@cohortapp/agent-sdk 2.3.0

package/lib/setup/sot.test.mjs

@@ -0,0 +1,81 @@
+/**
+ * sot.test.mjs — single-source-of-truth helper tests (lib/setup/sot.mjs).
+ * Covers wrapper generation idempotency + agent.json merge keeping unrelated keys.
+ * Run: `node --test lib/setup/sot.test.mjs`
+ * @module lib/setup/sot.test
+ */
+
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, writeFileSync, mkdirSync, readFileSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  readAgentJson, writeAgentJson, mergeAgentJson, deepMergeByKey,
+  ensureSotWrapper, isWrapper, agentTsPath, WRAPPER_TEMPLATE,
+} from "./sot.mjs";
+
+function tmpRoot() {
+  const r = mkdtempSync(join(tmpdir(), "maestro-sot-"));
+  mkdirSync(join(r, "config"), { recursive: true });
+  return r;
+}
+
+test("readAgentJson returns null when missing, object when present", () => {
+  const root = tmpRoot();
+  assert.equal(readAgentJson(root), null);
+  writeAgentJson(root, { firstName: "Jo" });
+  assert.deepEqual(readAgentJson(root), { firstName: "Jo" });
+});
+
+test("deepMergeByKey preserves unrelated keys and deep-merges objects", () => {
+  const base = { a: 1, nested: { x: 1, y: 2 }, arr: [1, 2] };
+  const patch = { nested: { y: 9, z: 3 }, arr: [3] };
+  const out = deepMergeByKey(base, patch);
+  assert.deepEqual(out, { a: 1, nested: { x: 1, y: 9, z: 3 }, arr: [3] });
+  // inputs not mutated
+  assert.deepEqual(base.nested, { x: 1, y: 2 });
+});
+
+test("mergeAgentJson keeps unrelated fields (split-brain guard)", () => {
+  const root = tmpRoot();
+  writeAgentJson(root, {
+    firstName: "OLD", title: "Role",
+    principal: { fullName: "P One", email: "p@x.com" },
+    responsibilities: ["a"],
+  });
+  mergeAgentJson(root, { firstName: "NEW", principal: { email: "p2@x.com" } });
+  const back = readAgentJson(root);
+  assert.equal(back.firstName, "NEW");
+  assert.equal(back.title, "Role", "unrelated key preserved");
+  assert.equal(back.principal.fullName, "P One", "nested unrelated key preserved");
+  assert.equal(back.principal.email, "p2@x.com", "nested key updated");
+  assert.deepEqual(back.responsibilities, ["a"], "array preserved");
+});
+
+test("isWrapper distinguishes wrapper from standalone literal", () => {
+  assert.equal(isWrapper(WRAPPER_TEMPLATE), true);
+  const standalone = `export const agent = {\n  firstName: 'Ravi',\n} as const;\n`;
+  assert.equal(isWrapper(standalone), false);
+  assert.equal(isWrapper("nonsense"), false);
+});
+
+test("ensureSotWrapper writes wrapper when absent and is idempotent", () => {
+  const root = tmpRoot();
+  const first = ensureSotWrapper(root);
+  assert.equal(first.wrote, true);
+  assert.ok(existsSync(agentTsPath(root)));
+  assert.ok(isWrapper(readFileSync(agentTsPath(root), "utf-8")));
+  const second = ensureSotWrapper(root);
+  assert.equal(second.wrote, false, "second call is a no-op");
+});
+
+test("ensureSotWrapper replaces a standalone literal .ts", () => {
+  const root = tmpRoot();
+  writeFileSync(agentTsPath(root), `export const agent = { firstName: 'Ravi' } as const;\n`);
+  const r = ensureSotWrapper(root);
+  assert.equal(r.wrote, true);
+  assert.ok(isWrapper(readFileSync(agentTsPath(root), "utf-8")));
+});

package/lib/setup/state.mjs

@@ -0,0 +1,151 @@
+/**
+ * lib/setup/state.mjs — durable checkpoint store for the `maestro setup` wizard.
+ *
+ * Persists to `state/setup/progress.json`. The checkpoint is a *hint*: on resume
+ * the runner re-`detect`s every section (the on-disk SoT is authoritative), but
+ * the checkpoint records what was applied, when, the verify result, and a hash
+ * of the answers that produced it (so a changed answer invalidates the skip).
+ *
+ * Schema (per §1 wizard / §4 design):
+ *   {
+ *     version: 1,
+ *     updatedAt: ISO,
+ *     answers: { ...durable answers across sections },
+ *     sections: {
+ *       <id>: { status, applied_at, verify, answersHash }
+ *     },
+ *     enrich: { <fieldUnit>: { status, at, reason? } }   // enrichment ledger
+ *   }
+ *
+ * Atomic writes (tmp + rename). Fail-soft on read (bad/missing file → fresh
+ * empty progress) so a corrupt checkpoint never blocks setup.
+ *
+ * @module lib/setup/state
+ */
+
+"use strict";
+
+import { existsSync, readFileSync, writeFileSync, renameSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { createHash } from "node:crypto";
+
+export const PROGRESS_REL = "state/setup/progress.json";
+export const SCHEMA_VERSION = 1;
+
+/** Absolute path to the progress file for an agent root. */
+export function progressPath(agentRoot) {
+  return join(agentRoot, PROGRESS_REL);
+}
+
+/** A fresh, empty progress object. */
+export function emptyProgress() {
+  return {
+    version: SCHEMA_VERSION,
+    updatedAt: null,
+    answers: {},
+    sections: {},
+    enrich: {},
+  };
+}
+
+/**
+ * Stable hash of an answers object (order-independent). Used to detect when a
+ * section's inputs changed so a previously-complete section is re-run.
+ * @param {object} answers
+ * @returns {string} 16-char hex digest
+ */
+export function hashAnswers(answers) {
+  const canonical = canonicalize(answers == null ? {} : answers);
+  return createHash("sha256").update(canonical).digest("hex").slice(0, 16);
+}
+
+function canonicalize(value) {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(canonicalize).join(",")}]`;
+  const keys = Object.keys(value).sort();
+  return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalize(value[k])}`).join(",")}}`;
+}
+
+/**
+ * Load the checkpoint for an agent root, returning a fresh empty progress when
+ * the file is missing or unreadable/corrupt (never throws).
+ * @param {string} agentRoot
+ * @returns {object}
+ */
+export function loadProgress(agentRoot) {
+  const p = progressPath(agentRoot);
+  if (!existsSync(p)) return emptyProgress();
+  try {
+    const raw = JSON.parse(readFileSync(p, "utf-8"));
+    if (!raw || typeof raw !== "object") return emptyProgress();
+    return {
+      version: raw.version || SCHEMA_VERSION,
+      updatedAt: raw.updatedAt || null,
+      answers: raw.answers && typeof raw.answers === "object" ? raw.answers : {},
+      sections: raw.sections && typeof raw.sections === "object" ? raw.sections : {},
+      enrich: raw.enrich && typeof raw.enrich === "object" ? raw.enrich : {},
+    };
+  } catch {
+    return emptyProgress();
+  }
+}
+
+/**
+ * Atomically persist a progress object. Stamps `updatedAt`.
+ * @param {string} agentRoot
+ * @param {object} progress
+ */
+export function saveProgress(agentRoot, progress) {
+  const p = progressPath(agentRoot);
+  mkdirSync(dirname(p), { recursive: true });
+  const body = { ...emptyProgress(), ...progress, version: SCHEMA_VERSION, updatedAt: new Date().toISOString() };
+  const tmp = `${p}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(tmp, JSON.stringify(body, null, 2) + "\n", "utf-8");
+  renameSync(tmp, p);
+  return body;
+}
+
+/**
+ * Record a section's status into the checkpoint and persist atomically.
+ * Returns the updated progress object.
+ * @param {string} agentRoot
+ * @param {string} sectionId
+ * @param {{status:string, verify?:object, answersHash?:string, answers?:object}} patch
+ */
+export function markSection(agentRoot, sectionId, patch = {}) {
+  const progress = loadProgress(agentRoot);
+  const prev = progress.sections[sectionId] || {};
+  progress.sections[sectionId] = {
+    status: patch.status || prev.status || "unknown",
+    applied_at: patch.status ? new Date().toISOString() : prev.applied_at || null,
+    verify: patch.verify !== undefined ? patch.verify : prev.verify || null,
+    answersHash: patch.answersHash !== undefined ? patch.answersHash : prev.answersHash || null,
+  };
+  if (patch.answers && typeof patch.answers === "object") {
+    progress.answers = { ...progress.answers, ...patch.answers };
+  }
+  return saveProgress(agentRoot, progress);
+}
+
+/**
+ * Record an enrichment unit outcome in the ledger.
+ * @param {string} agentRoot
+ * @param {string} unit  enrichable field id (e.g. "agent.persona")
+ * @param {{status:'enriched'|'pending'|'skipped', reason?:string}} patch
+ */
+export function markEnrich(agentRoot, unit, patch = {}) {
+  const progress = loadProgress(agentRoot);
+  progress.enrich[unit] = {
+    status: patch.status || "pending",
+    at: new Date().toISOString(),
+    ...(patch.reason ? { reason: patch.reason } : {}),
+  };
+  return saveProgress(agentRoot, progress);
+}
+
+/** Merge durable answers into the checkpoint (no section change). */
+export function mergeAnswers(agentRoot, answers) {
+  const progress = loadProgress(agentRoot);
+  progress.answers = { ...progress.answers, ...(answers || {}) };
+  return saveProgress(agentRoot, progress);
+}

package/lib/setup/state.test.mjs

@@ -0,0 +1,92 @@
+/**
+ * state.test.mjs — checkpoint round-trip / resume tests for lib/setup/state.mjs.
+ * Run: `node --test lib/setup/state.test.mjs`
+ * @module lib/setup/state.test
+ */
+
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, writeFileSync, mkdirSync, existsSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  loadProgress, saveProgress, markSection, markEnrich, mergeAnswers,
+  hashAnswers, progressPath, emptyProgress,
+} from "./state.mjs";
+
+function tmpRoot() {
+  return mkdtempSync(join(tmpdir(), "maestro-state-"));
+}
+
+test("loadProgress returns empty progress for a fresh root", () => {
+  const root = tmpRoot();
+  const p = loadProgress(root);
+  assert.equal(p.version, 1);
+  assert.deepEqual(p.sections, {});
+  assert.deepEqual(p.answers, {});
+});
+
+test("saveProgress + loadProgress round-trip with atomic write", () => {
+  const root = tmpRoot();
+  const p = emptyProgress();
+  p.answers.firstName = "Jacob";
+  saveProgress(root, p);
+  assert.ok(existsSync(progressPath(root)), "progress.json must exist");
+  const back = loadProgress(root);
+  assert.equal(back.answers.firstName, "Jacob");
+  assert.ok(back.updatedAt, "updatedAt stamped");
+});
+
+test("markSection records status + applied_at and persists", () => {
+  const root = tmpRoot();
+  markSection(root, "identity", { status: "complete", answersHash: "abc123", verify: { ok: true } });
+  const p = loadProgress(root);
+  assert.equal(p.sections.identity.status, "complete");
+  assert.equal(p.sections.identity.answersHash, "abc123");
+  assert.deepEqual(p.sections.identity.verify, { ok: true });
+  assert.ok(p.sections.identity.applied_at);
+});
+
+test("markSection merges durable answers", () => {
+  const root = tmpRoot();
+  markSection(root, "identity", { status: "complete", answers: { firstName: "Mara" } });
+  markSection(root, "company", { status: "complete", answers: { company: "Acme" } });
+  const p = loadProgress(root);
+  assert.equal(p.answers.firstName, "Mara");
+  assert.equal(p.answers.company, "Acme");
+});
+
+test("hashAnswers is order-independent and changes with content", () => {
+  const a = hashAnswers({ x: 1, y: 2 });
+  const b = hashAnswers({ y: 2, x: 1 });
+  const c = hashAnswers({ x: 1, y: 3 });
+  assert.equal(a, b, "key order must not matter");
+  assert.notEqual(a, c, "content change must change hash");
+});
+
+test("markEnrich records ledger entries", () => {
+  const root = tmpRoot();
+  markEnrich(root, "agent.persona", { status: "pending", reason: "llm failed" });
+  const p = loadProgress(root);
+  assert.equal(p.enrich["agent.persona"].status, "pending");
+  assert.equal(p.enrich["agent.persona"].reason, "llm failed");
+});
+
+test("corrupt progress file falls back to empty (never throws)", () => {
+  const root = tmpRoot();
+  mkdirSync(join(root, "state/setup"), { recursive: true });
+  writeFileSync(progressPath(root), "{ not json ");
+  const p = loadProgress(root);
+  assert.deepEqual(p.sections, {});
+});
+
+test("mergeAnswers updates without disturbing sections", () => {
+  const root = tmpRoot();
+  markSection(root, "identity", { status: "complete" });
+  mergeAnswers(root, { tone: "warm" });
+  const p = loadProgress(root);
+  assert.equal(p.answers.tone, "warm");
+  assert.equal(p.sections.identity.status, "complete");
+});

package/lib/singleton.js

@@ -0,0 +1,229 @@
+/**
+ * Maestro — Process Singleton Guard
+ *
+ * Prevents duplicate instances of long-running services (daemon, events
+ * server, huddle server, etc.). Uses PID files with stale detection.
+ *
+ * Usage:
+ *   import { acquireLock, releaseLock } from "@cohortapp/agent-sdk/lib/singleton.js";
+ *
+ *   // At startup:
+ *   if (!acquireLock("slack-events")) {
+ *     console.log("Already running — exiting");
+ *     process.exit(0);
+ *   }
+ *
+ *   // On shutdown:
+ *   process.on("SIGTERM", () => { releaseLock("slack-events"); process.exit(0); });
+ *
+ * @module singleton
+ */
+
+import { readFileSync, unlinkSync, existsSync, mkdirSync, openSync, writeSync, closeSync } from "node:fs";
+import { join } from "node:path";
+import { execFileSync } from "node:child_process";
+import { resolveAgentRoot } from "./agent-root.mjs";
+
+/**
+ * Resolve the process-locks directory.
+ *
+ * Resolved per call (not memoised at import) via the shared {@link resolveAgentRoot}
+ * so singleton honours the same AGENT_ROOT → AGENT_DIR → cwd precedence as the
+ * cadence bus, and so callers/tests that set the env after import are respected.
+ * Previously this read AGENT_ROOT once at import with no AGENT_DIR fallback,
+ * diverging from the bus and pinning the path to import-time cwd. (L5/L23)
+ *
+ * @returns {string} Absolute path to the process locks directory.
+ */
+function locksDir() {
+  return join(resolveAgentRoot(), "state", "locks", "process");
+}
+
+/**
+ * Attempt to acquire a singleton lock for a named service.
+ * Returns true if the lock was acquired (no other instance running).
+ * Returns false if another instance is already running.
+ *
+ * Handles stale PID files (process died without cleanup).
+ *
+ * @param {string} name - Service name (e.g., "slack-events", "daemon", "huddle-server")
+ * @returns {boolean}
+ */
+export function acquireLock(name) {
+  const dir = locksDir();
+  mkdirSync(dir, { recursive: true });
+  const pidFile = join(dir, `${name}.pid`);
+
+  // Atomic create-or-fail with O_EXCL ("wx"). The previous
+  // existsSync()-then-writeFileSync() was a check-then-act TOCTOU race: two
+  // services starting at the same instant could both pass the existsSync
+  // check and both "acquire" the lock, ending up with two daemons draining
+  // the same bus (double escalation, double side effects). With O_EXCL the
+  // kernel guarantees exactly one winner; the loser inspects the holder and
+  // reclaims only a genuinely stale lock, then retries once. (M9)
+  let acquired = false;
+  for (let attempt = 0; attempt < 2 && !acquired; attempt++) {
+    try {
+      const fd = openSync(pidFile, "wx");
+      // Store an identity token (process start time) alongside the PID so a
+      // future liveness check can distinguish "same process still alive" from
+      // "a different process happened to be assigned the same PID" — the
+      // classic PID-reuse-after-reboot false positive that would otherwise
+      // make a stale lock look alive and block startup forever. (L2)
+      writeSync(fd, serialiseHolder(process.pid, processIdentity(process.pid)));
+      closeSync(fd);
+      acquired = true;
+    } catch (err) {
+      if (err.code !== "EEXIST") throw err;
+      let holder = { pid: 0, identity: null };
+      try {
+        holder = parseHolder(readFileSync(pidFile, "utf8"));
+      } catch {
+        // Corrupt/unreadable PID file — treat as stale and reclaim below.
+      }
+      if (holder.pid && isHolderAlive(holder)) {
+        // Another instance is genuinely running.
+        return false;
+      }
+      // Stale (dead PID, recycled PID, or corrupt lock) — remove and retry once.
+      try { unlinkSync(pidFile); } catch { /* another start may have reclaimed it */ }
+    }
+  }
+  if (!acquired) return false;
+
+  // Register cleanup on exit
+  const cleanup = () => {
+    try { unlinkSync(pidFile); } catch { /* ignore */ }
+  };
+  process.on("exit", cleanup);
+  process.on("SIGINT", () => { cleanup(); process.exit(0); });
+  process.on("SIGTERM", () => { cleanup(); process.exit(0); });
+
+  return true;
+}
+
+/**
+ * Manually release a lock.
+ * @param {string} name
+ */
+export function releaseLock(name) {
+  const pidFile = join(locksDir(), `${name}.pid`);
+  try { unlinkSync(pidFile); } catch { /* ignore */ }
+}
+
+/**
+ * Check if a service is currently running.
+ * @param {string} name
+ * @returns {{ running: boolean, pid: number|null }}
+ */
+export function checkLock(name) {
+  const pidFile = join(locksDir(), `${name}.pid`);
+  if (!existsSync(pidFile)) return { running: false, pid: null };
+
+  try {
+    const holder = parseHolder(readFileSync(pidFile, "utf8"));
+    if (holder.pid && isHolderAlive(holder)) {
+      return { running: true, pid: holder.pid };
+    }
+    // Stale (dead PID, recycled PID, or corrupt lock) — clean up
+    try { unlinkSync(pidFile); } catch { /* ignore */ }
+    return { running: false, pid: null };
+  } catch {
+    return { running: false, pid: null };
+  }
+}
+
+/**
+ * Best-effort process identity token: the process start time as reported by
+ * `ps`. Two different processes that happen to share a PID (e.g. PID reuse
+ * after a reboot) will almost never share a start time, so comparing this on
+ * the liveness check turns a PID-reuse false positive into a correctly-detected
+ * stale lock. Best-effort by design: if `ps` is unavailable or the PID is gone,
+ * returns null and the caller falls back to a plain existence check. (L2)
+ *
+ * @param {number} pid
+ * @returns {string|null}
+ */
+function processIdentity(pid) {
+  if (!pid || pid <= 0) return null;
+  try {
+    // `ps -o lstart=` prints the process start time with no header. Stable for
+    // the life of the process; differs across PID reuse. execFileSync (not
+    // exec) avoids any shell. A non-existent PID exits non-zero -> caught.
+    const out = execFileSync("ps", ["-o", "lstart=", "-p", String(pid)], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+    return out || null;
+  } catch {
+    // ps unavailable (or PID gone) — best effort, no identity captured.
+    return null;
+  }
+}
+
+/**
+ * Serialise a lock holder to the on-disk format. Backwards compatible: a bare
+ * PID (no identity) is still a valid first line, so old lock files written by
+ * earlier versions parse fine.
+ *
+ * Format: line 1 = PID, line 2 (optional) = identity token.
+ *
+ * @param {number} pid
+ * @param {string|null} identity
+ * @returns {string}
+ */
+function serialiseHolder(pid, identity) {
+  return identity ? `${pid}\n${identity}` : String(pid);
+}
+
+/**
+ * Parse a lock file's contents into a holder record. Tolerates the legacy
+ * single-line (PID only) format as well as the PID + identity format.
+ *
+ * @param {string} raw
+ * @returns {{ pid: number, identity: string|null }}
+ */
+function parseHolder(raw) {
+  const lines = String(raw).split("\n");
+  const pid = parseInt((lines[0] || "").trim(), 10) || 0;
+  const identity = lines.length > 1 ? (lines.slice(1).join("\n").trim() || null) : null;
+  return { pid, identity };
+}
+
+/**
+ * Liveness check for a recorded lock holder, identity-aware.
+ *
+ * 1. If the PID is not alive at all -> not alive (stale).
+ * 2. If the lock recorded no identity (legacy file or ps was unavailable when
+ *    it was written) -> fall back to the plain PID existence result (no worse
+ *    than the historical behaviour).
+ * 3. If an identity was recorded, recompute the current identity for that PID
+ *    and require a match. A mismatch means the PID was recycled by a different
+ *    process, so the lock is stale and reclaimable. If we cannot recompute the
+ *    current identity (ps unavailable now), we err on the side of "alive" to
+ *    avoid evicting a real holder.
+ *
+ * @param {{ pid: number, identity: string|null }} holder
+ * @returns {boolean}
+ */
+function isHolderAlive(holder) {
+  if (!holder.pid || !isProcessRunning(holder.pid)) return false;
+  if (!holder.identity) return true; // legacy / no token recorded — best effort
+  const current = processIdentity(holder.pid);
+  if (current === null) return true; // can't verify now — don't evict a live holder
+  return current === holder.identity;
+}
+
+/**
+ * Check if a PID is still alive.
+ * @param {number} pid
+ * @returns {boolean}
+ */
+function isProcessRunning(pid) {
+  try {
+    process.kill(pid, 0); // Signal 0 = existence check, no actual signal
+    return true;
+  } catch {
+    return false;
+  }
+}

package/lib/singleton.test.mjs

@@ -0,0 +1,135 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, writeFileSync, existsSync, rmSync, readFileSync, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+// singleton.js now resolves the locks dir per call from AGENT_ROOT (then
+// AGENT_DIR, then cwd). Set AGENT_ROOT to a throwaway dir before importing so
+// the default suite operates inside it; individual tests that exercise the
+// AGENT_DIR fallback save/restore the environment themselves.
+const root = mkdtempSync(join(tmpdir(), "maestro-singleton-"));
+process.env.AGENT_ROOT = root;
+delete process.env.AGENT_DIR;
+const { acquireLock, releaseLock, checkLock } = await import("./singleton.js");
+
+const LOCKS = join(root, "state", "locks", "process");
+
+test("first acquire succeeds; second (live holder) is refused", () => {
+  assert.equal(acquireLock("a"), true);
+  // Our own PID is the holder and is alive, so re-acquire must fail.
+  assert.equal(acquireLock("a"), false);
+  releaseLock("a");
+});
+
+test("release frees the lock so it can be re-acquired", () => {
+  assert.equal(acquireLock("b"), true);
+  releaseLock("b");
+  assert.equal(acquireLock("b"), true);
+  releaseLock("b");
+});
+
+test("a stale lock (dead PID) is reclaimed atomically", () => {
+  const pidFile = join(LOCKS, "c.pid");
+  writeFileSync(pidFile, "2147483646"); // effectively never a live PID
+  assert.equal(acquireLock("c"), true);
+  // The reclaimed lock now records our PID on line 1 (identity may follow).
+  assert.equal(readFileSync(pidFile, "utf8").split("\n")[0].trim(), String(process.pid));
+  releaseLock("c");
+});
+
+test("a corrupt lock file is reclaimed", () => {
+  const pidFile = join(LOCKS, "d.pid");
+  writeFileSync(pidFile, "not-a-pid");
+  assert.equal(acquireLock("d"), true);
+  releaseLock("d");
+});
+
+test("acquire writes our own pid into the lock file", () => {
+  assert.equal(acquireLock("e"), true);
+  assert.equal(readFileSync(join(LOCKS, "e.pid"), "utf8").split("\n")[0].trim(), String(process.pid));
+  releaseLock("e");
+  assert.ok(!existsSync(join(LOCKS, "e.pid")));
+});
+
+test("checkLock reports running state for a held lock", () => {
+  assert.equal(acquireLock("f"), true);
+  const status = checkLock("f");
+  assert.equal(status.running, true);
+  assert.equal(status.pid, process.pid);
+  releaseLock("f");
+  assert.equal(checkLock("f").running, false);
+});
+
+// L5/L23: locks dir resolution honours AGENT_DIR when AGENT_ROOT is unset, and
+// is computed per call rather than memoised at import.
+test("locks dir honours AGENT_DIR when AGENT_ROOT is unset", () => {
+  const savedRoot = process.env.AGENT_ROOT;
+  const savedDir = process.env.AGENT_DIR;
+  const altRoot = mkdtempSync(join(tmpdir(), "maestro-singleton-agentdir-"));
+  try {
+    delete process.env.AGENT_ROOT;
+    process.env.AGENT_DIR = altRoot;
+    const altLocks = join(altRoot, "state", "locks", "process");
+
+    // Acquire under AGENT_DIR — the lock file must land under altRoot, proving
+    // per-call resolution picked up AGENT_DIR (not the import-time AGENT_ROOT).
+    assert.equal(acquireLock("agentdir"), true);
+    assert.ok(existsSync(join(altLocks, "agentdir.pid")));
+    // And it must NOT have been written under the original AGENT_ROOT tree.
+    assert.ok(!existsSync(join(LOCKS, "agentdir.pid")));
+    releaseLock("agentdir");
+    assert.ok(!existsSync(join(altLocks, "agentdir.pid")));
+  } finally {
+    if (savedRoot === undefined) delete process.env.AGENT_ROOT;
+    else process.env.AGENT_ROOT = savedRoot;
+    if (savedDir === undefined) delete process.env.AGENT_DIR;
+    else process.env.AGENT_DIR = savedDir;
+    rmSync(altRoot, { recursive: true, force: true });
+  }
+});
+
+// L2: PID-reuse false positive. A lock whose PID is alive (our own PID) but
+// whose recorded identity token does NOT match the real process identity is a
+// recycled PID, and must be reclaimed rather than treated as a live holder.
+test("a stale lock with alive-but-different identity is reclaimed", () => {
+  const pidFile = join(LOCKS, "g.pid");
+  mkdirSync(LOCKS, { recursive: true });
+  // Our own PID (alive) + a bogus identity token that cannot match the real
+  // `ps -o lstart=` start time for this process.
+  writeFileSync(pidFile, `${process.pid}\nBOGUS-IDENTITY-TOKEN-NEVER-MATCHES`);
+
+  // checkLock must see this as not running (identity mismatch -> stale).
+  assert.equal(checkLock("g").running, false);
+
+  // And acquire must succeed by reclaiming the stale lock.
+  writeFileSync(pidFile, `${process.pid}\nBOGUS-IDENTITY-TOKEN-NEVER-MATCHES`);
+  assert.equal(acquireLock("g"), true);
+  // The reclaimed lock now records our PID on line 1.
+  assert.equal(readFileSync(pidFile, "utf8").split("\n")[0].trim(), String(process.pid));
+  releaseLock("g");
+});
+
+// Identity match path: a lock written by acquire (real identity recorded) for
+// our own live PID is correctly treated as a live holder.
+test("a lock with matching identity for a live PID is treated as held", () => {
+  assert.equal(acquireLock("h"), true);
+  // Re-acquire must fail: same PID, identity recomputed and matches.
+  assert.equal(acquireLock("h"), false);
+  assert.equal(checkLock("h").running, true);
+  releaseLock("h");
+});
+
+// Legacy compatibility: an old single-line (PID-only) lock for a live PID is
+// still honoured as a live holder (no worse than historical behaviour).
+test("a legacy pid-only lock for a live PID is honoured", () => {
+  const pidFile = join(LOCKS, "i.pid");
+  mkdirSync(LOCKS, { recursive: true });
+  writeFileSync(pidFile, String(process.pid)); // legacy format, no identity
+  assert.equal(checkLock("i").running, true);
+  // Re-acquire must be refused since the PID is alive and no identity was set.
+  assert.equal(acquireLock("i"), false);
+  rmSync(pidFile, { force: true });
+});
+
+test.after(() => rmSync(root, { recursive: true, force: true }));