@dev-loops/core 0.1.0

package/src/loop/timeout-policy.mjs

@@ -0,0 +1,73 @@
+export const DEV_LOOP_TIMEOUT_CLASSIFICATION = Object.freeze({
+  PERSISTENT_INTERNAL_WAIT: "persistent_internal_wait",
+  EXTERNAL_HEALTHY_WAIT: "external_healthy_wait",
+  PROBE_STATUS: "probe_status",
+});
+
+export const PERSISTENT_INTERNAL_WAIT_TIMEOUT_POLICY = Object.freeze({
+  classification: DEV_LOOP_TIMEOUT_CLASSIFICATION.PERSISTENT_INTERNAL_WAIT,
+  minimumTimeoutMs: 3_600_000,
+  defaultTimeoutMs: 3_600_000,
+});
+
+export const EXTERNAL_HEALTHY_WAIT_TIMEOUT_POLICY = Object.freeze({
+  classification: DEV_LOOP_TIMEOUT_CLASSIFICATION.EXTERNAL_HEALTHY_WAIT,
+  minimumTimeoutMs: 1_800_000,
+  defaultTimeoutMs: 1_800_000,
+});
+
+function formatTimeoutDuration(timeoutMs) {
+  if (timeoutMs === 3_600_000) {
+    return "1 hour";
+  }
+
+  if (timeoutMs === 1_800_000) {
+    return "30 minutes";
+  }
+
+  if (timeoutMs === 86_400_000) {
+    return "24 hours";
+  }
+
+  return `${timeoutMs} ms`;
+}
+
+function enforceTimeoutPolicy(policy, { timeoutMs = policy.defaultTimeoutMs, explicitProbe = false, contextLabel }) {
+  if (!Number.isInteger(timeoutMs) || timeoutMs < 0) {
+    throw new Error(`${contextLabel} timeout must be a non-negative integer`);
+  }
+
+  if (explicitProbe) {
+    return 0;
+  }
+
+  if (timeoutMs === 0) {
+    throw new Error(`${contextLabel} uses the persistent unattended timeout contract; use an explicit probe/status path instead of timeout 0.`);
+  }
+
+  if (timeoutMs < policy.minimumTimeoutMs) {
+    throw new Error(`${contextLabel} requires at least ${policy.minimumTimeoutMs} ms (${formatTimeoutDuration(policy.minimumTimeoutMs)}) for persistent unattended waits; received ${timeoutMs}.`);
+  }
+
+  return timeoutMs;
+}
+
+export function enforcePersistentInternalWaitTimeout(options = {}) {
+  return enforceTimeoutPolicy(
+    PERSISTENT_INTERNAL_WAIT_TIMEOUT_POLICY,
+    {
+      contextLabel: "Persistent internal wait",
+      ...options,
+    },
+  );
+}
+
+export function enforceExternalHealthyWaitTimeout(options = {}) {
+  return enforceTimeoutPolicy(
+    EXTERNAL_HEALTHY_WAIT_TIMEOUT_POLICY,
+    {
+      contextLabel: "External healthy wait",
+      ...options,
+    },
+  );
+}

package/src/loop/tracker-first-loop-state.mjs

@@ -0,0 +1,87 @@
+/**
+ * Tracker-first loop state machine — pure logic layer.
+ *
+ * Standalone interpreter that maps a raw tracker/issue state string
+ * (plus optional PR context) to a canonical loop state with the same
+ * { ok, state, snapshot, allowedTransitions, nextAction } interface as
+ * detect-copilot-loop-state.mjs.
+ *
+ * Fail-closed contract: unknown/ambiguous tracker state maps to `needs_triage`,
+ * not to the canonical `unknown` state. Only an explicit `trackerState: "unknown"`
+ * produces the `unknown` canonical state.
+ */
+
+/** @typedef {"drafting"|"needs_triage"|"in_progress"|"in_review"|"merge_ready"|"blocked"|"completed"|"unknown"} TrackerState */
+
+/** @type {readonly TrackerState[]} */
+export const TRACKER_STATES = Object.freeze([
+  "drafting",
+  "needs_triage",
+  "in_progress",
+  "in_review",
+  "merge_ready",
+  "blocked",
+  "completed",
+  "unknown",
+]);
+
+/** @type {Readonly<Record<TrackerState, readonly TrackerState[]>>} */
+export const TRACKER_TRANSITIONS = Object.freeze({
+  drafting:        ["needs_triage", "blocked", "unknown"],
+  needs_triage:    ["in_progress", "blocked", "drafting", "unknown"],
+  in_progress:     ["in_review", "blocked", "needs_triage", "unknown"],
+  in_review:       ["merge_ready", "in_progress", "blocked", "unknown"],
+  merge_ready:     ["completed", "in_review", "blocked", "unknown"],
+  blocked:         ["needs_triage", "in_progress", "in_review", "drafting", "unknown"],
+  completed:       ["unknown"],
+  unknown:         Object.freeze([...TRACKER_STATES]),
+});
+
+/**
+ * Build a tracker-first loop state snapshot from PR-level tracker data.
+ *
+ * @param {object} input
+ * @param {string} input.trackerState - Raw tracker/issue state (e.g. from gh issue view --jq .state)
+ * @param {object} [input.prContext] - Optional PR context (linked PR, CI status)
+ * @returns {{ ok: true, state: TrackerState, snapshot: object, allowedTransitions: readonly TrackerState[], nextAction: string }}
+ */
+export function interpretTrackerLoopState(input) {
+  const raw = input.trackerState;
+
+  // Map raw tracker states to canonical states.
+  // Fail-closed: unrecognized/ambiguous states → needs_triage.
+  // Only explicit "unknown" → the canonical `unknown` state.
+  const lower = (raw || "").toLowerCase().trim();
+  let state = /** @type {TrackerState} */ ("needs_triage");
+
+  if (lower === "draft" || lower === "drafting") state = "drafting";
+  else if (lower === "open" || lower === "needs_triage") state = "needs_triage";
+  else if (lower === "in_progress" || lower === "in progress") state = "in_progress";
+  else if (lower === "in_review" || lower === "review") state = "in_review";
+  else if (lower === "merge_ready" || lower === "ready") state = "merge_ready";
+  else if (lower === "blocked") state = "blocked";
+  else if (lower === "closed" || lower === "completed" || lower === "done") state = "completed";
+  else if (lower === "unknown") state = "unknown";
+
+  const allowedTransitions = TRACKER_TRANSITIONS[state];
+  const snapshot = {
+    trackerState: state,
+    rawTrackerState: raw,
+    prLinked: Boolean(input.prContext),
+    prContext: input.prContext || null,
+  };
+
+  let nextAction = "inspect";
+  switch (state) {
+    case "drafting":        nextAction = "triage_or_block"; break;
+    case "needs_triage":    nextAction = "start_work"; break;
+    case "in_progress":     nextAction = "review"; break;
+    case "in_review":       nextAction = "merge_or_fix"; break;
+    case "merge_ready":     nextAction = "merge"; break;
+    case "blocked":         nextAction = "resolve_blocker"; break;
+    case "completed":       nextAction = "done"; break;
+    default:                nextAction = "reconcile"; break;
+  }
+
+  return { ok: true, state, snapshot, allowedTransitions, nextAction };
+}

package/src/loop/tracker-pr-state.mjs

@@ -0,0 +1,301 @@
+/**
+ * Deterministic state machine for the tracker-first story-to-PR lifecycle.
+ *
+ * This module provides:
+ * - TRACKER_PR_STATE: stable state name constants
+ * - normalizeTrackerPrSnapshot: validate and canonicalize a raw snapshot
+ * - interpretTrackerPrState: map a snapshot to one current state + allowed transitions + next action
+ * - REVERSE_SYNC_ACTION: canonical reverse-sync action for each state
+ *
+ * The transition graph (`TRACKER_PR_TRANSITIONS`) is an internal implementation detail.
+ * Callers obtain the allowed transitions for a specific state from the
+ * `allowedTransitions` field returned by `interpretTrackerPrState`.
+ *
+ * MVP invariant: one tracker work item -> one GitHub PR.
+ *
+ * The state machine captures observable facts (tracker item identity, PR lifecycle)
+ * and maps them deterministically to exactly one current state, a list of allowed
+ * next transitions, a recommended next action, and the canonical reverse-sync action
+ * that should be applied to the tracker when entering that state.
+ *
+ * This snapshot intentionally does not encode tracker-native workflow readiness.
+ * Higher-level callers may combine tracker-owned readiness or blocked/done state
+ * with this helper when deciding whether PR creation is appropriate.
+ *
+ * Source-of-truth ownership:
+ * - Tracker:        work-item identity, planning hierarchy, and tracker-native state
+ * - GitHub:         PR lifecycle, review state, CI/check results, and merge facts
+ * - dev-loops:   projection and sync logic only; never the canonical owner of
+ *                   business fields
+ */
+
+/** Stable state name constants for the tracker-first story-to-PR lifecycle. */
+export const TRACKER_PR_STATE = Object.freeze({
+  /**
+   * No tracker work item was found. Nothing can proceed without a valid
+   * tracker item to anchor the PR.
+   */
+  NO_TRACKER_ITEM: "no_tracker_item",
+
+  /**
+   * A tracker work item exists and no PR has been created for it yet.
+   * This helper does not infer tracker-native readiness beyond that no-PR
+   * execution fact.
+   */
+  READY_NO_PR: "ready_no_pr",
+
+  /**
+   * A draft PR exists for the tracker work item. The tracker should reflect
+   * an in-progress state. PR metadata must include the required tracker
+   * identifier/link and follow the deterministic title/body projection rules.
+   */
+  DRAFT_PR_OPEN: "draft_pr_open",
+
+  /**
+   * The PR has been marked ready for review (no longer draft). The tracker
+   * should reflect a reviewable / in-review state.
+   */
+  PR_REVIEWABLE: "pr_reviewable",
+
+  /**
+   * The PR has been merged. This is the terminal success state. The tracker
+   * should be moved to done/completed.
+   */
+  PR_MERGED: "pr_merged",
+
+  /**
+   * The PR was closed without being merged. There is no automatic tracker
+   * state transition for this event by default. A human decision is required.
+   */
+  PR_CLOSED_UNMERGED: "pr_closed_unmerged",
+
+  /**
+   * Stop state for ambiguous or contradictory lifecycle snapshots that need
+   * an explicit user decision before the workflow can continue.
+   */
+  BLOCKED_NEEDS_USER_DECISION: "blocked_needs_user_decision",
+});
+
+/**
+ * Legal transitions for each state.
+ * The agent layer selects among allowed transitions; the state machine enforces
+ * the graph.
+ *
+ * Internal implementation detail. Callers receive the allowed transitions for a
+ * given state via the `allowedTransitions` field of `interpretTrackerPrState`.
+ */
+const TRACKER_PR_TRANSITIONS = Object.freeze({
+  [TRACKER_PR_STATE.NO_TRACKER_ITEM]: [],
+  [TRACKER_PR_STATE.READY_NO_PR]: [TRACKER_PR_STATE.DRAFT_PR_OPEN],
+  [TRACKER_PR_STATE.DRAFT_PR_OPEN]: [TRACKER_PR_STATE.PR_REVIEWABLE],
+  [TRACKER_PR_STATE.PR_REVIEWABLE]: [
+    TRACKER_PR_STATE.PR_MERGED,
+    TRACKER_PR_STATE.PR_CLOSED_UNMERGED,
+    TRACKER_PR_STATE.DRAFT_PR_OPEN,
+  ],
+  [TRACKER_PR_STATE.PR_MERGED]: [],
+  [TRACKER_PR_STATE.PR_CLOSED_UNMERGED]: [
+    TRACKER_PR_STATE.READY_NO_PR,
+    TRACKER_PR_STATE.BLOCKED_NEEDS_USER_DECISION,
+  ],
+  [TRACKER_PR_STATE.BLOCKED_NEEDS_USER_DECISION]: [],
+});
+
+/**
+ * Canonical reverse-sync action for each state.
+ *
+ * Each value names the tracker-side transition that should be applied when
+ * the lifecycle enters that state. Adapter implementations map these canonical
+ * action names to tracker-native field updates.
+ *
+ * "none" means no automatic tracker state mutation is required.
+ */
+export const REVERSE_SYNC_ACTION = Object.freeze({
+  [TRACKER_PR_STATE.NO_TRACKER_ITEM]: "none",
+  [TRACKER_PR_STATE.READY_NO_PR]: "none",
+  [TRACKER_PR_STATE.DRAFT_PR_OPEN]: "set_in_progress",
+  [TRACKER_PR_STATE.PR_REVIEWABLE]: "set_reviewable",
+  [TRACKER_PR_STATE.PR_MERGED]: "set_done",
+  [TRACKER_PR_STATE.PR_CLOSED_UNMERGED]: "none",
+  [TRACKER_PR_STATE.BLOCKED_NEEDS_USER_DECISION]: "none",
+});
+
+const GATE_REVIEW_VERDICT_SET = new Set(["clean", "findings_present", "blocked"]);
+
+function normalizeSha(value) {
+  return typeof value === "string" && value.trim().length > 0
+    ? value.trim()
+    : null;
+}
+
+function normalizeGateReviewVerdict(value) {
+  const normalized = typeof value === "string" ? value.trim().toLowerCase() : "";
+  return GATE_REVIEW_VERDICT_SET.has(normalized) ? normalized : null;
+}
+
+function hasCleanVisibleCurrentHeadDraftGate(snapshot) {
+  return snapshot.prHeadSha !== null
+    && snapshot.draftGateCommentVisible
+    && snapshot.draftGateCommentVerdict === "clean"
+    && snapshot.draftGateCommentHeadSha === snapshot.prHeadSha;
+}
+
+
+function normalizeBooleanLike(value) {
+  if (typeof value === "boolean") {
+    return value;
+  }
+
+  if (typeof value === "number") {
+    if (value === 1) {
+      return true;
+    }
+
+    if (value === 0) {
+      return false;
+    }
+
+    return false;
+  }
+
+  if (typeof value === "string") {
+    const normalized = value.trim().toLowerCase();
+
+    if (normalized === "true" || normalized === "1") {
+      return true;
+    }
+
+    if (normalized === "false" || normalized === "0" || normalized.length === 0) {
+      return false;
+    }
+  }
+
+  return false;
+}
+
+/** Recommended next action for each state. */
+const NEXT_ACTIONS = Object.freeze({
+  [TRACKER_PR_STATE.NO_TRACKER_ITEM]:
+    "Obtain a valid tracker work item before creating a PR",
+  [TRACKER_PR_STATE.READY_NO_PR]:
+    "If tracker workflow says the item is ready, create a draft PR with required tracker metadata (identifier link, title pattern, body sections, labels)",
+  [TRACKER_PR_STATE.DRAFT_PR_OPEN]:
+    "Complete development work, run draft gate, post a visible clean current-head draft_gate comment, then mark the draft PR as ready for review",
+  [TRACKER_PR_STATE.PR_REVIEWABLE]:
+    "Wait for review and CI; merge when approved, or convert back to draft if rework is needed",
+  [TRACKER_PR_STATE.PR_MERGED]:
+    "Sync tracker item to done/completed terminal state",
+  [TRACKER_PR_STATE.PR_CLOSED_UNMERGED]:
+    "Report to user; no automatic tracker transition — decide whether to reopen, create a new PR, or close the tracker item",
+  [TRACKER_PR_STATE.BLOCKED_NEEDS_USER_DECISION]:
+    "Report the blocked state to the user and stop; do not proceed without explicit authorization",
+});
+
+/**
+ * Normalize a raw tracker-PR snapshot into a validated, canonical snapshot.
+ *
+ * Unknown or invalid field values are replaced with safe defaults.
+ * Throws if `raw` is not a non-null object.
+ *
+ * Snapshot schema:
+ * - trackerItemExists {boolean}      — whether a tracker work item was found
+ * - trackerItemId {string|null}      — opaque tracker item identifier (e.g. "PROJ-123")
+ * - prExists {boolean}               — whether a GitHub PR exists for this item
+ * - prNumber {number|null}           — PR number if known; treat `prNumber` with `prExists=false` as contradictory input
+ * - prDraft {boolean}                — whether the PR is in draft state
+ * - prMerged {boolean}               — whether the PR has been merged
+ * - prClosed {boolean}               — whether the PR is closed on GitHub (merged PRs are also closed)
+ * - prHeadSha {string|null}          — current PR head SHA
+ * - draftGateCommentVisible {boolean} — whether the draft-gate PR comment is visible on the PR thread
+ * - draftGateCommentHeadSha {string|null} — head SHA encoded in the draft-gate PR comment
+ * - draftGateCommentVerdict {"clean"|"findings_present"|"blocked"|null} — draft-gate comment verdict
+ *
+ * @param {object} raw - raw snapshot input
+ * @returns {object} normalized snapshot
+ */
+export function normalizeTrackerPrSnapshot(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error("Snapshot must be a non-null object");
+  }
+
+  const trackerItemExists = normalizeBooleanLike(raw.trackerItemExists);
+  const prExists = normalizeBooleanLike(raw.prExists);
+  const prNumber =
+    typeof raw.prNumber === "number" && Number.isInteger(raw.prNumber) && raw.prNumber > 0
+      ? raw.prNumber
+      : null;
+
+  return {
+    trackerItemExists,
+    trackerItemId:
+      trackerItemExists && typeof raw.trackerItemId === "string" && raw.trackerItemId.trim().length > 0
+        ? raw.trackerItemId.trim()
+        : null,
+    prExists,
+    prNumber,
+    prDraft: normalizeBooleanLike(raw.prDraft),
+    prMerged: normalizeBooleanLike(raw.prMerged),
+    prClosed: normalizeBooleanLike(raw.prClosed),
+    prHeadSha: prExists ? normalizeSha(raw.prHeadSha) : null,
+    draftGateCommentVisible: normalizeBooleanLike(raw.draftGateCommentVisible),
+    draftGateCommentHeadSha: prExists ? normalizeSha(raw.draftGateCommentHeadSha) : null,
+    draftGateCommentVerdict: normalizeGateReviewVerdict(raw.draftGateCommentVerdict),
+  };
+}
+
+/**
+ * Interpret a tracker-PR lifecycle snapshot into one current state, allowed
+ * next transitions, a recommended next action, and the canonical reverse-sync
+ * action for the tracker.
+ *
+ * Interpretation is deterministic: the same snapshot always yields the same
+ * result. The function normalizes the snapshot before interpreting, so raw
+ * inputs are accepted.
+ *
+ * Routing priority:
+ * 1. Contradictory snapshot -> blocked_needs_user_decision
+ * 2. No tracker item and no PR facts -> no_tracker_item (nothing to anchor a PR to)
+ * 3. PR merged -> pr_merged (terminal success)
+ * 4. PR closed without merge -> pr_closed_unmerged (terminal, no auto-sync; `prClosed && !prMerged`, even if the closed PR still reports draft)
+ * 5. Draft PR exists -> draft_pr_open (in-progress)
+ * 6. PR exists and not draft, not merged, not closed -> pr_reviewable
+ * 7. Tracker item exists and no PR exists -> ready_no_pr (no-PR execution state)
+ *
+ * @param {object} snapshot - raw or normalized snapshot
+ * @returns {{ state: string, allowedTransitions: string[], nextAction: string, reverseSyncAction: string }}
+ */
+export function interpretTrackerPrState(snapshot) {
+  const s = normalizeTrackerPrSnapshot(snapshot);
+
+  const contradictorySnapshot =
+    (!s.trackerItemExists && (s.prExists || s.prNumber !== null || s.prDraft || s.prMerged || s.prClosed)) ||
+    (!s.prExists && (s.prNumber !== null || s.prDraft || s.prMerged || s.prClosed)) ||
+    (s.prMerged && s.prDraft);
+
+  let state;
+
+  if (contradictorySnapshot) {
+    state = TRACKER_PR_STATE.BLOCKED_NEEDS_USER_DECISION;
+  } else if (!s.trackerItemExists) {
+    state = TRACKER_PR_STATE.NO_TRACKER_ITEM;
+  } else if (s.prExists && s.prMerged) {
+    state = TRACKER_PR_STATE.PR_MERGED;
+  } else if (s.prExists && s.prClosed) {
+    state = TRACKER_PR_STATE.PR_CLOSED_UNMERGED;
+  } else if (s.prExists && s.prDraft) {
+    state = TRACKER_PR_STATE.DRAFT_PR_OPEN;
+  } else if (s.prExists) {
+    state = hasCleanVisibleCurrentHeadDraftGate(s)
+      ? TRACKER_PR_STATE.PR_REVIEWABLE
+      : TRACKER_PR_STATE.BLOCKED_NEEDS_USER_DECISION;
+  } else {
+    state = TRACKER_PR_STATE.READY_NO_PR;
+  }
+
+  return {
+    state,
+    allowedTransitions: [...TRACKER_PR_TRANSITIONS[state]],
+    nextAction: NEXT_ACTIONS[state],
+    reverseSyncAction: REVERSE_SYNC_ACTION[state],
+  };
+}

package/src/loop/worktree-guard.mjs

@@ -0,0 +1,141 @@
+/**
+ * Shared worktree and subagent guard primitives.
+ *
+ * Extracted from `scripts/loop/pre-commit-branch-guard.mjs` so that both the
+ * pre-commit guard and the new pre-flight gate share one implementation.
+ *
+ * This module is intentionally pure and side-effect free.
+ */
+
+import { realpathSync } from "node:fs";
+
+// ---------------------------------------------------------------------------
+// Worktree path helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Check whether `cwd` is under a tmp/worktrees path segment.
+ *
+ * @param {string} cwd - Absolute or relative path to the current working directory.
+ * @returns {boolean}
+ */
+export function isUnderWorktreePath(cwd) {
+  const normalized = cwd.replace(/\\/g, "/");
+  return /(?:^|\/)tmp\/worktrees(?:\/|$)/.test(normalized);
+}
+
+/**
+ * Parse the main (primary) git worktree path from `git worktree list` output.
+ *
+ * The first line of `git worktree list` is the primary worktree.
+ * Format: `<path>  <sha> [<branch>]`
+ *
+ * @param {string} worktreeListOutput - Raw stdout from `git worktree list`.
+ * @returns {string | null} The main worktree path, or null if it cannot be parsed.
+ */
+export function parseMainWorktreePath(worktreeListOutput) {
+  const firstLine = worktreeListOutput.split("\n")[0].trim();
+  if (!firstLine) return null;
+  // Find the first hex SHA (7+ chars) preceded by whitespace; take everything before it as the path.
+  const shaIdx = firstLine.search(/\s[0-9a-f]{7,64}\b/iu);
+  if (shaIdx === -1) return null;
+  return firstLine.slice(0, shaIdx).trim();
+}
+
+/**
+ * Check whether `cwd` is the main git checkout (or a subdirectory of it).
+ *
+ * @param {string} cwd - Absolute or relative path to the current working directory.
+ * @param {string | null} mainWorktreePath - The main worktree path from `parseMainWorktreePath`.
+ * @returns {boolean}
+ */
+export function isMainCheckout(cwd, mainWorktreePath) {
+  if (!mainWorktreePath) return false;
+  let resolvedCwd;
+  try { resolvedCwd = realpathSync(cwd); } catch { resolvedCwd = cwd; }
+  let resolvedMain;
+  try { resolvedMain = realpathSync(mainWorktreePath); } catch { resolvedMain = mainWorktreePath; }
+  const normalizedCwd = resolvedCwd.replace(/\\/g, "/").replace(/\/+$/u, "");
+  const normalizedMain = resolvedMain.replace(/\\/g, "/").replace(/\/+$/u, "");
+  return normalizedCwd === normalizedMain || normalizedCwd.startsWith(normalizedMain + "/");
+}
+
+/**
+ * Parse all worktree paths from `git worktree list` output.
+ *
+ * Each line in the output has the format `<path>  <sha> [<branch>]`.
+ * Returns absolute paths (one per worktree), preserving list order.
+ *
+ * @param {string} worktreeListOutput - Raw stdout from `git worktree list`.
+ * @returns {string[]}
+ */
+export function parseAllWorktreePaths(worktreeListOutput) {
+  const paths = [];
+  for (const line of worktreeListOutput.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    const shaIdx = trimmed.search(/\s[0-9a-f]{7,64}\b/iu);
+    if (shaIdx === -1) continue;
+    paths.push(trimmed.slice(0, shaIdx).trim());
+  }
+  return paths;
+}
+
+/**
+ * Check whether `cwd` is listed as a git worktree by `git worktree list`.
+ *
+ * This is stricter than `isUnderWorktreePath()` — a manually-created
+ * `tmp/worktrees/<slug>/` directory inside the main checkout passes
+ * `isUnderWorktreePath()` but fails `isListedWorktree()` because it is
+ * not a real git worktree.
+ *
+ * Resolves symlinks via realpathSync so that /var vs /private/var
+ * differences on macOS do not cause false negatives.
+ *
+ * @param {string} cwd - Absolute or relative path to the current working directory.
+ * @param {string[]} worktreePaths - Array of paths from `parseAllWorktreePaths`.
+ * @returns {boolean}
+ */
+export function isListedWorktree(cwd, worktreePaths) {
+  let resolvedCwd;
+  try { resolvedCwd = realpathSync(cwd); } catch { resolvedCwd = cwd; }
+  const normalized = resolvedCwd.replace(/\\/g, "/").replace(/\/+$/u, "");
+  return worktreePaths.some((p) => {
+    let resolvedP;
+    try { resolvedP = realpathSync(p); } catch { resolvedP = p; }
+    const normalizedP = resolvedP.replace(/\\/g, "/").replace(/\/+$/u, "");
+    // Only match worktree paths that are under tmp/worktrees/ (exclude main checkout).
+    if (!isUnderWorktreePath(normalizedP)) return false;
+    // Accept exact match or cwd is a subdirectory of a listed worktree root.
+    return normalized === normalizedP || normalized.startsWith(normalizedP + "/");
+  });
+}
+
+
+
+// ---------------------------------------------------------------------------
+// Subagent availability
+// ---------------------------------------------------------------------------
+
+/**
+ * Environment variable name checked by `detectSubagentAvailability`.
+ *
+ * Set `PI_SUBAGENT_AVAILABLE=1` when the runtime supports subagent dispatch.
+ * This is consistent with the `PI_WORKTREE_BYPASS` pattern and other repo-local
+ * runtime configuration gates already present in the repo.
+ */
+export const PI_SUBAGENT_AVAILABLE_VAR = "PI_SUBAGENT_AVAILABLE";
+
+/**
+ * Detect whether subagent dispatch is available in the current runtime.
+ *
+ * This is an env-var-based heuristic, consistent with other bypass/availability
+ * patterns in the repo. It is intentionally simple — the gate's subagent check
+ * is advisory (fails-open) and never hard-blocks on subagent absence.
+ *
+ * @param {{ env?: Record<string, string | undefined> }} [options]
+ * @returns {boolean}
+ */
+export function detectSubagentAvailability({ env = process.env } = {}) {
+  return (env[PI_SUBAGENT_AVAILABLE_VAR] ?? "").trim() === "1";
+}