@tekyzinc/gsd-t 3.29.11 → 4.0.14

package/bin/gsd-t-worker-dispatch.cjs

@@ -1,211 +0,0 @@
-#!/usr/bin/env node
-'use strict';
-
-/**
- * GSD-T Worker Sub-Dispatch (M46 D2 T2)
- *
- * Thin adapter that lets an unattended supervisor worker fan out its own
- * file-disjoint tasks by reusing the M44-verified `runDispatch` instrument.
- * This module is a new CONSUMER of `bin/gsd-t-parallel.cjs::runDispatch` —
- * not a modifier. The in-session dispatch path is byte-identical post-D2.
- *
- * Contract: .gsd-t/contracts/headless-default-contract.md v2.1.0 §Worker Sub-Dispatch
- *
- * Public API:
- *   dispatchWorkerTasks({projectDir, parentSessionId, tasks, maxParallel})
- *     → { parallel, taskResults, wallClockMs, reason }
- *
- * Triggers sub-dispatch when all hold:
- *   - tasks.length > 1
- *   - tasks are file-disjoint (pairwise no overlap on `task.files`)
- * Otherwise returns `{parallel: false, …}` and the caller falls through to
- * its current serial behavior.
- */
-
-const path = require('path');
-
-const SPAWN_PLAN_KIND = 'unattended-worker-sub';
-const DEFAULT_MAX_PARALLEL = 4;
-
-/**
- * Pairwise file-disjointness across a task set. Returns true iff no two
- * tasks share any file in their `files` arrays. Tasks without a `files`
- * array (or empty) are treated as having no declared file scope and
- * therefore never overlap with anyone — callers upstream should not
- * pass such tasks to sub-dispatch, but we remain conservative: a task
- * with no `files` is considered disjoint from every other task only
- * when every counterpart also has files declared. When both sides lack
- * `files`, we conservatively report NOT disjoint so the caller falls
- * back to serial — an undeclared scope is an unknown scope.
- */
-function _areFileDisjoint(tasks) {
-  if (!Array.isArray(tasks) || tasks.length < 2) return true;
-  for (let i = 0; i < tasks.length; i++) {
-    const a = tasks[i];
-    const aFiles = (a && Array.isArray(a.files)) ? a.files : null;
-    for (let j = i + 1; j < tasks.length; j++) {
-      const b = tasks[j];
-      const bFiles = (b && Array.isArray(b.files)) ? b.files : null;
-      if (!aFiles || !bFiles) return false;
-      const set = new Set(aFiles);
-      for (const f of bFiles) {
-        if (set.has(f)) return false;
-      }
-    }
-  }
-  return true;
-}
-
-/**
- * Emit a spawn-plan frame for this sub-dispatch. Best-effort; writer
- * failures never propagate (per spawn-plan-writer.cjs §Hard rules).
- */
-function _writeSubDispatchSpawnPlan({ projectDir, parentSessionId, tasks }) {
-  try {
-    const writer = require(path.join(__dirname, 'spawn-plan-writer.cjs'));
-    const spawnId = `worker-sub-${parentSessionId}-${Date.now()}`;
-    const planTasks = tasks.map((t) => ({
-      id: (t && typeof t.taskId === 'string') ? t.taskId : String((t && t.taskId) || ''),
-      title: (t && typeof t.title === 'string') ? t.title : '',
-      status: 'pending',
-    }));
-    writer.writeSpawnPlan({
-      spawnId,
-      kind: SPAWN_PLAN_KIND,
-      projectDir,
-      tasks: planTasks,
-    });
-  } catch (_e) {
-    /* best-effort; never block dispatch */
-  }
-}
-
-/**
- * dispatchWorkerTasks — the M46 D2 sub-dispatch entry point.
- *
- * @param {object}   opts
- * @param {string}   opts.projectDir        absolute project root
- * @param {string}   opts.parentSessionId   $GSD_T_PARENT_AGENT_ID from worker env
- * @param {Array}    opts.tasks             [{taskId, files, command, ...}]
- * @param {number}   [opts.maxParallel=4]   concurrency cap (default matches M44)
- * @returns {Promise<{parallel: boolean, taskResults: Array, wallClockMs: number, reason: string}>}
- */
-async function dispatchWorkerTasks(opts) {
-  const projectDir = (opts && opts.projectDir) || process.cwd();
-  const parentSessionId = (opts && opts.parentSessionId) || '';
-  const tasks = (opts && Array.isArray(opts.tasks)) ? opts.tasks : [];
-  const maxParallel = Number.isFinite(opts && opts.maxParallel) && opts.maxParallel > 0
-    ? Math.floor(opts.maxParallel)
-    : DEFAULT_MAX_PARALLEL;
-
-  if (tasks.length === 0) {
-    return { parallel: false, taskResults: [], wallClockMs: 0, reason: 'no-tasks' };
-  }
-  if (tasks.length === 1) {
-    return { parallel: false, taskResults: [], wallClockMs: 0, reason: 'single-task' };
-  }
-  if (!_areFileDisjoint(tasks)) {
-    return { parallel: false, taskResults: [], wallClockMs: 0, reason: 'file-overlap' };
-  }
-
-  _writeSubDispatchSpawnPlan({ projectDir, parentSessionId, tasks });
-
-  const startedAt = Date.now();
-  try {
-    const parallel = require(path.join(__dirname, 'gsd-t-parallel.cjs'));
-    const result = await parallel.runDispatch({
-      projectDir,
-      tasks,
-      maxWorkers: maxParallel,
-      mode: 'worker-subdispatch',
-    });
-    const wallClockMs = Date.now() - startedAt;
-    const taskResults = (result && Array.isArray(result.workerResults))
-      ? result.workerResults
-      : (result && Array.isArray(result.taskResults) ? result.taskResults : []);
-    return {
-      parallel: true,
-      taskResults,
-      wallClockMs,
-      reason: 'dispatched',
-    };
-  } catch (e) {
-    const wallClockMs = Date.now() - startedAt;
-    const msg = (e && e.message) ? e.message : String(e);
-    return {
-      parallel: false,
-      taskResults: [],
-      wallClockMs,
-      reason: `dispatch-error: ${msg}`,
-    };
-  }
-}
-
-module.exports = {
-  dispatchWorkerTasks,
-  _areFileDisjoint,
-  SPAWN_PLAN_KIND,
-};
-
-if (require.main === module) {
-  (async () => {
-    const fs = require('fs');
-    const argv = process.argv.slice(2);
-    let parentSessionId = null;
-    let tasksPath = null;
-    let maxParallel = DEFAULT_MAX_PARALLEL;
-    for (let i = 0; i < argv.length; i++) {
-      const a = argv[i];
-      if (a === '--parent-session') {
-        parentSessionId = argv[++i];
-      } else if (a === '--tasks') {
-        tasksPath = argv[++i];
-      } else if (a === '--max-parallel') {
-        const n = parseInt(argv[++i], 10);
-        if (Number.isFinite(n) && n > 0) maxParallel = n;
-      }
-    }
-    if (!parentSessionId) {
-      process.stderr.write('error: --parent-session required\n');
-      process.exit(2);
-    }
-    if (!tasksPath) {
-      process.stderr.write('error: --tasks required\n');
-      process.exit(2);
-    }
-    let raw;
-    try {
-      raw = fs.readFileSync(tasksPath, 'utf8');
-    } catch (e) {
-      process.stderr.write(`error: cannot read tasks file ${tasksPath}: ${(e && e.message) || e}\n`);
-      process.exit(2);
-    }
-    let tasks;
-    try {
-      tasks = JSON.parse(raw);
-    } catch (e) {
-      process.stderr.write(`error: malformed tasks JSON: ${(e && e.message) || e}\n`);
-      process.exit(2);
-    }
-    if (!Array.isArray(tasks)) {
-      process.stderr.write('error: tasks JSON must be an array\n');
-      process.exit(2);
-    }
-    const projectDir = process.cwd();
-    try {
-      const result = await dispatchWorkerTasks({
-        projectDir,
-        parentSessionId,
-        tasks,
-        maxParallel,
-      });
-      process.stdout.write(JSON.stringify(result) + '\n');
-      const anyFailed = Array.isArray(result && result.taskResults)
-        && result.taskResults.some((r) => r && (r.exitCode !== 0 && r.exitCode != null));
-      process.exit(anyFailed ? 1 : 0);
-    } catch (e) {
-      process.stderr.write(`error: dispatch threw: ${(e && e.message) || e}\n`);
-      process.exit(1);
-    }
-  })();
-}

package/bin/handoff-lock.cjs

@@ -1,249 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * GSD-T Handoff Lock — Fail-safe sentinel preventing parent/child race
- * conditions in `autoSpawnHeadless()`.
- *
- * Problem: when the interactive parent spawns a detached headless child to
- * resume a session, both processes may briefly contend for the continue-here
- * file and session JSON. If the child wakes and reads before the parent has
- * finished writing, it sees stale or partial state.
- *
- * Solution: the parent acquires a short-lived lock on
- * `.gsd-t/.handoff/lock-{sessionId}` BEFORE writing handoff artifacts and
- * releases it AFTER `child.unref()` returns. The child waits on the same
- * lock path before reading the continue-here file.
- *
- * Locks are TTL-bounded (default 30s) so a crashed parent can never wedge
- * a future spawn — `cleanStaleLocks()` swept by housekeeping or by the next
- * acquire attempt against an expired record reclaims the slot.
- *
- * Zero external dependencies (Node.js built-ins only).
- *
- * Contract: .gsd-t/contracts/headless-auto-spawn-contract.md v1.0.0
- *           (implementation-detail primitive; no contract bump)
- * Consumers: bin/headless-auto-spawn.js (Task 2 — wires this in),
- *            commands/gsd-t-resume.md (child-side wait).
- */
-
-const fs = require("fs");
-const path = require("path");
-
-// ── Constants ────────────────────────────────────────────────────────────────
-
-const HANDOFF_DIR_REL = path.join(".gsd-t", ".handoff");
-const LOCK_FILE_PREFIX = "lock-";
-const DEFAULT_TTL_MS = 30000;
-const DEFAULT_WAIT_TIMEOUT_MS = 30000;
-const DEFAULT_STALE_AGE_MS = 60000;
-const POLL_INTERVAL_MS = 100;
-const GRACE_MS = 500;
-
-// ── Exports ──────────────────────────────────────────────────────────────────
-
-module.exports = {
-  acquireHandoffLock,
-  releaseHandoffLock,
-  waitForLockRelease,
-  cleanStaleLocks,
-  // Exported for tests / consumer wiring:
-  lockPathFor,
-  HANDOFF_DIR_REL,
-};
-
-// ── acquireHandoffLock ───────────────────────────────────────────────────────
-
-/**
- * Acquire an exclusive handoff lock for the given sessionId.
- *
- * @param {string} projectDir
- * @param {string} sessionId
- * @param {{ ttlMs?: number }} [opts]
- * @returns {{ lockPath: string, sessionId: string }} release handle
- * @throws {Error} if an unexpired lock already exists
- */
-function acquireHandoffLock(projectDir, sessionId, opts) {
-  if (!projectDir || typeof projectDir !== "string") {
-    throw new Error("acquireHandoffLock: `projectDir` is required");
-  }
-  if (!sessionId || typeof sessionId !== "string") {
-    throw new Error("acquireHandoffLock: `sessionId` is required");
-  }
-  const ttlMs = (opts && opts.ttlMs) || DEFAULT_TTL_MS;
-
-  const dir = path.join(projectDir, HANDOFF_DIR_REL);
-  ensureDir(dir);
-
-  const lockPath = lockPathFor(projectDir, sessionId);
-
-  // If a lock file already exists, decide whether it is still binding.
-  if (fs.existsSync(lockPath)) {
-    const existing = readLockSafe(lockPath);
-    const now = Date.now();
-    if (existing && now < existing.releaseBy + GRACE_MS) {
-      throw new Error(
-        `handoff lock held by PID ${existing.parentPid} until ${new Date(
-          existing.releaseBy,
-        ).toISOString()}`,
-      );
-    }
-    // Expired or unparseable — reclaim it.
-    try {
-      fs.unlinkSync(lockPath);
-    } catch (_) {
-      /* race: someone else cleaned it; fall through */
-    }
-  }
-
-  const acquiredAt = Date.now();
-  const record = {
-    sessionId,
-    parentPid: process.pid,
-    acquiredAt,
-    releaseBy: acquiredAt + ttlMs,
-  };
-
-  // Write atomically: O_EXCL ensures we lose if a concurrent acquirer beats
-  // us between the existsSync check above and this write.
-  let fd;
-  try {
-    fd = fs.openSync(lockPath, "wx");
-  } catch (e) {
-    if (e && e.code === "EEXIST") {
-      // Another acquirer raced ahead; surface a uniform error.
-      const existing = readLockSafe(lockPath);
-      const pid = existing ? existing.parentPid : "unknown";
-      const until = existing
-        ? new Date(existing.releaseBy).toISOString()
-        : "unknown";
-      throw new Error(`handoff lock held by PID ${pid} until ${until}`);
-    }
-    throw e;
-  }
-  try {
-    fs.writeSync(fd, JSON.stringify(record, null, 2) + "\n");
-  } finally {
-    fs.closeSync(fd);
-  }
-
-  return { lockPath, sessionId };
-}
-
-// ── releaseHandoffLock ───────────────────────────────────────────────────────
-
-/**
- * Release a previously acquired handoff lock. Idempotent — tolerates a
- * missing file (already released or never existed).
- *
- * @param {{ lockPath: string, sessionId: string }} handle
- */
-function releaseHandoffLock(handle) {
-  if (!handle || !handle.lockPath) return;
-  try {
-    fs.unlinkSync(handle.lockPath);
-  } catch (e) {
-    if (e && e.code === "ENOENT") return; // already released
-    throw e;
-  }
-}
-
-// ── waitForLockRelease ───────────────────────────────────────────────────────
-
-/**
- * Poll until the lock file for {sessionId} no longer exists, OR until
- * timeoutMs elapses. Throws on timeout.
- *
- * @param {string} projectDir
- * @param {string} sessionId
- * @param {number} [timeoutMs]
- * @returns {Promise<true>}
- */
-function waitForLockRelease(projectDir, sessionId, timeoutMs) {
-  const limit = typeof timeoutMs === "number" ? timeoutMs : DEFAULT_WAIT_TIMEOUT_MS;
-  const lockPath = lockPathFor(projectDir, sessionId);
-  const start = Date.now();
-
-  return new Promise((resolve, reject) => {
-    const check = () => {
-      if (!fs.existsSync(lockPath)) {
-        resolve(true);
-        return;
-      }
-      if (Date.now() - start >= limit) {
-        reject(new Error(`waitForLockRelease timeout after ${limit}ms`));
-        return;
-      }
-      setTimeout(check, POLL_INTERVAL_MS);
-    };
-    check();
-  });
-}
-
-// ── cleanStaleLocks ──────────────────────────────────────────────────────────
-
-/**
- * Sweep `.gsd-t/.handoff/` and remove any `lock-*` file whose `acquiredAt`
- * is older than `maxAgeMs`. Returns the count of files removed.
- *
- * @param {string} projectDir
- * @param {number} [maxAgeMs]
- * @returns {number}
- */
-function cleanStaleLocks(projectDir, maxAgeMs) {
-  const limit = typeof maxAgeMs === "number" ? maxAgeMs : DEFAULT_STALE_AGE_MS;
-  const dir = path.join(projectDir, HANDOFF_DIR_REL);
-  if (!fs.existsSync(dir)) return 0;
-
-  let removed = 0;
-  let entries;
-  try {
-    entries = fs.readdirSync(dir);
-  } catch (_) {
-    return 0;
-  }
-  const now = Date.now();
-  for (const name of entries) {
-    if (!name.startsWith(LOCK_FILE_PREFIX)) continue;
-    const fp = path.join(dir, name);
-    const rec = readLockSafe(fp);
-    // Unparseable lock files are treated as stale — they're not protecting
-    // anything, and leaving them around defeats the cleaner.
-    if (!rec || now - rec.acquiredAt > limit) {
-      try {
-        fs.unlinkSync(fp);
-        removed++;
-      } catch (_) {
-        /* ignore */
-      }
-    }
-  }
-  return removed;
-}
-
-// ── Helpers ──────────────────────────────────────────────────────────────────
-
-function lockPathFor(projectDir, sessionId) {
-  return path.join(projectDir, HANDOFF_DIR_REL, `${LOCK_FILE_PREFIX}${sessionId}`);
-}
-
-function readLockSafe(fp) {
-  try {
-    const raw = fs.readFileSync(fp, "utf8");
-    const j = JSON.parse(raw);
-    if (
-      typeof j === "object" &&
-      j &&
-      typeof j.acquiredAt === "number" &&
-      typeof j.releaseBy === "number"
-    ) {
-      return j;
-    }
-    return null;
-  } catch (_) {
-    return null;
-  }
-}
-
-function ensureDir(d) {
-  if (!fs.existsSync(d)) fs.mkdirSync(d, { recursive: true });
-}

package/bin/handoff-lock.js

@@ -1,249 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * GSD-T Handoff Lock — Fail-safe sentinel preventing parent/child race
- * conditions in `autoSpawnHeadless()`.
- *
- * Problem: when the interactive parent spawns a detached headless child to
- * resume a session, both processes may briefly contend for the continue-here
- * file and session JSON. If the child wakes and reads before the parent has
- * finished writing, it sees stale or partial state.
- *
- * Solution: the parent acquires a short-lived lock on
- * `.gsd-t/.handoff/lock-{sessionId}` BEFORE writing handoff artifacts and
- * releases it AFTER `child.unref()` returns. The child waits on the same
- * lock path before reading the continue-here file.
- *
- * Locks are TTL-bounded (default 30s) so a crashed parent can never wedge
- * a future spawn — `cleanStaleLocks()` swept by housekeeping or by the next
- * acquire attempt against an expired record reclaims the slot.
- *
- * Zero external dependencies (Node.js built-ins only).
- *
- * Contract: .gsd-t/contracts/headless-auto-spawn-contract.md v1.0.0
- *           (implementation-detail primitive; no contract bump)
- * Consumers: bin/headless-auto-spawn.js (Task 2 — wires this in),
- *            commands/gsd-t-resume.md (child-side wait).
- */
-
-const fs = require("fs");
-const path = require("path");
-
-// ── Constants ────────────────────────────────────────────────────────────────
-
-const HANDOFF_DIR_REL = path.join(".gsd-t", ".handoff");
-const LOCK_FILE_PREFIX = "lock-";
-const DEFAULT_TTL_MS = 30000;
-const DEFAULT_WAIT_TIMEOUT_MS = 30000;
-const DEFAULT_STALE_AGE_MS = 60000;
-const POLL_INTERVAL_MS = 100;
-const GRACE_MS = 500;
-
-// ── Exports ──────────────────────────────────────────────────────────────────
-
-module.exports = {
-  acquireHandoffLock,
-  releaseHandoffLock,
-  waitForLockRelease,
-  cleanStaleLocks,
-  // Exported for tests / consumer wiring:
-  lockPathFor,
-  HANDOFF_DIR_REL,
-};
-
-// ── acquireHandoffLock ───────────────────────────────────────────────────────
-
-/**
- * Acquire an exclusive handoff lock for the given sessionId.
- *
- * @param {string} projectDir
- * @param {string} sessionId
- * @param {{ ttlMs?: number }} [opts]
- * @returns {{ lockPath: string, sessionId: string }} release handle
- * @throws {Error} if an unexpired lock already exists
- */
-function acquireHandoffLock(projectDir, sessionId, opts) {
-  if (!projectDir || typeof projectDir !== "string") {
-    throw new Error("acquireHandoffLock: `projectDir` is required");
-  }
-  if (!sessionId || typeof sessionId !== "string") {
-    throw new Error("acquireHandoffLock: `sessionId` is required");
-  }
-  const ttlMs = (opts && opts.ttlMs) || DEFAULT_TTL_MS;
-
-  const dir = path.join(projectDir, HANDOFF_DIR_REL);
-  ensureDir(dir);
-
-  const lockPath = lockPathFor(projectDir, sessionId);
-
-  // If a lock file already exists, decide whether it is still binding.
-  if (fs.existsSync(lockPath)) {
-    const existing = readLockSafe(lockPath);
-    const now = Date.now();
-    if (existing && now < existing.releaseBy + GRACE_MS) {
-      throw new Error(
-        `handoff lock held by PID ${existing.parentPid} until ${new Date(
-          existing.releaseBy,
-        ).toISOString()}`,
-      );
-    }
-    // Expired or unparseable — reclaim it.
-    try {
-      fs.unlinkSync(lockPath);
-    } catch (_) {
-      /* race: someone else cleaned it; fall through */
-    }
-  }
-
-  const acquiredAt = Date.now();
-  const record = {
-    sessionId,
-    parentPid: process.pid,
-    acquiredAt,
-    releaseBy: acquiredAt + ttlMs,
-  };
-
-  // Write atomically: O_EXCL ensures we lose if a concurrent acquirer beats
-  // us between the existsSync check above and this write.
-  let fd;
-  try {
-    fd = fs.openSync(lockPath, "wx");
-  } catch (e) {
-    if (e && e.code === "EEXIST") {
-      // Another acquirer raced ahead; surface a uniform error.
-      const existing = readLockSafe(lockPath);
-      const pid = existing ? existing.parentPid : "unknown";
-      const until = existing
-        ? new Date(existing.releaseBy).toISOString()
-        : "unknown";
-      throw new Error(`handoff lock held by PID ${pid} until ${until}`);
-    }
-    throw e;
-  }
-  try {
-    fs.writeSync(fd, JSON.stringify(record, null, 2) + "\n");
-  } finally {
-    fs.closeSync(fd);
-  }
-
-  return { lockPath, sessionId };
-}
-
-// ── releaseHandoffLock ───────────────────────────────────────────────────────
-
-/**
- * Release a previously acquired handoff lock. Idempotent — tolerates a
- * missing file (already released or never existed).
- *
- * @param {{ lockPath: string, sessionId: string }} handle
- */
-function releaseHandoffLock(handle) {
-  if (!handle || !handle.lockPath) return;
-  try {
-    fs.unlinkSync(handle.lockPath);
-  } catch (e) {
-    if (e && e.code === "ENOENT") return; // already released
-    throw e;
-  }
-}
-
-// ── waitForLockRelease ───────────────────────────────────────────────────────
-
-/**
- * Poll until the lock file for {sessionId} no longer exists, OR until
- * timeoutMs elapses. Throws on timeout.
- *
- * @param {string} projectDir
- * @param {string} sessionId
- * @param {number} [timeoutMs]
- * @returns {Promise<true>}
- */
-function waitForLockRelease(projectDir, sessionId, timeoutMs) {
-  const limit = typeof timeoutMs === "number" ? timeoutMs : DEFAULT_WAIT_TIMEOUT_MS;
-  const lockPath = lockPathFor(projectDir, sessionId);
-  const start = Date.now();
-
-  return new Promise((resolve, reject) => {
-    const check = () => {
-      if (!fs.existsSync(lockPath)) {
-        resolve(true);
-        return;
-      }
-      if (Date.now() - start >= limit) {
-        reject(new Error(`waitForLockRelease timeout after ${limit}ms`));
-        return;
-      }
-      setTimeout(check, POLL_INTERVAL_MS);
-    };
-    check();
-  });
-}
-
-// ── cleanStaleLocks ──────────────────────────────────────────────────────────
-
-/**
- * Sweep `.gsd-t/.handoff/` and remove any `lock-*` file whose `acquiredAt`
- * is older than `maxAgeMs`. Returns the count of files removed.
- *
- * @param {string} projectDir
- * @param {number} [maxAgeMs]
- * @returns {number}
- */
-function cleanStaleLocks(projectDir, maxAgeMs) {
-  const limit = typeof maxAgeMs === "number" ? maxAgeMs : DEFAULT_STALE_AGE_MS;
-  const dir = path.join(projectDir, HANDOFF_DIR_REL);
-  if (!fs.existsSync(dir)) return 0;
-
-  let removed = 0;
-  let entries;
-  try {
-    entries = fs.readdirSync(dir);
-  } catch (_) {
-    return 0;
-  }
-  const now = Date.now();
-  for (const name of entries) {
-    if (!name.startsWith(LOCK_FILE_PREFIX)) continue;
-    const fp = path.join(dir, name);
-    const rec = readLockSafe(fp);
-    // Unparseable lock files are treated as stale — they're not protecting
-    // anything, and leaving them around defeats the cleaner.
-    if (!rec || now - rec.acquiredAt > limit) {
-      try {
-        fs.unlinkSync(fp);
-        removed++;
-      } catch (_) {
-        /* ignore */
-      }
-    }
-  }
-  return removed;
-}
-
-// ── Helpers ──────────────────────────────────────────────────────────────────
-
-function lockPathFor(projectDir, sessionId) {
-  return path.join(projectDir, HANDOFF_DIR_REL, `${LOCK_FILE_PREFIX}${sessionId}`);
-}
-
-function readLockSafe(fp) {
-  try {
-    const raw = fs.readFileSync(fp, "utf8");
-    const j = JSON.parse(raw);
-    if (
-      typeof j === "object" &&
-      j &&
-      typeof j.acquiredAt === "number" &&
-      typeof j.releaseBy === "number"
-    ) {
-      return j;
-    }
-    return null;
-  } catch (_) {
-    return null;
-  }
-}
-
-function ensureDir(d) {
-  if (!fs.existsSync(d)) fs.mkdirSync(d, { recursive: true });
-}