@dev-loops/core 1.0.2-slim.0 → 1.0.3

package/src/loop/watcher-exclusivity.mjs

@@ -0,0 +1,302 @@
+/**
+ * watcher-exclusivity.mjs — dev-loop execution-cap watcher-exclusivity
+ * resolver. Mirrors ./reviewer-unit-bound.mjs and ./role-budget-bound.mjs's
+ * style: a bounded, deterministic primitive that resolves the current
+ * watch-owner verdict for a (target, head, wait-kind) boundary from
+ * caller-supplied lease/transition evidence, and always fails closed
+ * (blocked, never a silent pass) on any owner mismatch, stale lease, or
+ * malformed transition.
+ *
+ * The whole point of this primitive: the coordinator never becomes a SECOND
+ * observer of an in-flight external wait (Copilot review, CI, workflow run).
+ * `secondObserverAuthorized` is `false` in every branch of
+ * `resolveWatchOwnership` — there is no verdict shape that authorizes the
+ * caller to start its own competing watch/probe loop. The owner and
+ * transition evidence each carry a `target` field, compared against
+ * `boundary.target` alongside `head` and `waitKind`, so the resolver
+ * genuinely keys on the full (target, head, wait-kind) triple instead of
+ * accepting evidence for a different target.
+ *
+ * This resolver is caller-AGNOSTIC: it reports the single-owner verdict over
+ * SUPPLIED evidence and does not authenticate the calling runner. It cannot
+ * tell whether the process invoking it IS the recorded lease owner — that
+ * caller-identity check (verifying the calling runner matches
+ * `evidence.owner`, and gating the wait before it starts) is the consumer's
+ * responsibility and is deferred to the slice-b live wiring.
+ *
+ * Pure and offline: no runtime/harness adapter import, no file reads, no
+ * network, no state held across calls. This primitive is a post-hoc verdict
+ * over caller-supplied `evidence` — it does not read or write any lease
+ * file itself; that stays the caller's concern (the existing
+ * runner-coordination lease read/write path).
+ */
+
+import { EXTERNAL_HEALTHY_WAIT_TIMEOUT_POLICY } from "./timeout-policy.mjs";
+
+/** Wait kinds this primitive recognizes. */
+export const WATCH_KINDS = Object.freeze(["copilot_review", "ci", "workflow_run"]);
+
+/**
+ * Coordinator operation kinds that are always prohibited under watcher
+ * exclusivity: every one of these would make the coordinator a second
+ * observer of an in-flight external wait instead of the sole lease owner.
+ *
+ * Exported as a frozen ARRAY, not a Set: `Object.freeze(new Set(...))`
+ * freezes only the Set's own properties, not its contents — `.add`/
+ * `.delete`/`.clear` still work on a frozen Set and the mutation persists on
+ * this module-singleton export. A frozen array has no such escape hatch.
+ */
+export const PROHIBITED_COORDINATOR_OBSERVER_OPERATIONS = Object.freeze([
+  "direct_probe",
+  "start_watcher",
+  "sleep_retry",
+  "second_watch_loop",
+]);
+
+const PROHIBITED_COORDINATOR_OBSERVER_OPERATIONS_SET = new Set(PROHIBITED_COORDINATOR_OBSERVER_OPERATIONS);
+
+/** Transition statuses that authorize a phase advance once owner+transition match the boundary. */
+const ADVANCING_TRANSITION_STATUSES = new Set(["changed", "completed"]);
+/** Transition statuses that keep a matching owner in a healthy wait (never advance). */
+const WAITING_TRANSITION_STATUSES = new Set(["timeout", "idle", "pending"]);
+
+/** @param {unknown} value @returns {boolean} */
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+/**
+ * Recursively freeze a plain object/array value's own nested plain
+ * objects/arrays. A shallow Object.freeze leaves nested values mutable.
+ * Recurses into children even when the current container is already frozen.
+ * A WeakSet cycle guard prevents infinite recursion on a cyclic object graph.
+ * @param {unknown} value
+ * @param {WeakSet<object>} [seen]
+ * @returns {unknown} the same value, deep-frozen.
+ */
+function deepFreeze(value, seen = new WeakSet()) {
+  if (value === null || typeof value !== "object" || seen.has(value)) {
+    return value;
+  }
+  seen.add(value);
+  for (const key of Object.keys(value)) {
+    deepFreeze(value[key], seen);
+  }
+  return Object.freeze(value);
+}
+
+/**
+ * Validate + normalize the trust-boundary identity at the boundary. Fails
+ * closed (TypeError naming the violation) on any malformed field.
+ * @param {{target:string, head:string, waitKind:string}} boundary
+ * @returns {{target:string, head:string, waitKind:string}}
+ */
+function validateBoundary(boundary) {
+  if (!boundary || typeof boundary !== "object") {
+    throw new TypeError("resolveWatchOwnership requires boundary to be an object");
+  }
+  if (!isNonEmptyString(boundary.target)) {
+    throw new TypeError("boundary.target must be a non-empty string");
+  }
+  if (!isNonEmptyString(boundary.head)) {
+    throw new TypeError("boundary.head must be a non-empty string");
+  }
+  if (!WATCH_KINDS.includes(boundary.waitKind)) {
+    throw new TypeError(`boundary.waitKind must be one of ${WATCH_KINDS.join(", ")}, got ${JSON.stringify(boundary.waitKind)}`);
+  }
+  return { target: boundary.target.trim(), head: boundary.head.trim(), waitKind: boundary.waitKind };
+}
+
+/**
+ * Validate + normalize `evidence.owner`. `null` (no active owner) is valid;
+ * a present owner must carry every required field.
+ * @param {unknown} owner
+ * @returns {{runId:string, target:string, head:string, waitKind:string, updatedAt:string}|null}
+ */
+function validateOwner(owner) {
+  if (owner === null || owner === undefined) return null;
+  if (typeof owner !== "object") {
+    throw new TypeError("evidence.owner must be null or an object");
+  }
+  if (!isNonEmptyString(owner.runId)) {
+    throw new TypeError("evidence.owner.runId must be a non-empty string");
+  }
+  if (!isNonEmptyString(owner.target)) {
+    throw new TypeError("evidence.owner.target must be a non-empty string");
+  }
+  if (!isNonEmptyString(owner.head)) {
+    throw new TypeError("evidence.owner.head must be a non-empty string");
+  }
+  if (!WATCH_KINDS.includes(owner.waitKind)) {
+    throw new TypeError(`evidence.owner.waitKind must be one of ${WATCH_KINDS.join(", ")}, got ${JSON.stringify(owner.waitKind)}`);
+  }
+  if (!isNonEmptyString(owner.updatedAt) || Number.isNaN(Date.parse(owner.updatedAt))) {
+    throw new TypeError("evidence.owner.updatedAt must be a non-empty, Date.parse-able timestamp string");
+  }
+  return {
+    runId: owner.runId.trim(),
+    target: owner.target.trim(),
+    head: owner.head.trim(),
+    waitKind: owner.waitKind,
+    updatedAt: owner.updatedAt.trim(),
+  };
+}
+
+/**
+ * Validate + normalize `evidence.transition`. `null`/absent (no transition
+ * observed yet) is valid; a present transition must carry every required
+ * field.
+ * @param {unknown} transition
+ * @returns {{target:string, head:string, waitKind:string, status:string}|null}
+ */
+function validateTransition(transition) {
+  if (transition === null || transition === undefined) return null;
+  if (typeof transition !== "object") {
+    throw new TypeError("evidence.transition must be null or an object");
+  }
+  if (!isNonEmptyString(transition.target)) {
+    throw new TypeError("evidence.transition.target must be a non-empty string");
+  }
+  if (!isNonEmptyString(transition.head)) {
+    throw new TypeError("evidence.transition.head must be a non-empty string");
+  }
+  if (!WATCH_KINDS.includes(transition.waitKind)) {
+    throw new TypeError(`evidence.transition.waitKind must be one of ${WATCH_KINDS.join(", ")}, got ${JSON.stringify(transition.waitKind)}`);
+  }
+  if (!isNonEmptyString(transition.status)) {
+    throw new TypeError("evidence.transition.status must be a non-empty string");
+  }
+  return {
+    target: transition.target.trim(),
+    head: transition.head.trim(),
+    waitKind: transition.waitKind,
+    status: transition.status.trim(),
+  };
+}
+
+/** @param {string} a @param {string} b @returns {boolean} case-insensitive, trimmed equality. */
+function sameNormalized(a, b) {
+  return a.trim().toLowerCase() === b.trim().toLowerCase();
+}
+
+/**
+ * Resolve the current watch-owner verdict for one (target, head, wait-kind)
+ * boundary from caller-supplied lease/transition evidence. Validates every
+ * input at the trust boundary and fails closed on malformed input
+ * (TypeError) or on any owner/transition mismatch (a "blocked" verdict —
+ * never a silent pass).
+ *
+ * `secondObserverAuthorized` is `false` in every returned verdict: there is
+ * no shape this function returns that authorizes the caller to start its
+ * own competing watch/probe loop.
+ *
+ * @param {object} options
+ * @param {{target:string, head:string, waitKind:"copilot_review"|"ci"|"workflow_run"}} options.boundary
+ * @param {{owner: object|null, transition?: object|null}} options.evidence
+ * @param {number} options.now non-negative integer ms epoch.
+ * @param {number} options.staleAfterMs positive integer.
+ * @returns {object} a frozen verdict; see module header for shapes.
+ */
+export function resolveWatchOwnership({ boundary, evidence, now, staleAfterMs } = {}) {
+  const normalizedBoundary = validateBoundary(boundary);
+  if (!Number.isInteger(now) || now < 0) {
+    throw new TypeError("resolveWatchOwnership requires now to be a non-negative integer");
+  }
+  if (!Number.isInteger(staleAfterMs) || staleAfterMs <= 0) {
+    throw new TypeError("resolveWatchOwnership requires staleAfterMs to be a positive integer");
+  }
+  if (!evidence || typeof evidence !== "object") {
+    throw new TypeError("resolveWatchOwnership requires evidence to be an object with an owner field");
+  }
+  const owner = validateOwner(evidence.owner);
+  const transition = validateTransition(evidence.transition);
+
+  const blocked = (reason) => deepFreeze({
+    ok: false,
+    verdict: "blocked",
+    reason,
+    boundary: normalizedBoundary,
+    secondObserverAuthorized: false,
+    advancePhaseAuthorized: false,
+    probeAuthorized: false,
+    waitTimeoutPolicy: EXTERNAL_HEALTHY_WAIT_TIMEOUT_POLICY,
+  });
+
+  if (owner === null) {
+    return blocked("no_active_owner");
+  }
+  if (!sameNormalized(owner.target, normalizedBoundary.target)) {
+    return blocked("owner_target_mismatch");
+  }
+  if (!sameNormalized(owner.head, normalizedBoundary.head)) {
+    return blocked("owner_head_mismatch");
+  }
+  if (owner.waitKind !== normalizedBoundary.waitKind) {
+    return blocked("owner_wait_kind_mismatch");
+  }
+  if (now - Date.parse(owner.updatedAt) > staleAfterMs) {
+    return blocked("owner_lease_stale");
+  }
+
+  const ownedWaiting = () => deepFreeze({
+    ok: true,
+    status: "owned_waiting",
+    owner,
+    advancePhaseAuthorized: false,
+    probeAuthorized: false,
+    secondObserverAuthorized: false,
+    waitTimeoutPolicy: EXTERNAL_HEALTHY_WAIT_TIMEOUT_POLICY,
+  });
+
+  if (transition === null) {
+    return ownedWaiting();
+  }
+  if (
+    !sameNormalized(transition.target, normalizedBoundary.target) ||
+    !sameNormalized(transition.head, normalizedBoundary.head) ||
+    transition.waitKind !== normalizedBoundary.waitKind
+  ) {
+    return blocked("stale_or_malformed_transition");
+  }
+  if (ADVANCING_TRANSITION_STATUSES.has(transition.status)) {
+    return deepFreeze({
+      ok: true,
+      status: "transition_ready",
+      owner,
+      transition,
+      advancePhaseAuthorized: true,
+      probeAuthorized: false,
+      secondObserverAuthorized: false,
+      waitTimeoutPolicy: EXTERNAL_HEALTHY_WAIT_TIMEOUT_POLICY,
+    });
+  }
+  if (WAITING_TRANSITION_STATUSES.has(transition.status)) {
+    // A timeout does not advance the phase — the existing timeout policy
+    // governs escalation, this resolver only reports the healthy wait.
+    return ownedWaiting();
+  }
+  return blocked("stale_or_malformed_transition");
+}
+
+/**
+ * Pure default-deny guard: the coordinator has no sanctioned observer
+ * operation while watcher exclusivity holds — the lease owner is the sole
+ * observer. Every explicitly prohibited kind throws a named prohibition
+ * error; every OTHER kind (there is no allow-list) throws
+ * unknown_coordinator_observer_operation. This mirrors
+ * assertReviewerOperationAllowed's default-deny posture, but with an empty
+ * allow-list: there is nothing a coordinator may do here except wait for the
+ * lease owner's evidence to change.
+ * @param {{kind:string}} operation
+ * @returns {never}
+ */
+export function assertNoOverlappingObserver(operation) {
+  if (!operation || typeof operation !== "object" || !isNonEmptyString(operation.kind)) {
+    throw new TypeError("assertNoOverlappingObserver requires operation.kind to be a non-empty string");
+  }
+  const { kind } = operation;
+  if (PROHIBITED_COORDINATOR_OBSERVER_OPERATIONS_SET.has(kind)) {
+    throw new Error(`coordinator observer operation prohibited under watcher exclusivity: ${kind}`);
+  }
+  throw new Error(`unknown_coordinator_observer_operation: ${kind}`);
+}

package/src/loop/worktree-guard.mjs

@@ -35,12 +35,13 @@ export function isUnderWorktreePath(cwd) {
  * @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();
+  // The main worktree is the FIRST parseable entry — derived from the same
+  // parser `parseAllWorktreePaths` uses, so the two can never disagree about
+  // which path is the main checkout. Parsing only the raw first line would
+  // return null on a leading blank/SHA-less line while `parseAllWorktreePaths`
+  // still parses the real main line, nulling the main-checkout guard while the
+  // path stays admittable (the leading-blank-line fail-open).
+  return parseAllWorktreePaths(worktreeListOutput)[0] ?? null;
 }
 
 /**
@@ -115,10 +116,15 @@ export function isListedWorktree(cwd, worktreePaths) {
 /**
  * Resolve the root of the listed git worktree that contains `cwd`.
  *
- * Mirrors `isListedWorktree`'s matching (realpath-resolved, tmp/worktrees/-scoped,
- * exact-or-subdirectory) but returns the worktree ROOT instead of a boolean, so
- * callers can address files relative to the worktree's own subtree (`packages/`,
- * `node_modules/`) rather than the possibly-nested `cwd`.
+ * Returns the worktree ROOT (realpath-resolved, exact-or-subdirectory match)
+ * instead of a boolean, so callers can address files relative to the worktree's
+ * own subtree (`packages/`, `node_modules/`) rather than the possibly-nested
+ * `cwd`. Matches ANY listed worktree — not just `tmp/worktrees/`-scoped ones —
+ * so the core-isolation invariant is evaluable for a sibling/linked checkout
+ * that lives outside `tmp/worktrees/`; the caller decides admit/reject.
+ * When `cwd` sits under nested worktrees (a `tmp/worktrees/` child inside its
+ * parent checkout), the LONGEST matching root wins, so the innermost worktree's
+ * own subtree is addressed regardless of `git worktree list` order.
  *
  * @param {string} cwd - Absolute or relative path inside the worktree.
  * @param {string[]} worktreePaths - Array of paths from `parseAllWorktreePaths`.
@@ -128,16 +134,16 @@ export function resolveContainingWorktreeRoot(cwd, worktreePaths) {
   let resolvedCwd;
   try { resolvedCwd = realpathSync(cwd); } catch { resolvedCwd = cwd; }
   const normalizedCwd = resolvedCwd.replace(/\\/g, "/").replace(/\/+$/u, "");
+  let best = null;
   for (const p of worktreePaths) {
     let resolvedP;
     try { resolvedP = realpathSync(p); } catch { resolvedP = p; }
     const normalizedP = resolvedP.replace(/\\/g, "/").replace(/\/+$/u, "");
-    if (!isUnderWorktreePath(normalizedP)) continue;
     if (normalizedCwd === normalizedP || normalizedCwd.startsWith(normalizedP + "/")) {
-      return normalizedP;
+      if (best === null || normalizedP.length > best.length) best = normalizedP;
     }
   }
-  return null;
+  return best;
 }
 
 /**
@@ -191,6 +197,67 @@ export function isWorktreeCoreIsolated(cwd, worktreePaths) {
   return linkReal === coreReal;
 }
 
+/**
+ * Shared admit/reject decision for local-implementation worktree isolation.
+ *
+ * The single source of truth both enforcement sites route through
+ * (`pre-flight-gate.mjs` `checkWorktreeIsolation` and
+ * `resolve-dev-loop-startup.mjs`'s `local_implementation` block), so they
+ * cannot diverge. Each caller maps the returned `error`/`detail` to its own
+ * guidance/reason wording; this function owns only the decision.
+ *
+ * `tmp/worktrees/` stays the default and recommended location, but it is not
+ * the invariant. The real invariant is core isolation: a checkout's
+ * `node_modules/@dev-loops/core` resolves to its OWN `packages/core`.
+ * A checkout OUTSIDE `tmp/worktrees/` that is not the main checkout and
+ * satisfies that invariant is admitted rather than rejected on path prefix
+ * alone; one that does not satisfy it (its core link escapes its own
+ * `packages/core`) fails closed.
+ *
+ * Decision order:
+ *  - outside `tmp/worktrees/` + main checkout  -> reject `main_checkout_detected`
+ *  - outside `tmp/worktrees/` + unresolvable worktree root -> reject `not_in_worktree` (fail closed, no vacuous admit)
+ *  - outside `tmp/worktrees/` + core-isolated  -> ADMIT (verified-isolation)
+ *  - outside `tmp/worktrees/` + not isolated   -> reject `not_in_worktree`
+ *  - under `tmp/worktrees/` + not a real worktree -> reject `not_in_worktree`
+ *  - under `tmp/worktrees/` + core link escapes -> reject `core_link_escapes`
+ *  - otherwise -> ADMIT
+ *
+ * @param {object} params
+ * @param {string} params.cwd - Current working directory (absolute or relative).
+ * @param {string | null} params.mainWorktreePath - From `parseMainWorktreePath`.
+ * @param {string[]} params.allWorktreePaths - From `parseAllWorktreePaths`.
+ * @returns {{ ok: true } | { ok: false, error: string, detail: string }}
+ */
+export function classifyWorktreeIsolation({ cwd, mainWorktreePath, allWorktreePaths }) {
+  if (!isUnderWorktreePath(cwd)) {
+    if (mainWorktreePath !== null && isMainCheckout(cwd, mainWorktreePath)) {
+      return { ok: false, error: "main_checkout_detected", detail: "main_checkout" };
+    }
+    // Outside tmp/worktrees and not the main checkout: assert the REAL
+    // core-isolation invariant instead of rejecting on path prefix alone.
+    // The invariant is only meaningful for a checkout that resolves to a real
+    // listed git worktree root; when the root cannot be resolved (an unlisted
+    // checkout, or an empty/unparseable `git worktree list` — which also nulls
+    // mainWorktreePath and skips the main-checkout guard above) the core-isolation
+    // check would vacuously return true, so fail closed rather than admit.
+    if (resolveContainingWorktreeRoot(cwd, allWorktreePaths) === null) {
+      return { ok: false, error: "not_in_worktree", detail: "outside_not_isolated" };
+    }
+    if (isWorktreeCoreIsolated(cwd, allWorktreePaths)) {
+      return { ok: true };
+    }
+    return { ok: false, error: "not_in_worktree", detail: "outside_not_isolated" };
+  }
+  if (!isListedWorktree(cwd, allWorktreePaths)) {
+    return { ok: false, error: "not_in_worktree", detail: "fake_worktree" };
+  }
+  if (!isWorktreeCoreIsolated(cwd, allWorktreePaths)) {
+    return { ok: false, error: "core_link_escapes", detail: "core_escapes" };
+  }
+  return { ok: true };
+}
+
 
 /**
  * Realpath-normalize a path that MAY NOT EXIST yet.

package/src/security/secret-scan.mjs

@@ -319,6 +319,17 @@ export function parseAddedLines(diffText) {
  * @param {string} diffText
  * @returns {{ ok: boolean, findings: { file: string, line: number, detectorClass: string, reason: string }[] }}
  */
+// The committed `.claude/package-lock.json` is, like `bun.lock`, a fully
+// machine-generated lockfile whose every token derives from public npm registry metadata
+// (Subresource Integrity digests, `resolved` tarball URLs, and long hyphenated per-platform
+// package names from its real transitive tree) — none of it is a secret by construction.
+// Unlike bun.lock's narrow tuple shape, an npm v3 lock spreads those long tokens across many
+// distinct field shapes, so rather than enumerate every
+// field individually the HIGH_ENTROPY detector is skipped for this one generated file; the
+// literal-credential and sink-pattern detectors still run over every line unchanged, so a real
+// credential shape landing here is still caught.
+const HIGH_ENTROPY_EXEMPT_FILES = new Set([".claude/package-lock.json"]);
+
 export function scanDiffText(diffText) {
   const findings = [];
   for (const entry of parseAddedLines(diffText)) {
@@ -334,7 +345,9 @@ export function scanDiffText(diffText) {
         // names cross the generic entropy threshold despite containing no value.
         .replace(/@mariozechner\/clipboard-[a-z0-9-]+/gu, "<clipboard-platform-package>")
       : entry.text;
+    const skipHighEntropy = HIGH_ENTROPY_EXEMPT_FILES.has(entry.file ?? "");
     for (const hit of scanLineText(text)) {
+      if (skipHighEntropy && hit.detectorClass === DETECTOR_CLASSES.HIGH_ENTROPY) continue;
       findings.push({ file: entry.file, line: entry.line, ...hit });
     }
   }