@dev-loops/core 0.3.0 → 0.4.0

package/package.json

@@ -1,7 +1,10 @@
 {
   "name": "@dev-loops/core",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
   "description": "Shared deterministic support package for dev-loop skills, repo-local scripts, and GitHub automation.",
   "exports": {
     "./bash-exit-one": "./src/bash-exit-one.mjs",

package/src/config/config.mjs

@@ -75,6 +75,30 @@ const AutonomyConfig = z.strictObject({
   stopAt: z.array(
     z.enum(["refinement", "draft-pr", "pre-approval", "merge"])
   ),
+  // When true, merge is a fixed, non-overridable human action: the agent never
+  // runs `gh pr merge`, `resolveAutonomyStopAt` always includes "merge", and
+  // any per-run merge authorization (envelope flag / explicit instruction) is
+  // ignored — it fails closed. See resolveHumanMergeOnly / resolveEffectiveMergeAuthorized.
+  humanMergeOnly: z.boolean().optional(),
+});
+
+/**
+ * Human-handoff config (#920, Request B of #910): at the pre-approval /
+ * merge-handoff boundary, OFFER to assign the PR to a named human
+ * reviewer/assignee. Opt-in (default off). Pairs with autonomy.humanMergeOnly.
+ * `candidatesFrom` selects which sources the resolver queries; `assignees` is a
+ * static highest-priority candidate list. Absent/empty = disabled no-op.
+ */
+const HumanHandoffConfig = z.strictObject({
+  enabled: z.boolean().default(false),
+  candidatesFrom: z
+    .array(z.enum(["codeowners", "recent-committers"]))
+    .optional(),
+  assignees: z.array(z.string().trim().min(1)).optional(),
+});
+
+const ApprovalConfig = z.strictObject({
+  humanHandoff: HumanHandoffConfig.optional(),
 });
 
 const WorkflowConfig = z.strictObject({
@@ -104,6 +128,18 @@ const QueueConfig = z.strictObject({
   archiveOlderThanDays: z.number().int().positive().optional(),
 });
 
+/**
+ * Worktree lifecycle config (#909): which gitignored files/dirs to provision
+ * into a fresh worktree from the main checkout. Entries are repo-relative
+ * literal paths OR glob patterns. `copyOnInit` → `fs.cp` (isolated per
+ * worktree); `linkOnInit` → absolute symlink into the main checkout (read-only
+ * data). Both optional; empty/absent is a valid no-op.
+ */
+const WorktreeConfig = z.strictObject({
+  copyOnInit: z.array(z.string().trim().min(1)).optional(),
+  linkOnInit: z.array(z.string().trim().min(1)).optional(),
+});
+
 /** Internal path whitelist for internal-only PR detection — flat array of regex strings */
 const InternalPatternsConfig = z.array(z.string().trim().min(1)).min(1);
 
@@ -147,11 +183,13 @@ export const DevLoopConfigSchema = z.strictObject({
   refinement: RefinementConfig.optional(),
   gates: GatesConfig.optional(),
   autonomy: AutonomyConfig.optional(),
+  approval: ApprovalConfig.optional(),
   workflow: WorkflowConfig.optional(),
   localImplementation: LocalImplementationConfig.optional(),
   queue: QueueConfig.optional(),
   personas: PersonasConfig.optional(),
   internalPathPatterns: InternalPatternsConfig.optional(),
+  worktree: WorktreeConfig.optional(),
 });
 
 // ============================================================================
@@ -165,7 +203,14 @@ export const BUILT_IN_DEFAULTS = Object.freeze({
   models: Object.freeze({}),
   refinement: Object.freeze({ fanOut: 3, mode: "parallel", maxCopilotRounds: 5, stopOnLowSignal: false, lowSignalRoundThreshold: 3, lowSignalMaxComments: 2 }),
   gates: Object.freeze({}),
-  autonomy: Object.freeze({ stopAt: Object.freeze(["merge"]) }),
+  autonomy: Object.freeze({ stopAt: Object.freeze(["merge"]), humanMergeOnly: false }),
+  approval: Object.freeze({
+    humanHandoff: Object.freeze({
+      enabled: false,
+      candidatesFrom: Object.freeze([]),
+      assignees: Object.freeze([]),
+    }),
+  }),
   workflow: Object.freeze({
     asyncStartMode: "required",
     requireRetrospective: false,
@@ -193,6 +238,7 @@ export const BUILT_IN_DEFAULTS = Object.freeze({
     "^\\.github/",
     "^test/",
   ]),
+  worktree: Object.freeze({ copyOnInit: Object.freeze([]), linkOnInit: Object.freeze([]) }),
 });
 
 // ============================================================================
@@ -207,11 +253,13 @@ export const FileConfigSchema = z.strictObject({
   refinement: RefinementConfig.partial().optional(),
   gates: FileGatesConfig.optional(),
   autonomy: AutonomyConfig.partial().optional(),
+  approval: ApprovalConfig.partial().optional(),
   workflow: WorkflowConfig.partial().optional(),
   localImplementation: LocalImplementationConfig.partial().optional(),
   queue: QueueConfig.partial().optional(),
   personas: FilePersonasConfig.optional(),
   internalPathPatterns: InternalPatternsConfig.optional(),
+  worktree: WorktreeConfig.partial().optional(),
 });
 
 // ============================================================================
@@ -727,10 +775,66 @@ export function resolveConductorModel(config) {
  * @returns {string[]}
  */
 export function resolveAutonomyStopAt(config) {
-  if (config?.autonomy?.stopAt && Array.isArray(config.autonomy.stopAt)) {
-    return [...config.autonomy.stopAt];
+  const base = (config?.autonomy?.stopAt && Array.isArray(config.autonomy.stopAt))
+    ? [...config.autonomy.stopAt]
+    : ["merge"];
+  // Fail closed: humanMergeOnly forces a human stop at merge regardless of
+  // what stopAt is configured (even an explicit []).
+  if (resolveHumanMergeOnly(config) && !base.includes("merge")) {
+    base.push("merge");
   }
-  return ["merge"];
+  return base;
+}
+
+/**
+ * Resolve the fixed human-merge-only invariant from the merged dev-loop config.
+ *
+ * When true, the agent must never perform the merge itself: `gh pr merge` is a
+ * human-only action and any per-run merge authorization is ignored. Defaults to
+ * false (the agent may merge once authorized).
+ *
+ * @param {DevLoopConfig} config
+ * @returns {boolean}
+ */
+export function resolveHumanMergeOnly(config) {
+  return config?.autonomy?.humanMergeOnly === true;
+}
+
+/**
+ * Authoritative gate: resolve the effective merge authorization for the agent.
+ *
+ * This is the single chokepoint that decides whether the agent is cleared to
+ * run `gh pr merge`. When `humanMergeOnly` is set on the repo config, this
+ * ALWAYS returns false — the per-run `mergeAuthorized` flag (envelope flag or
+ * explicit "merge" instruction) cannot override the repo invariant. Fails
+ * closed: a non-boolean `mergeAuthorized` is treated as not authorized.
+ *
+ * @param {boolean} mergeAuthorized per-run authorization signal
+ * @param {DevLoopConfig} config merged dev-loop config
+ * @returns {boolean}
+ */
+export function resolveEffectiveMergeAuthorized(mergeAuthorized, config) {
+  if (resolveHumanMergeOnly(config)) return false;
+  return mergeAuthorized === true;
+}
+
+/**
+ * Authoritative gate for callers that load the config themselves and hold its
+ * `{ config, errors }` load result. FAILS CLOSED on any config load/validation
+ * error: `loadDevLoopConfig` never throws (it returns an `errors` array), so a
+ * caller must not assume "no exception" means "config is safe". If the config
+ * could not be loaded/validated, the `.devloops` file declaring `humanMergeOnly`
+ * may be the very one that failed — so merge authorization is denied rather than
+ * silently granted from a fallback config that lacks the invariant.
+ *
+ * @param {boolean} mergeAuthorized per-run authorization signal
+ * @param {{ config?: DevLoopConfig, errors?: Array<unknown> }} loadResult result of `loadDevLoopConfig`
+ * @returns {boolean}
+ */
+export function resolveEffectiveMergeAuthorizedFromLoad(mergeAuthorized, loadResult) {
+  const errors = loadResult?.errors ?? [];
+  if (errors.length > 0) return false;
+  return resolveEffectiveMergeAuthorized(mergeAuthorized, loadResult?.config);
 }
 
 const DEFAULT_REFINEMENT_CONFIG = BUILT_IN_DEFAULTS.refinement;
@@ -1053,6 +1157,61 @@ const DEFAULT_INTERNAL_PATH_PATTERNS = BUILT_IN_DEFAULTS.internalPathPatterns;
  * @param {DevLoopConfig} config
  * @returns {string[]}
  */
+/**
+ * Resolve the worktree lifecycle config from the merged dev-loop config.
+ *
+ * Returns `{ copyOnInit, linkOnInit }` with empty-array defaults when the
+ * config omits the `worktree` section or either list. Entries are trimmed,
+ * repo-relative literal paths or glob patterns expanded against the main
+ * checkout at provision time. See scripts/loop/provision-worktree.mjs.
+ *
+ * @param {DevLoopConfig} config
+ * @returns {{ copyOnInit: string[], linkOnInit: string[] }}
+ */
+export function resolveWorktreeConfig(config) {
+  const wt = config?.worktree;
+  const list = (v) =>
+    Array.isArray(v)
+      ? v.map((s) => (typeof s === "string" ? s.trim() : "")).filter((s) => s.length > 0)
+      : [];
+  return { copyOnInit: list(wt?.copyOnInit), linkOnInit: list(wt?.linkOnInit) };
+}
+
+/**
+ * Resolve the human-handoff config from the merged dev-loop config (#920).
+ *
+ * Returns a normalized `{ enabled, candidatesFrom, assignees }`. Defaults to
+ * disabled with empty arrays when the `approval.humanHandoff` section is absent.
+ * When disabled (default), this is a no-op: callers must not source candidates
+ * or assign anyone. Pairs with `autonomy.humanMergeOnly`: when human-merge is
+ * enforced, this names who should take the merge.
+ *
+ * @param {DevLoopConfig} config
+ * @returns {{ enabled: boolean, candidatesFrom: ("codeowners"|"recent-committers")[], assignees: string[] }}
+ */
+export function resolveHumanHandoffConfig(config) {
+  const hh = config?.approval?.humanHandoff;
+  const enabled = hh?.enabled === true;
+  const list = (v) =>
+    Array.isArray(v)
+      ? v.map((s) => (typeof s === "string" ? s.trim() : "")).filter((s) => s.length > 0)
+      : [];
+  const candidatesFrom = list(hh?.candidatesFrom).filter(
+    (s) => s === "codeowners" || s === "recent-committers"
+  );
+  // Normalize assignees: strip a leading `@`, trim, and drop empties so an empty
+  // login (e.g. config value of `"@"` or `""`) can never leak downstream into
+  // `gh pr edit --add-assignee ""`.
+  const assignees = list(hh?.assignees)
+    .map((s) => s.replace(/^@/, "").trim())
+    .filter((s) => s.length > 0);
+  return {
+    enabled,
+    candidatesFrom: enabled ? candidatesFrom : [],
+    assignees: enabled ? assignees : [],
+  };
+}
+
 export function resolveInternalPathPatterns(config) {
   if (
     config?.internalPathPatterns &&

package/src/loop/async-start-contract.mjs

@@ -10,10 +10,9 @@
  * async context marker. When the marker is absent, the check fails closed
  * and returns a machine-readable rejection rather than silently proceeding.
  *
- * Async context markers (required when workflow.asyncStartMode is `required`),
- * neutral-first — see `@dev-loops/core/loop/run-context`:
+ * Async context marker (required when workflow.asyncStartMode is `required`)
+ * — see `@dev-loops/core/loop/run-context`:
  * - DEVLOOPS_RUN_ID env var (neutral, harness-agnostic)
- * - PI_SUBAGENT_RUN_ID env var (Pi subagent framework; retained as a compatibility alias)
  *
  * Allowed modes:
  * - workflow.asyncStartMode: required | allowed
@@ -30,11 +29,10 @@ import { RUN_ID_MARKERS, isClaudeHarness } from "./run-context.mjs";
 // ---------------------------------------------------------------------------
 
 /**
- * Environment variable names that indicate an async context, neutral-first.
+ * Environment variable names that indicate an async context.
  * Sourced from the shared run-context contract so the markers stay in one place.
- * The historical name is kept for back-compat; it now includes DEVLOOPS_RUN_ID.
  */
-export const PI_ASYNC_CONTEXT_MARKERS = RUN_ID_MARKERS;
+export const ASYNC_CONTEXT_MARKERS = RUN_ID_MARKERS;
 
 /** Supported workflow async-start modes. */
 export const ASYNC_START_MODE = Object.freeze({
@@ -130,8 +128,8 @@ export function validateAsyncStartContext({
     };
   }
 
-  // Check for any async context marker (neutral DEVLOOPS_RUN_ID or the Pi alias)
-  for (const marker of PI_ASYNC_CONTEXT_MARKERS) {
+  // Check for any async context marker (DEVLOOPS_RUN_ID)
+  for (const marker of ASYNC_CONTEXT_MARKERS) {
     const value = env[marker];
     if (typeof value === "string" && value.trim().length > 0) {
       return {
@@ -150,24 +148,7 @@ export function validateAsyncStartContext({
     };
   }
 
-  const sessionOnlyMarker =
-    (typeof env.PI_SESSION_ID === "string" && env.PI_SESSION_ID.trim().length > 0)
-      ? "PI_SESSION_ID"
-      : ((typeof env.PI_ASYNC_CONTEXT === "string" && env.PI_ASYNC_CONTEXT.trim().length > 0)
-          ? "PI_ASYNC_CONTEXT"
-          : null);
-  if (sessionOnlyMarker !== null) {
-    return {
-      status: ASYNC_START_STATUS.REJECTED,
-      reason:
-        `Detected ${sessionOnlyMarker}, but GitHub-first async-start requires a visible ` +
-        "subagent run id for inspectable startup/resume evidence. " +
-        "Set DEVLOOPS_RUN_ID (or the PI_SUBAGENT_RUN_ID alias) to proceed. Any exception must come from repository-maintained workflow policy.",
-      detectedMarker: null,
-    };
-  }
-
-  if (env.PI_DEV_LOOP_DETACHED === "1") {
+  if (env.DEVLOOPS_DETACHED === "1") {
     return {
       status: ASYNC_START_STATUS.REJECTED,
       reason:
@@ -185,7 +166,7 @@ export function validateAsyncStartContext({
       "No async context detected. " +
       "The dev-loop must run within a visible async subagent session, " +
       "not as a detached local process. " +
-      `Set ${PI_ASYNC_CONTEXT_MARKERS[0]} (or the PI_SUBAGENT_RUN_ID alias) to proceed. ` +
+      `Set ${ASYNC_CONTEXT_MARKERS[0]} to proceed. ` +
       "Repository-maintained workflow policy controls any exceptions.",
     detectedMarker: null,
   };

package/src/loop/handoff-envelope.mjs

@@ -21,6 +21,7 @@ import {
 import { normalizeRepoSlug } from "../github/repo-slug.mjs";
 import { COPILOT_REVIEW_WAIT_TIMEOUT_MS } from "./policy-constants.mjs";
 import { resolveEffectiveAsyncStartMode } from "./async-start-contract.mjs";
+import { resolveHumanMergeOnly } from "../config/config.mjs";
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -243,10 +244,18 @@ function deriveTarget(bundle, repo) {
 // ---------------------------------------------------------------------------
 
 function deriveStopRules(settings, strategy) {
-  if (settings?.autonomy?.stopAt && Array.isArray(settings.autonomy.stopAt)) {
-    return [...settings.autonomy.stopAt];
+  const base = (settings?.autonomy?.stopAt && Array.isArray(settings.autonomy.stopAt))
+    ? [...settings.autonomy.stopAt]
+    : [...(STRATEGY_DEFAULT_STOP_RULES[strategy] ?? [])];
+  // Fail closed: humanMergeOnly forces "merge" into the dispatched agent's
+  // stopRules regardless of configured stopAt, mirroring the authoritative
+  // resolveAutonomyStopAt(config) invariant. Without this, a custom
+  // stopAt that omits "merge" (e.g. [] or ["draft-pr"]) would tell the agent
+  // NOT to stop at merge — a direct humanMergeOnly bypass.
+  if (resolveHumanMergeOnly(settings) && !base.includes("merge")) {
+    base.push("merge");
   }
-  return [...(STRATEGY_DEFAULT_STOP_RULES[strategy] ?? [])];
+  return base;
 }
 
 // ---------------------------------------------------------------------------
@@ -316,28 +325,61 @@ function deriveCwd(bundle, options = {}) {
   const kind = normalizeTargetKind(artifact.kind);
 
   if (root) {
+    // issue/pr go through the single source of truth (resolveWorktreePath); other
+    // slug kinds (local_branch/local_phase) still use the namespace + slug.
+    if (kind === DEV_LOOP_TARGET_KIND.ISSUE && Number.isInteger(artifact.issue) && artifact.issue > 0) {
+      return resolveWorktreePath({ repoRoot: root, kind: "issue", number: artifact.issue });
+    }
+    if (kind === DEV_LOOP_TARGET_KIND.PR && Number.isInteger(artifact.pr) && artifact.pr > 0) {
+      return resolveWorktreePath({ repoRoot: root, kind: "pr", number: artifact.pr });
+    }
     const slug = buildWorktreeSlug(artifact, kind);
     if (slug) {
-      return `${root}/tmp/worktrees/${slug}`;
+      return `${root}/${WORKTREE_NAMESPACE}/${slug}`;
     }
   }
 
   return null;
 }
 
+/** Repo-relative root for loop-owned worktrees. The `dev-loops/` namespace */
+/** marks them so cleanup can only ever remove its own (issue #909). */
+export const WORKTREE_NAMESPACE = "tmp/worktrees/dev-loops";
+
+/**
+ * Resolve the canonical, namespaced worktree path for an issue/PR. Sole source
+ * of truth shared by create, provision, and cleanup. No branch suffix, so the
+ * path is recomputable from the issue/PR number alone.
+ *
+ * @param {{ repoRoot: string, kind: "issue"|"pr", number: number }} args
+ * @returns {string} Absolute path `<repoRoot>/tmp/worktrees/dev-loops/<kind>-<number>`
+ */
+export function resolveWorktreePath({ repoRoot, kind, number } = {}) {
+  const root = normalizeString(repoRoot);
+  if (!root) throw new Error("resolveWorktreePath: repoRoot is required and must be a non-empty string");
+  const k = typeof kind === "string" ? kind.trim().toLowerCase() : "";
+  if (k !== DEV_LOOP_TARGET_KIND.ISSUE && k !== DEV_LOOP_TARGET_KIND.PR) {
+    throw new Error(`resolveWorktreePath: kind must be "issue" or "pr", got "${kind}"`);
+  }
+  if (!Number.isInteger(number) || number < 1) {
+    throw new Error(`resolveWorktreePath: number must be a positive integer, got ${number}`);
+  }
+  return `${root}/${WORKTREE_NAMESPACE}/${k}-${number}`;
+}
+
 function flattenSlugSegment(s) {
   if (typeof s !== "string") return "";
   return s.replace(/[/\\]/g, "-").replace(/[^a-zA-Z0-9._-]/g, "");
 }
 
 function buildWorktreeSlug(artifact, kind) {
+  // Canonical naming is namespaced + no branch suffix (issue #909) so the path
+  // is recomputable from the issue/PR number alone (cleanup can find it).
   if (kind === DEV_LOOP_TARGET_KIND.ISSUE && Number.isInteger(artifact.issue) && artifact.issue > 0) {
-    const branch = normalizeString(artifact.branch);
-    return branch ? `issue-${artifact.issue}-${flattenSlugSegment(branch)}` : `issue-${artifact.issue}`;
+    return `issue-${artifact.issue}`;
   }
   if (kind === DEV_LOOP_TARGET_KIND.PR && Number.isInteger(artifact.pr) && artifact.pr > 0) {
-    const branch = normalizeString(artifact.branch);
-    return branch ? `pr-${artifact.pr}-${flattenSlugSegment(branch)}` : `pr-${artifact.pr}`;
+    return `pr-${artifact.pr}`;
   }
   if (kind === DEV_LOOP_TARGET_KIND.LOCAL_BRANCH) {
     const branch = normalizeString(artifact.branch);

package/src/loop/lifecycle-state.mjs

@@ -162,6 +162,7 @@ function normalizeLifecycleState(value) {
  *   hasUnresolvedThreads, // boolean: unresolved review threads exist
  *   preApprovalGatePassed, // boolean: current-head pre_approval_gate clean
  *   mergeAuthorized,    // boolean: explicit merge authorization granted
+ *   humanMergeOnly,     // boolean: repo invariant — agent may never merge (fails closed)
  *   isMerged,           // boolean: PR has been merged
  * }
  * ```
@@ -194,9 +195,18 @@ export function resolveLifecycleState(input = {}) {
     hasUnresolvedThreads = false,
     preApprovalGatePassed = false,
     mergeAuthorized = false,
+    humanMergeOnly = false,
     isMerged = false,
   } = input;
 
+  // Fail closed: when the repo enforces human-only merge, the agent is never
+  // cleared to advance to the merge action — the per-run mergeAuthorized signal
+  // is ignored. Also fail closed on a non-boolean `mergeAuthorized` (only an
+  // exact `true` clears merge), matching the authoritative
+  // `resolveEffectiveMergeAuthorized` gate. An already-merged PR (isMerged) is
+  // still terminal below.
+  const effectiveMergeAuthorized = humanMergeOnly !== true && mergeAuthorized === true;
+
   // 1. Explicit phase override — canonical or fail closed
   if (phase !== null && phase !== undefined) {
     const normalized = normalizeLifecycleState(phase);
@@ -212,7 +222,9 @@ export function resolveLifecycleState(input = {}) {
   }
 
   // 3. Merge authorized with pre-approval + linked PR → merge
-  if (mergeAuthorized && preApprovalGatePassed && hasLinkedPr) {
+  // (humanMergeOnly forces effectiveMergeAuthorized=false above, so the loop
+  // stays at the pre_approval_gate human-merge handoff instead.)
+  if (effectiveMergeAuthorized && preApprovalGatePassed && hasLinkedPr) {
     return buildResult(LIFECYCLE_STATE.MERGE);
   }
 

package/src/loop/queue-board-ordering.mjs

@@ -25,7 +25,11 @@ export async function resolveNextUpOrder(
   const listItems = dependencies.listQueueItems ?? listQueueItemsMain;
   try {
     const result = await listItems(
-      { repo, project: projectNumber, column: "Next Up" },
+      // list-queue-items validates `project` as a string ref (CLI contract);
+      // resolveProjectNumber yields a number, so stringify it. Passing the raw
+      // number trips parseProjectRef's `typeof raw !== "string"` guard, which
+      // surfaces as a misleading "--project is required" (#901).
+      { repo, project: String(projectNumber), column: "Next Up" },
       { env, runChild: dependencies.runChild },
     );
     const order = (result?.items ?? [])

package/src/loop/queue-driver.mjs

@@ -57,6 +57,28 @@ export async function runQueue(repoRoot, repo, options = {}) {
   const opts = { ...DEFAULT_QUEUE_DRIVER_OPTIONS, ...options };
   const queue = await readQueue(repoRoot);
 
+  // Data-integrity guard (#913): this driver is a deterministic ADAPTER over the
+  // board, not the orchestration harness. Completion (`done` / move to Done) may
+  // only ever REFLECT a real terminal signal supplied by an orchestrator via
+  // `runEntry` (e.g. a merged PR). With no `runEntry` wired in the current
+  // harness there is nothing that can produce a verifiable terminal state, so
+  // the run MUST be a no-op: leave every entry and board column untouched and
+  // report the reason. Previously the missing-orchestrator path fell back to a
+  // fabricated `{ ok: true, pr: null }` per entry, which silently marked an
+  // entire Next Up `done` and moved it to Done without any work happening.
+  if (typeof opts.runEntry !== "function") {
+    return {
+      ok: true,
+      noop: true,
+      reason: "no-orchestrator",
+      message:
+        "queue run is a deterministic adapter with no orchestrator wired (no runEntry); " +
+        "leaving board columns unchanged. Items move to Done only on a real terminal signal.",
+      results: [],
+      queue,
+    };
+  }
+
   // Config-driven loop-state → board-column mapping (#793, AC1/AC3). Loaded
   // once per run; resolves logical columns to configured display names, with
   // the AC1 defaults when no `queue.statusColumns`/`queue.stateColumnMap` is set.
@@ -135,9 +157,9 @@ export async function runQueue(repoRoot, repo, options = {}) {
     await syncColumn(entry.target, columnFor("implementation"));
 
     try {
-      const entryResult = opts.runEntry
-        ? await opts.runEntry(entry, repo, opts)
-        : { ok: true, pr: null };
+      // runEntry is guaranteed a function here (guarded at function entry):
+      // the adapter never fabricates a terminal result for an undispatched item.
+      const entryResult = await opts.runEntry(entry, repo, opts);
 
       if (entryResult.ok) {
         if (entryResult.pr) {

package/src/loop/run-context.mjs

@@ -1,15 +1,11 @@
 /**
  * Neutral run-id / async-context contract.
  *
- * The dev-loop async path historically keyed off Pi's `PI_SUBAGENT_RUN_ID` env var to
+ * The dev-loop async path keys off the harness-neutral `DEVLOOPS_RUN_ID` env var to
  * identify an inspectable per-subagent run (runner ownership, async-start enforcement,
- * human-comment gating). This module generalizes that into a harness-neutral
- * `DEVLOOPS_RUN_ID`, keeping `PI_SUBAGENT_RUN_ID` as a backward-compatible alias, and
- * provides a mint-and-propagate path for harnesses (e.g. Claude Code) that inject no
- * native per-subagent run id.
- *
- * Marker precedence is neutral-first: a present `DEVLOOPS_RUN_ID` wins; otherwise the Pi
- * alias is honored. Existing Pi runs that set only `PI_SUBAGENT_RUN_ID` behave identically.
+ * human-comment gating), and provides a mint-and-propagate path for harnesses (e.g. Claude
+ * Code) that inject no native per-subagent run id. The harness sets `DEVLOOPS_RUN_ID` when
+ * dispatching an async subagent.
  *
  * This module is pure except for the explicit file/IO helpers (writeRunContext/readRunContext),
  * which take an injectable `fs` and `root` for testability.
@@ -21,16 +17,13 @@ import path from "node:path";
 
 /**
  * Env var names that carry the async-context run id, in resolution precedence order.
- * Neutral `DEVLOOPS_RUN_ID` first; Pi `PI_SUBAGENT_RUN_ID` retained as a compatibility alias.
+ * The neutral `DEVLOOPS_RUN_ID` is the sole marker.
  */
-export const RUN_ID_MARKERS = Object.freeze(["DEVLOOPS_RUN_ID", "PI_SUBAGENT_RUN_ID"]);
+export const RUN_ID_MARKERS = Object.freeze(["DEVLOOPS_RUN_ID"]);
 
 /** Neutral env var name used when minting/propagating a run id. */
 export const NEUTRAL_RUN_ID_VAR = "DEVLOOPS_RUN_ID";
 
-/** Pi-compatibility alias env var name. */
-export const PI_RUN_ID_ALIAS_VAR = "PI_SUBAGENT_RUN_ID";
-
 /** State-file name (under `.pi/`, consistent with existing dev-loop checkpoint files). */
 export const RUN_CONTEXT_FILENAME = "dev-loop-run-context.json";
 
@@ -56,7 +49,7 @@ export function isClaudeHarness(env = process.env) {
 }
 
 /**
- * Resolve the active run id from the environment, neutral marker first.
+ * Resolve the active run id from the environment.
  *
  * @param {Record<string, string|undefined>} [env]
  * @returns {string|null} The trimmed run id, or null when none is set.
@@ -154,8 +147,8 @@ export function readRunContext({ root, fs = fsDefault }) {
  * Resolve the active run id, or mint one and persist a run-context state file.
  *
  * This is the "mint at startup and propagate" primitive a Claude dev-loop agent (or a
- * headless entry) calls before dispatching child work. When the env already carries a run
- * id (Pi alias or neutral), it is reused and no new id is minted.
+ * headless entry) calls before dispatching child work. When the env already carries a
+ * `DEVLOOPS_RUN_ID`, it is reused and no new id is minted.
  *
  * @param {object} [params]
  * @param {Record<string, string|undefined>} [params.env]

package/src/loop/worktree-guard.mjs

@@ -121,32 +121,22 @@ export function isListedWorktree(cwd, worktreePaths) {
  * Neutral environment variable name checked by `detectSubagentAvailability`.
  *
  * Set `DEVLOOPS_SUBAGENT_AVAILABLE=1` when the runtime supports subagent dispatch.
- * This is consistent with the `PI_WORKTREE_BYPASS` pattern and other repo-local
+ * This is consistent with the `DEVLOOPS_WORKTREE_BYPASS` pattern and other repo-local
  * runtime configuration gates already present in the repo.
  */
 export const DEVLOOPS_SUBAGENT_AVAILABLE_VAR = "DEVLOOPS_SUBAGENT_AVAILABLE";
 
-/**
- * Pi-compatibility alias for {@link DEVLOOPS_SUBAGENT_AVAILABLE_VAR}; honored when the
- * neutral var is unset so existing Pi runtimes keep working unchanged.
- */
-export const PI_SUBAGENT_AVAILABLE_VAR = "PI_SUBAGENT_AVAILABLE";
-
-/** Availability env var names, neutral-first. */
-export const SUBAGENT_AVAILABLE_VARS = Object.freeze([
-  DEVLOOPS_SUBAGENT_AVAILABLE_VAR,
-  PI_SUBAGENT_AVAILABLE_VAR,
-]);
+/** Availability env var names. */
+export const SUBAGENT_AVAILABLE_VARS = Object.freeze([DEVLOOPS_SUBAGENT_AVAILABLE_VAR]);
 
 /**
  * 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. Precedence is
- * neutral-first: the first var that is *set* (non-blank) is authoritative — so an explicit
- * `DEVLOOPS_SUBAGENT_AVAILABLE=0` is respected even when `PI_SUBAGENT_AVAILABLE=1`. The Pi
- * alias is only consulted when the neutral var is unset/blank.
+ * is advisory (fails-open) and never hard-blocks on subagent absence. The var that is
+ * *set* (non-blank) is authoritative — so an explicit `DEVLOOPS_SUBAGENT_AVAILABLE=0` is
+ * respected as a hard "not available".
  *
  * @param {{ env?: Record<string, string | undefined> }} [options]
  * @returns {boolean}