@dev-loops/core 1.0.0-rc.5 → 1.0.0-rc.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dev-loops/core",
-  "version": "1.0.0-rc.5",
+  "version": "1.0.0-rc.7",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -21,11 +21,14 @@
     "./debt/shape": "./src/debt/shape.mjs",
     "./debt/signal": "./src/debt/debt-signal.mjs",
     "./github/copilot-helpers": "./src/github/copilot-helpers.mjs",
+    "./github/comment-id-guard": "./src/github/comment-id-guard.mjs",
+    "./github/gh": "./src/github/gh.mjs",
     "./github/issue-ops": "./src/github/issue-ops.mjs",
     "./github/ownership-helpers": "./src/github/ownership-helpers.mjs",
     "./github/repo-slug": "./src/github/repo-slug.mjs",
     "./github/review-threads": "./src/github/review-threads.mjs",
     "./loop/async-start-contract": "./src/loop/async-start-contract.mjs",
+    "./loop/agent-stall": "./src/loop/agent-stall.mjs",
     "./loop/bash-command-classify": "./src/loop/bash-command-classify.mjs",
     "./loop/conductor-routing": "./src/loop/conductor-routing.mjs",
     "./loop/copilot-ci-status": "./src/loop/copilot-ci-status.mjs",
@@ -35,6 +38,7 @@
     "./loop/gate-fanin": "./src/loop/gate-fanin.mjs",
     "./loop/handoff-envelope": "./src/loop/handoff-envelope.mjs",
     "./loop/lifecycle-state": "./src/loop/lifecycle-state.mjs",
+    "./loop/markdown-sections": "./src/loop/markdown-sections.mjs",
     "./loop/issue-refinement-artifact": "./src/loop/issue-refinement-artifact.mjs",
     "./loop/phase-files": "./src/loop/phase-files.mjs",
     "./loop/policy-constants": "./src/loop/policy-constants.mjs",
@@ -54,9 +58,14 @@
     "./loop/queue-membership": "./src/loop/queue-membership.mjs",
     "./loop/queue-parallel": "./src/loop/queue-parallel.mjs",
     "./loop/queue-state": "./src/loop/queue-state.mjs",
+    "./loop/size-budget-merge-gate": "./src/loop/size-budget-merge-gate.mjs",
+    "./loop/cache-telemetry-evidence": "./src/loop/cache-telemetry-evidence.mjs",
+    "./loop/primer-evidence": "./src/loop/primer-evidence.mjs",
+    "./loop/review-dispatch-plan": "./src/loop/review-dispatch-plan.mjs",
     "./loop/reviewer-loop-state": "./src/loop/reviewer-loop-state.mjs",
     "./loop/run-context": "./src/loop/run-context.mjs",
     "./loop/run-inspection": "./src/loop/run-inspection.mjs",
+    "./loop/run-post-merge-actions": "./src/loop/run-post-merge-actions.mjs",
     "./loop/spike-exit-contract": "./src/loop/spike-exit-contract.mjs",
     "./loop/spike-intake-contract": "./src/loop/spike-intake-contract.mjs",
     "./loop/steering": "./src/loop/steering.mjs",
@@ -68,6 +77,7 @@
     "./loop/ui-review-diagnose": "./src/loop/ui-review-diagnose.mjs",
     "./loop/ui-review-report": "./src/loop/ui-review-report.mjs",
     "./loop/ui-review-teardown": "./src/loop/ui-review-teardown.mjs",
+    "./security/secret-scan": "./src/security/secret-scan.mjs",
     "./projects/list-queue-items": "./src/projects/list-queue-items.mjs",
     "./projects/move-queue-item": "./src/projects/move-queue-item.mjs",
     "./projects/resolve-project": "./src/projects/resolve-project.mjs",
@@ -75,6 +85,7 @@
     "./tracker": "./src/tracker/index.mjs",
     "./loop/worktree-guard": "./src/loop/worktree-guard.mjs",
     "./loop/main-checkout-ff": "./src/loop/main-checkout-ff.mjs",
+    "./loop/normalize": "./src/loop/normalize.mjs",
     "./loop/tracker-first-loop-state": "./src/loop/tracker-first-loop-state.mjs"
   },
   "bin": {

package/src/analysis/change-classifier.mjs

@@ -22,6 +22,10 @@ export const ChangeCategory = Object.freeze({
   // child_process/shell exec, untrusted network fetch, destructive filesystem
   // ops / local-file upload). Triggers an up-front adversarial threat-model angle.
   SECURITY_SENSITIVE_SEAM: "SECURITY_SENSITIVE_SEAM",
+  // #1442: a changed file is on the prose surface (docs/articles/**,
+  // docs/presentations/**, README*, narrative docs/*.md) — ADR 0041 prose half.
+  // Triggers the required fail-closed `deslop` gate angle.
+  PROSE_PRESENT: "PROSE_PRESENT",
 });
 
 // ---------------------------------------------------------------------------
@@ -69,6 +73,12 @@ export const CATEGORY_ANGLE_MAP = {
   [ChangeCategory.SECURITY_SENSITIVE_SEAM]: [
     "threat-model", "input-validation", "scope", "correctness",
   ],
+  // #1442 (ADR 0041 prose half): a prose-surface path is present → run the
+  // required `deslop` gate angle. skills/docs/** is deliberately NOT prose, so
+  // a normative-contract-only docs diff never triggers deslop.
+  [ChangeCategory.PROSE_PRESENT]: [
+    "deslop",
+  ],
 };
 
 /**

package/src/analysis/diff-analyzer.mjs

@@ -21,6 +21,44 @@
 // fails closed toward a full re-review, which is what a version bump needs.
 const DOTFILE_CONFIG_BASENAMES = new Set([".devloops"]);
 
+// #1442 (ADR 0041 prose half): the prose surface that triggers the required
+// `deslop` gate angle. skills/docs/** is deliberately excluded — those are
+// normative contracts (owned by the contract style guide + contradiction
+// lens), not prose, and deslop's contrast-cutting must not fight RFC-2119
+// modality.
+const PROSE_PATH_RE = /^docs\/(articles|presentations)\//;
+const NARRATIVE_DOC_RE = /^docs\/[^/]+\.(md|markdown)$/;
+// #1442 review finding: the skills/docs/** exemption must hold for the README
+// rule too. PROSE_PATH_RE / NARRATIVE_DOC_RE are anchored to `docs/` so
+// skills/docs files never match them; the README basename rule is the ONLY
+// path by which a skills/docs file could be classified prose (e.g. a future
+// `skills/docs/README-*.md`). Carve the normative-contract subtree out
+// explicitly so a README-named contract never arms deslop.
+const SKILLS_DOCS_EXEMPT_RE = /^(skills\/docs|\x2eclaude\/skills\/docs)\//;
+
+/**
+ * Whether a file path is on the prose surface (#1442): docs/articles/**,
+ * docs/presentations/**, README*, or a narrative direct-child docs/*.md.
+ * skills/docs/** (and .claude/skills/docs/**) is exempt (normative
+ * contracts, not prose) across ALL rules, including the README basename rule.
+ *
+ * @param {string} filePath
+ * @returns {boolean}
+ */
+export function isProsePath(filePath) {
+  // #1442 review finding (input-validation): exported trust-boundary guard.
+  // Fail closed (false) on a non-string/empty argument rather than crashing in
+  // normalizeSep(filePath).replaceAll(...).
+  if (typeof filePath !== "string" || filePath.length === 0) return false;
+  const fp = normalizeSep(filePath);
+  if (SKILLS_DOCS_EXEMPT_RE.test(fp)) return false;
+  if (PROSE_PATH_RE.test(fp)) return true;
+  if (NARRATIVE_DOC_RE.test(fp)) return true;
+  const base = fp.split("/").pop() ?? "";
+  if (base.startsWith("README")) return true;
+  return false;
+}
+
 /**
  * @typedef {object} T0Result
  * @property {string[]} files — flat file paths
@@ -56,6 +94,13 @@ export function analyzeT0(nameStatusOutput) {
   const extensions = new Set();
   const directories = new Set();
   let renameCount = 0;
+  // #1442 review finding: prose arming must be scoped to content-carrying
+  // rows. A pure deletion (`D` name-status row) has no prose content for the
+  // deslop reviewer to strip — arming deslop on it over-selects and re-runs
+  // the fan-out over a content-free delta. Added/modified/renamed-dest rows
+  // (A / M / M? / R-dest) carry content and still arm prose. Rename rows emit
+  // `R<score>\told\tnew` (rawPath = parts[2], the new content-bearing path).
+  let prosePresent = false;
 
   for (const line of lines) {
     const parts = line.split("\t");
@@ -73,6 +118,16 @@ export function analyzeT0(nameStatusOutput) {
     if (dir) directories.add(dir);
 
     if (status.startsWith("R")) renameCount++;
+    // #1442: a content-carrying prose file arms PROSE_PRESENT → deslop. Pure
+    // deletions (`D`) are excluded (no prose content to strip, avoids noise);
+    // a pure `R100` rename (git's 100% similarity score — no content changed)
+    // is likewise content-free and must not arm deslop. Renames with a score
+    // below 100 (`R<score>\told\tnew`, rawPath = the new content-bearing path)
+    // carry content and still arm prose.
+    if (prosePresent) continue;
+    if (status === "D" || status.startsWith("D")) continue;
+    if (status.startsWith("R") && status === "R100") continue;
+    if (isProsePath(path)) prosePresent = true;
   }
 
   const renameOnly = lines.length > 0 && renameCount === lines.length;
@@ -87,6 +142,7 @@ export function analyzeT0(nameStatusOutput) {
     directories: [...directories].sort(),
     renameOnly,
     allDocs,
+    prosePresent,
   };
 }
 
@@ -372,6 +428,7 @@ function t0FileCategories(t0) {
   const categories = [];
   if (t0.renameOnly) categories.push("RENAME_ONLY");
   if (t0.allDocs) categories.push("DOCS_ONLY");
+  if (t0.prosePresent) categories.push("PROSE_PRESENT");
   if (t0.files.every((f) => classifyFile(f) === "config")) categories.push("CONFIG_ONLY");
   if (t0.files.every((f) => classifyFile(f) === "test")) categories.push("TEST_ONLY");
   if (t0.files.every((f) => classifyFile(f) === "ci")) categories.push("CI_ONLY");
@@ -392,6 +449,7 @@ function t0PresentSurfaceCategories(t0) {
   const categories = [];
   const cats = new Set(t0.files.map(classifyFile));
   if (cats.has("docs")) categories.push("DOCS_ONLY");
+  if (t0.prosePresent) categories.push("PROSE_PRESENT");
   if (cats.has("config")) categories.push("CONFIG_ONLY");
   if (cats.has("test")) categories.push("TEST_ONLY");
   if (cats.has("ci")) categories.push("CI_ONLY");
@@ -445,8 +503,17 @@ export function analyzeDiff({ nameStatusOutput, diffOutput }) {
   // When t1 is null (unambiguous diff), infer categories from t0
   // so dynamic angle resolution can narrow for config-only / test-only etc.
   if (!t1) {
+    // #1442 Copilot finding: a genuinely MIXED diff whose T1 never ran (no
+    // diffOutput) must NOT get a T0-only PROSE_PRESENT category. Non-empty
+    // categories set ambiguous=false, so a mixed code+prose diff would
+    // under-select to just deslop + always-include and drop the code-review
+    // core. T0-only inference is only safe for unambiguous diffs (docs-only /
+    // single surface); a mixed diff without hunk content is unclassifiable, so
+    // return empty categories and let resolveDynamicAngles fall back to the
+    // full angle set (fail closed).
+    const changeCategories = t0Ambiguous ? [] : inferCategoriesFromT0(t0);
     t1 = {
-      changeCategories: inferCategoriesFromT0(t0),
+      changeCategories,
       hunkCount: 0,
       lineStats: { added: 0, deleted: 0 },
     };

package/src/claude/hook-decisions.mjs

@@ -10,6 +10,7 @@
  */
 
 import { resolveRunId } from "../loop/run-context.mjs";
+import { isUnderWorktreePath } from "../loop/worktree-guard.mjs";
 import {
   commandContainsGhPrReady,
   commandContainsGhPrMerge,
@@ -22,13 +23,23 @@ import {
   commandContainsRawExternalWrite,
   extractRepoFlagsFromExternalWriteSegments,
   commandContainsGitStash,
+  extractGhApiEndpointSegments,
+  commandContainsSubIssueAdHocBypass,
+  commandContainsReplyResolveBypass,
+  commandContainsGraphqlResolveReviewThread,
+  commandContainsCopilotRequestBypass,
+  commandContainsCopilotSummonComment,
+  commandContainsDetachedWaitTool,
+  commandContainsInlineInterpreter,
   TARGET_REPO_SLUG,
 } from "../loop/bash-command-classify.mjs";
 
 /**
  * @typedef {Object} HookDecision
- * @property {"allow"|"deny"} decision
- * @property {string} [reason] - Human-readable reason (shown to Claude on deny).
+ * @property {"allow"|"deny"|"block"} decision — `block` is the SubagentStop vocabulary
+ *   (exit 2 + stderr JSON), used by `decideSubagentStopGuard`; `allow`/`deny` are the PreToolUse
+ *   vocabulary used by `decideBashGate`/`decideWriteGuard`.
+ * @property {string} [reason] - Human-readable reason (shown to the agent on deny/block).
  */
 
 const ALLOW = Object.freeze({ decision: "allow" });
@@ -78,18 +89,81 @@ export const DEV_LOOP_AGENT_TYPE = "dev-loop";
  * @param {boolean} [params.gatePassed] - Whether the relevant gate evidence exists for the PR.
  * @param {string|null} [params.gateError] - Error detail when the gate guard could not run.
  * @param {string|null} [params.agentType] - Claude `agent_type` from the hook payload; non-null
- *   string inside a subagent, null in the main agent. Scopes the external-write guard.
+ *   string inside a subagent, null in the main agent. Scopes the subagent-only predicates.
+ * @param {boolean} [params.humanMergeOnly] - Effective repo `autonomy.humanMergeOnly` invariant
+ *   (`resolveHumanMergeOnly`); when true, `gh pr merge` is refused actor-independently
+ *   (STOP-HUMAN-MERGE-001), because the main agent is the actor that performs GitHub writes and a
+ *   subagent-only deny would enforce nothing.
  * @returns {HookDecision}
  */
-export function decideBashGate({ command, repoSlug = null, gatePassed = false, gateError = null, agentType = null }) {
+export function decideBashGate({ command, repoSlug = null, gatePassed = false, gateError = null, agentType = null, humanMergeOnly = false }) {
   if (typeof command !== "string") {
     return ALLOW;
   }
+  // Normalize (trim + case-fold) so a divergent slug (surrounding whitespace, casing) does not
+  // silently fail OPEN and disable every guard that depends on inTargetRepo (#1622).
+  const inTargetRepo = (repoSlug ?? "").trim().toLowerCase() === TARGET_REPO_SLUG.trim().toLowerCase();
+
+  // OPS-NO-INLINE-INTERPRETER (#1622): inline interpreters (`node -e`/`--eval`/`-p`, `python3 -c`,
+  // heredocs fed to node/python) are barred actor-independently on the target repo — the rule bars
+  // "Coordinator and agent flows"; sanctioned output parsing uses `--jq`/`--silent`, never an
+  // inline interpreter.
+  if (inTargetRepo && commandContainsInlineInterpreter(command)) {
+    return {
+      decision: "deny",
+      reason:
+        "OPS-NO-INLINE-INTERPRETER: inline interpreters (node -e/--eval/-p, python3 -c, heredoc to " +
+        "node/python) are barred in the dev-loop flow. Parse tool output via --jq/--silent and mutate " +
+        "files via the editor/patch tools or a --jq-composed --body-file, never an inline interpreter.",
+    };
+  }
+
+  // SUBISSUE-NO-ADHOC-BYPASS (#1622): ad-hoc `gh api` writes to the target repo's sub-issue endpoints.
+  // Actor-independent (no reserved direct path). Gated on the target repo: the absolute slug-embedded
+  // form identifies the target repo; the bare relative form (`gh api issues/5/sub_issues`) resolves
+  // against the cwd repo, so it is in scope only when running in the target repo (mirrors the #1047
+  // explicit-`--repo`/cwd-target posture).
+  if (inTargetRepo && commandContainsSubIssueAdHocBypass(command)) {
+    return {
+      decision: "deny",
+      reason:
+        "SUBISSUE-NO-ADHOC-BYPASS: ad-hoc `gh api` writes to the target repo's sub_issues endpoint are " +
+        "blocked. Manage sub-issues via the sanctioned manage-sub-issues wrapper instead.",
+    };
+  }
+
+  // COPILOT-FOLLOWUP-REPLY-RESOLVE-HELPER (#1622): ad-hoc thread-resolution writes — raw `gh api` POST
+  // to pulls/<n>/comments/<m>/replies, or a `gh api graphql` resolveReviewThread mutation (the Rest
+  // path names the target repo; the graphql form has no path-host repo, so it is scoped to the cwd
+  // repo). Actor-independent: reply through reply-resolve-review-thread(s).mjs.
+  if (inTargetRepo && (commandContainsReplyResolveBypass(command) || commandContainsGraphqlResolveReviewThread(command))) {
+    return {
+      decision: "deny",
+      reason:
+        "COPILOT-FOLLOWUP-REPLY-RESOLVE-HELPER: ad-hoc thread-reply mutations are blocked. Resolve review " +
+        "threads via scripts/github/reply-resolve-review-thread.mjs (one thread) or " +
+        "reply-resolve-review-threads.mjs (multiple threads, --message-map), not raw gh api/graphql.",
+    };
+  }
+
+  // COPILOT-FOLLOWUP-REQUEST-HELPER-ONLY (#1622): ad-hoc Copilot review requests — raw `gh api` writes
+  // to pulls/<n>/requested_reviewers, or a bare `/copilot` / `/copilot re-review` comment summon on the
+  // target repo. Actor-independent: request Copilot via scripts/github/request-copilot-review.mjs.
+  if (inTargetRepo && (commandContainsCopilotRequestBypass(command) || commandContainsCopilotSummonComment(command))) {
+    return {
+      decision: "deny",
+      reason:
+        "COPILOT-FOLLOWUP-REQUEST-HELPER-ONLY: ad-hoc Copilot review requests are blocked. Request Copilot " +
+        "via scripts/github/request-copilot-review.mjs — do not write requested_reviewers or post a literal " +
+        "/copilot comment.",
+    };
+  }
+
   // `git stash` writes to `refs/stash`, one ref shared by every worktree over this repo's single
   // `.git` directory — a stash from one worktree can pop into another's. Block it outright on the
   // target repo; see skills/docs/worktree-guidance.md#never-git-stash-in-a-shared-git-layout for the
   // stash-free alternative (git diff / a patch file / a scratch checkout).
-  if (commandContainsGitStash(command) && (repoSlug ?? "").toLowerCase() === TARGET_REPO_SLUG.toLowerCase()) {
+  if (commandContainsGitStash(command) && inTargetRepo) {
     return {
       decision: "deny",
       reason:
@@ -130,7 +204,36 @@ export function decideBashGate({ command, repoSlug = null, gatePassed = false, g
   const isReady = commandContainsGhPrReady(command);
   const isMerge = commandContainsGhPrMerge(command);
   const isCreate = commandContainsGhPrCreate(command);
+
+  // STOP-HUMAN-MERGE-001 (#1622): when the repo resolves `autonomy.humanMergeOnly`, `gh pr merge` is
+  // refused actor-independently — the main agent is the actor that performs GitHub writes, so only an
+  // actor-independent deny enforces the human-merge invariant (an agent-scoped deny would enforce
+  // nothing on the main-agent write path).
+  if (humanMergeOnly && isMerge && inTargetRepo) {
+    return {
+      decision: "deny",
+      reason:
+        "STOP-HUMAN-MERGE-001: this repo resolves autonomy.humanMergeOnly — the loop must stop at merge " +
+        "for a human action; the agent MUST NOT run `gh pr merge`. Leave the PR merge-ready and a human " +
+        "merges it.",
+    };
+  }
+
   if (!isReady && !isMerge && !isCreate) {
+    // COPILOT-FOLLOWUP-WAIT-TOOLS (#1622): banned detached/polling wait wrappers. Subagent-only — the
+    // rule is classified `agent` (behavioral guidance for the dev-loop driving agent); the main
+    // agent/operator retains manual wait tooling. The main agent's own sanctioned wait path is still
+    // the deterministic tools.
+    if (typeof agentType === "string" && inTargetRepo && commandContainsDetachedWaitTool(command)) {
+      return {
+        decision: "deny",
+        reason:
+          "COPILOT-FOLLOWUP-WAIT-TOOLS: wait only through deterministic tools (scripts/loop/detect-copilot-" +
+          "loop-state.mjs one-shot, dev-loops loop watch-cycle persistent, scripts/github/wait-pr-checks.mjs, " +
+          "gh run watch) — nohup/disown/tmux/screen detach and while-sleep-poll loops are barred for the " +
+          "dev-loop driving agent.",
+      };
+    }
     return ALLOW;
   }
 
@@ -265,3 +368,99 @@ export function decideWriteGuard({ filePath, isRepoMutation, enforce = false, en
       "See skills/docs/main-agent-contract.md.",
   };
 }
+
+/**
+ * Env var that exempts an interactive session awaiting commit authorization from the
+ * SubagentStop uncommitted-work guard (#1619).
+ *
+ * An opt-in signal set by the operator or the interactive coordination path
+ * (`DEVLOOPS_COMMIT_AUTH_PENDING=1`) when intentionally holding uncommitted work pending
+ * operator commit authorization — consistent with the operator-set `DEVLOOPS_*` env vars in
+ * this repo (`DEVLOOPS_MAIN_AGENT_READONLY`, `DEVLOOPS_ALLOW_MAIN`, `DEVLOOPS_SUBAGENT_AVAILABLE`),
+ * which are environment/operator signals rather than values written by a code path. A
+ * non-interactive (dispatched) subagent leaves it unset, so its commit-before-exit obligation
+ * stays enforced.
+ */
+export const DEVLOOPS_COMMIT_AUTH_PENDING_VAR = "DEVLOOPS_COMMIT_AUTH_PENDING";
+
+/**
+ * Env var that exempts an orchestrator-owned-commit dispatch from the SubagentStop
+ * uncommitted-work guard (#1786).
+ *
+ * A "LOCAL EDITS ONLY: no commit" dispatch (e.g. the `developer`/`quality`/`docs` delegation
+ * pattern in `skills/local-implementation/SKILL.md` "Delegation contract") tells the subagent to
+ * make local edits and report changed files, leaving commit + push to the dispatching
+ * orchestrator once it consolidates results. Without an exemption, that subagent's own
+ * SubagentStop event still sees the dirty worktree it was told not to commit and deadlocks. The
+ * dispatcher sets `DEVLOOPS_ORCHESTRATOR_OWNS_COMMIT=1` for that dispatch to declare it owns the
+ * commit — same opt-in `DEVLOOPS_*` signal shape as `DEVLOOPS_COMMIT_AUTH_PENDING`, but distinct:
+ * this one exempts a non-interactive delegated dispatch whose commit responsibility sits with its
+ * caller, not an interactive session awaiting operator authorization. Left unset, an ordinary
+ * dispatch's commit-before-exit obligation stays enforced (fail closed by default).
+ */
+export const DEVLOOPS_ORCHESTRATOR_OWNS_COMMIT_VAR = "DEVLOOPS_ORCHESTRATOR_OWNS_COMMIT";
+
+/**
+ * Decide whether a SubagentStop must be blocked because the subagent's worktree has
+ * uncommitted changes (#1619).
+ *
+ * `scripts/loop/cleanup-worktree.mjs` runs `git worktree remove --force` after a merge, so
+ * uncommitted changes in a worktree are destroyed with no warning. `LOCAL-COMMIT-BEFORE-EXIT`
+ * existed only as prose. This decider makes it mechanical: refuse the subagent stop when the
+ * cwd is under `tmp/worktrees/` and `git status --porcelain` is non-empty, unless the session
+ * is an interactive one awaiting commit authorization, or the dispatch is an explicit
+ * orchestrator-owned-commit exemption (#1786) (either exempt). A clean worktree, a cwd
+ * outside `tmp/worktrees/`, and a git-error/empty-porcelain case all allow the stop.
+ *
+ * Pure and side-effect free. The hook script gathers `cwd` and the `git status --porcelain`
+ * output and calls this; the block decision is surfaced via exit code 2 + stderr JSON by the
+ * hook (the SubagentStop contract differs from PreToolUse's `permissionDecision` form).
+ *
+ * @param {Object} params
+ * @param {string|undefined} params.cwd - Current working directory; a non-string value is
+ *   treated as out of scope (allow) — the decider is fail-safe.
+ * @param {string|undefined} params.porcelain - Raw `git status --porcelain` output; a non-string
+ *   or empty value is treated as clean (allow) — the decider is fail-safe.
+ * @param {boolean} [params.pendingCommitAuthorization] - True when the interactive session is
+ *   awaiting commit authorization (exempt) — derived by the hook script from the
+ *   `DEVLOOPS_COMMIT_AUTH_PENDING=1` opt-in env signal.
+ * @param {boolean} [params.orchestratorOwnsCommit] - True when this dispatch is an explicit
+ *   orchestrator-owned-commit exemption (exempt) — derived by the hook script from the
+ *   `DEVLOOPS_ORCHESTRATOR_OWNS_COMMIT=1` opt-in env signal.
+ * @returns {HookDecision}
+ */
+export function decideSubagentStopGuard({ cwd, porcelain, pendingCommitAuthorization = false, orchestratorOwnsCommit = false }) {
+  if (typeof cwd !== "string" || !isUnderWorktreePath(cwd)) {
+    return ALLOW;
+  }
+  if (pendingCommitAuthorization || orchestratorOwnsCommit) {
+    return ALLOW;
+  }
+  if (typeof porcelain !== "string" || porcelain.trim() === "") {
+    return ALLOW;
+  }
+  const dirty = porcelain
+    .split("\n")
+    .map((l) => l.trim())
+    .filter(Boolean);
+  // The reason is fed back to the stopping subagent as context, so the path
+  // enumeration is capped: an unbounded list on a very dirty worktree produces a
+  // multi-megabyte reason that consumers truncate or choke on, burying the one
+  // actionable line. The "Dirty paths (N):" header below always carries the full
+  // dirty count; the trailing "… and X more" line (when present) carries the
+  // remaining count past the cap, not the full total.
+  const MAX_LISTED_DIRTY_PATHS = 50;
+  const listed = dirty.slice(0, MAX_LISTED_DIRTY_PATHS).map((p) => "  " + p);
+  if (dirty.length > MAX_LISTED_DIRTY_PATHS) {
+    listed.push(`  … and ${dirty.length - MAX_LISTED_DIRTY_PATHS} more (run \`git status --porcelain\` for the full list)`);
+  }
+  return {
+    decision: "block",
+    reason:
+      "LOCAL-COMMIT-BEFORE-EXIT: the worktree has uncommitted changes — refusing subagent exit " +
+      "to prevent silent data loss from post-merge worktree cleanup (cleanup-worktree.mjs runs " +
+      "`git worktree remove --force`). Commit your work before stopping. " +
+      `Dirty paths (${dirty.length}):\n` +
+      listed.join("\n"),
+  };
+}

package/src/cli/primitives.mjs

@@ -1,4 +1,6 @@
 import { spawn } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
 import { parseArgs } from "node:util";
 
 /**
@@ -113,7 +115,7 @@ export function parsePositiveInteger(value, flag, parseError = null) {
 
 export function parseNonNegativeInteger(value, flag, parseError = null) {
   if (!/^\d+$/.test(value)) {
-    throw toCliError(`${flag} must be a non-negative integer`, parseError);
+    throw toCliError(`${flag} must be a non-negative integer, got "${value}"`, parseError);
   }
   return Number(value);
 }
@@ -126,6 +128,27 @@ export function parseIssueNumber(value, parseError = null) {
   return parsePositiveInteger(value, "--issue", parseError);
 }
 
+// Parse a comma-separated allowlist of numeric issue/PR ids (e.g. `1670,9000`
+// from an `--allowed-refs` CLI option). Returns the ids as deduped numeric
+// strings, empty array for an empty/whitespace-only input. Rejects any
+// non-numeric (or zero) entry so a typo can never silently allowlist nothing.
+export function parseAllowedRefsCsv(value, flag, parseError = null) {
+  const parts = String(value ?? "")
+    .split(",")
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+  const ids = [];
+  for (const part of parts) {
+    if (!/^\d+$/u.test(part) || Number(part) === 0) {
+      throw toCliError(`${flag} must be a comma-separated list of positive integers (got ${JSON.stringify(part)})`, parseError);
+    }
+    if (!ids.includes(part)) {
+      ids.push(part);
+    }
+  }
+  return ids;
+}
+
 // `stdinText` is optional and additive: omit it and stdin stays closed exactly
 // as before. Supply it (a `gh api ... --input -` payload) and it is piped in,
 // so a caller that needs stdin no longer has to reach for a second, separately
@@ -146,6 +169,33 @@ export function runChild(command, args, env = process.env, stdinText = undefined
   });
 }
 
+/**
+ * Resolve a `--body <text>` / `--body-file <path>` pair to the actual body
+ * string, the one file-reading step every `--body-file` CLI flag in this repo
+ * needs: read the file (or stdin, when `allowStdin` and `bodyFile === "-"`)
+ * and FAIL CLOSED (throw) on an empty/whitespace-only result, so a blank or
+ * unreadable `--body-file` can never silently clear a PR/comment body. When
+ * `bodyFile` is absent, `body` is returned unchanged (no emptiness check —
+ * callers that must reject an empty inline `--body` do that themselves,
+ * since not every caller enforces it).
+ *
+ * @param {object} input
+ * @param {string} [input.body] — inline body value, returned as-is when no bodyFile
+ * @param {string} [input.bodyFile] — path to read the body from ("-" = stdin, when allowStdin)
+ * @param {boolean} [input.allowStdin] — honor `bodyFile === "-"` as stdin (fd 0); default false
+ * @returns {Promise<string | undefined>}
+ */
+export async function resolveBodyOrFile({ body, bodyFile, allowStdin = false } = {}) {
+  if (bodyFile === undefined || bodyFile === null) return body;
+  // fs/promises readFile does not accept an integer fd, so stdin (fd 0) is
+  // read synchronously via readFileSync, which does accept one.
+  const content = allowStdin && bodyFile === "-" ? readFileSync(0, "utf8") : await readFile(bodyFile, "utf8");
+  if (content.trim().length === 0) {
+    throw new Error(`--body-file ${bodyFile} is empty`);
+  }
+  return content;
+}
+
 export function runCommand(command, args, { cwd = process.cwd(), env = process.env } = {}) {
   return new Promise((resolve, reject) => {
     const child = spawn(command, args, { cwd, env, stdio: ["ignore", "pipe", "pipe"] });