@dev-loops/core 0.1.3 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dev-loops/core",
-  "version": "0.1.3",
+  "version": "0.2.1",
   "type": "module",
   "description": "Shared deterministic support package for dev-loop skills, repo-local scripts, and GitHub automation.",
   "exports": {
@@ -9,6 +9,9 @@
     "./cli/primitives": "./src/cli/primitives.mjs",
     "./cli/retry-wrapper": "./src/cli/retry-wrapper.mjs",
     "./cli/subcommand-runner": "./src/cli/subcommand-runner.mjs",
+    "./claude/asset-generation": "./src/claude/asset-generation.mjs",
+    "./claude/headless-entry": "./src/claude/headless-entry.mjs",
+    "./claude/hook-decisions": "./src/claude/hook-decisions.mjs",
     "./config": "./src/config/config.mjs",
     "./debt/cluster": "./src/debt/cluster.mjs",
     "./debt/finding": "./src/debt/debt-finding.mjs",
@@ -21,6 +24,7 @@
     "./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/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",
     "./loop/copilot-loop-iterations": "./src/loop/copilot-loop-iterations.mjs",
@@ -36,6 +40,7 @@
     "./loop/queue-parallel": "./src/loop/queue-parallel.mjs",
     "./loop/queue-state": "./src/loop/queue-state.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/steering": "./src/loop/steering.mjs",
     "./loop/timeout-policy": "./src/loop/timeout-policy.mjs",

package/src/claude/asset-generation.mjs

@@ -0,0 +1,182 @@
+/**
+ * Generate Claude Code assets (.claude/agents/*.md, .claude/skills/<name>/SKILL.md) from the
+ * canonical Pi sources (agents/*.agent.md, skills/**\/SKILL.md), which remain the single
+ * source of truth. These are pure transforms (no file IO) so they are deterministic and
+ * unit-testable; the orchestration/IO lives in scripts/claude/generate-claude-assets.mjs.
+ *
+ * Pi→Claude tool-name mapping (confirmed against Claude Code docs):
+ *   read→Read, search→Grep+Glob, execute→Bash, bash→Bash, edit→Edit, write→Write,
+ *   agent→Agent, subagent→Agent, todo→TodoWrite, review_loop→Agent (the review subagent).
+ * Frontmatter *tool lists* are rewritten, and bodies are copied through `stripPiOnlyBlocks`
+ * (#817): `<!-- pi-only -->`…`<!-- /pi-only -->` sections are removed for the Claude output so
+ * Pi-runtime-specific prose (e.g. `tools: [subagent]`/`maxSubagentDepth` assertions, the
+ * `contact_supervisor`/`pi-intercom` bug guidance) doesn't contradict the Claude assets. The
+ * source stays Pi-complete; general `subagent` prose is preserved (Claude has subagents too).
+ *
+ * Frontmatter handling:
+ * - Agents keep name/description/tools (comma-separated, per Claude's agent format) and drop
+ *   Pi-only fields that have no faithful Claude agent equivalent: argument-hint,
+ *   systemPromptMode, inheritProjectContext, inheritSkills, maxSubagentDepth, user-invocable.
+ *   (Subagents are never user-invocable in Claude; maxSubagentDepth/inherit* are Pi
+ *   async-dispatch concerns. The user entrypoint under Claude is the dev-loop *skill*.)
+ * - Skills keep name/description/allowed-tools (space-separated) and preserve `user-invocable`
+ *   (Claude honors it 1:1 — `user-invocable: false` hides the skill from the `/` menu). The
+ *   Pi-specific `compatibility` text is dropped (no Claude field).
+ */
+
+import { parse as parseYaml } from "yaml";
+
+/** Pi→Claude tool-name map. A Pi name may expand to multiple Claude tools (search→Grep,Glob). */
+export const TOOL_NAME_MAP = Object.freeze({
+  read: ["Read"],
+  search: ["Grep", "Glob"],
+  execute: ["Bash"],
+  bash: ["Bash"],
+  edit: ["Edit"],
+  write: ["Write"],
+  agent: ["Agent"],
+  subagent: ["Agent"],
+  todo: ["TodoWrite"],
+  review_loop: ["Agent"],
+});
+
+const GENERATED_NOTE = (source) =>
+  `<!-- GENERATED from ${source} by scripts/claude/generate-claude-assets.mjs — do not edit; edit the source and regenerate. -->`;
+
+/**
+ * Strip Pi-runtime-only prose blocks from a body for the Claude output (#817).
+ *
+ * The canonical sources stay Pi-complete; sections that are Pi-runtime-specific and misleading
+ * under Claude (e.g. `tools: [subagent]`/`maxSubagentDepth` assertions that contradict the
+ * mapped Claude frontmatter, or the `contact_supervisor`/`pi-intercom` Pi-bug guidance) are
+ * wrapped in the source with `<!-- pi-only -->` … `<!-- /pi-only -->` and removed here. Resulting
+ * blank-line runs are collapsed so the stripped body stays clean. `subagent` prose in general is
+ * NOT stripped — Claude has subagents too.
+ *
+ * @param {string} body
+ * @returns {string}
+ */
+export function stripPiOnlyBlocks(body) {
+  const s = String(body);
+  // True no-op when there are no markers — must NOT touch blank-line runs in marker-free
+  // bodies (they may carry intentional spacing; collapsing them would drift the committed tree).
+  if (!s.includes("<!-- pi-only -->")) {
+    return s;
+  }
+  // Markers must not nest; pairs are matched non-greedily. After removing the block(s), collapse
+  // any run of 3+ newlines in this (marker-bearing) body to a single blank line — this tidies the
+  // gaps left by removal; marker-free bodies are returned untouched above, so their intentional
+  // blank runs are never affected.
+  return s
+    .replace(/[ \t]*<!-- pi-only -->[\s\S]*?<!-- \/pi-only -->[ \t]*\n?/g, "")
+    .replace(/\n{3,}/g, "\n\n");
+}
+
+/**
+ * Map a single Pi tool name to its Claude tool name(s).
+ * @param {string} name
+ * @returns {string[]} Claude tool names (empty if unknown).
+ */
+export function mapTool(name) {
+  return TOOL_NAME_MAP[String(name).trim()] ?? [];
+}
+
+/**
+ * Map a list of Pi tool names to deduped Claude tool names, preserving first-seen order.
+ * @param {string[]} tools
+ * @returns {string[]}
+ */
+export function mapTools(tools) {
+  const out = [];
+  for (const tool of tools ?? []) {
+    for (const mapped of mapTool(tool)) {
+      if (!out.includes(mapped)) {
+        out.push(mapped);
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * Split a source markdown file into its parsed frontmatter and verbatim body.
+ * @param {string} raw
+ * @returns {{ frontmatter: Record<string, unknown>, body: string }}
+ */
+export function splitFrontmatter(raw, source) {
+  const where = source ? ` (${source})` : "";
+  const match = String(raw).match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+  if (!match) {
+    throw new Error(`source file is missing a leading YAML frontmatter block${where}`);
+  }
+  let frontmatter;
+  try {
+    frontmatter = parseYaml(match[1]) ?? {};
+  } catch (error) {
+    throw new Error(`failed to parse YAML frontmatter${where}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  return { frontmatter, body: match[2] };
+}
+
+/** Normalize a Pi `tools` value (YAML list) into a string[] of names. */
+function normalizeToolList(value) {
+  if (Array.isArray(value)) {
+    return value.map((v) => String(v).trim()).filter(Boolean);
+  }
+  if (typeof value === "string") {
+    return value.split(/[\s,]+/).map((v) => v.trim()).filter(Boolean);
+  }
+  return [];
+}
+
+/**
+ * Transform a canonical `agents/*.agent.md` into a Claude `.claude/agents/*.md` document.
+ * @param {{ source: string, raw: string }} input
+ * @returns {string} Full generated file content.
+ */
+export function transformAgent({ source, raw }) {
+  const { frontmatter, body: rawBody } = splitFrontmatter(raw, source);
+  const body = stripPiOnlyBlocks(rawBody);
+  const tools = mapTools(normalizeToolList(frontmatter.tools));
+
+  const lines = ["---"];
+  lines.push(`name: ${JSON.stringify(String(frontmatter.name ?? ""))}`);
+  if (frontmatter.description != null) {
+    lines.push(`description: ${JSON.stringify(String(frontmatter.description))}`);
+  }
+  if (tools.length > 0) {
+    lines.push(`tools: ${tools.join(", ")}`);
+  }
+  lines.push("---");
+  lines.push(GENERATED_NOTE(source));
+  lines.push("");
+  return `${lines.join("\n")}\n${body}`;
+}
+
+/**
+ * Transform a canonical `skills/<name>/SKILL.md` into a Claude `.claude/skills/<name>/SKILL.md`.
+ * @param {{ source: string, raw: string }} input
+ * @returns {string} Full generated file content.
+ */
+export function transformSkill({ source, raw }) {
+  const { frontmatter, body: rawBody } = splitFrontmatter(raw, source);
+  const body = stripPiOnlyBlocks(rawBody);
+  const tools = mapTools(normalizeToolList(frontmatter["allowed-tools"]));
+
+  const lines = ["---"];
+  lines.push(`name: ${JSON.stringify(String(frontmatter.name ?? ""))}`);
+  if (frontmatter.description != null) {
+    lines.push(`description: ${JSON.stringify(String(frontmatter.description))}`);
+  }
+  if (tools.length > 0) {
+    lines.push(`allowed-tools: ${tools.join(" ")}`);
+  }
+  // user-invocable maps 1:1 — Claude honors `user-invocable: false` (hides from the / menu).
+  if (typeof frontmatter["user-invocable"] === "boolean") {
+    lines.push(`user-invocable: ${frontmatter["user-invocable"]}`);
+  }
+  lines.push("---");
+  lines.push(GENERATED_NOTE(source));
+  lines.push("");
+  return `${lines.join("\n")}\n${body}`;
+}

package/src/claude/headless-entry.mjs

@@ -0,0 +1,69 @@
+/**
+ * Headless dev-loop entry helpers for Claude Code (#775).
+ *
+ * Builds a non-interactive `claude -p` invocation that runs the dev-loop, with the CA2 run id
+ * propagated into the spawned process's environment via `runContextEnv`. That propagation is
+ * what lets the #773 PreToolUse write-guard recognize the headless session as the dev-loop
+ * subagent context (completing the CA2→CA4 wiring for the headless path). The repo's
+ * `.claude/settings.json` hooks apply automatically to the spawned session.
+ *
+ * Pure: builds the command/args/env; the actual spawn lives in the entry script
+ * (scripts/claude/headless-dev-loop.mjs), which is the only part that needs `claude` on PATH.
+ */
+
+import { runContextEnv } from "../loop/run-context.mjs";
+
+/** Default Claude CLI binary name. */
+export const DEFAULT_CLAUDE_BIN = "claude";
+
+/**
+ * Build the headless dev-loop prompt for a target.
+ *
+ * @param {Object} [params]
+ * @param {number|string} [params.issue]
+ * @param {number|string} [params.pr]
+ * @returns {string}
+ */
+export function buildDevLoopPrompt({ issue, pr } = {}) {
+  if (issue != null && `${issue}`.trim() && pr != null && `${pr}`.trim()) {
+    throw new TypeError("buildDevLoopPrompt: provide at most one target (issue or pr), not both");
+  }
+  if (issue != null && `${issue}`.trim()) {
+    return `Run the dev-loop for issue #${issue}. Use the /dev-loop skill; routing resolves the rest.`;
+  }
+  if (pr != null && `${pr}`.trim()) {
+    return `Run the dev-loop for PR #${pr}. Use the /dev-loop skill; routing resolves the rest.`;
+  }
+  return "Run the dev-loop. Use the /dev-loop skill; routing resolves the current state.";
+}
+
+/**
+ * Build a non-interactive `claude -p` invocation for the dev-loop.
+ *
+ * @param {Object} params
+ * @param {string} params.prompt - The headless prompt (see buildDevLoopPrompt).
+ * @param {string} params.runId - The dev-loop run id to propagate (see ensureRunId).
+ * @param {string} [params.claudeBin] - Claude CLI binary (default "claude").
+ * @param {string[]} [params.extraArgs] - Extra args appended after `-p <prompt>`.
+ * @param {Record<string,string|undefined>} [params.baseEnv] - Base env (default process.env).
+ * @returns {{ command: string, args: string[], env: Record<string,string|undefined> }}
+ */
+export function buildHeadlessClaudeInvocation({ prompt, runId, claudeBin = DEFAULT_CLAUDE_BIN, extraArgs = [], baseEnv = process.env }) {
+  if (typeof prompt !== "string" || prompt.trim().length === 0) {
+    throw new TypeError("buildHeadlessClaudeInvocation: prompt must be a non-empty string");
+  }
+  if (typeof runId !== "string" || runId.trim().length === 0) {
+    throw new TypeError("buildHeadlessClaudeInvocation: runId must be a non-empty string");
+  }
+  if (typeof claudeBin !== "string" || claudeBin.trim().length === 0) {
+    throw new TypeError("buildHeadlessClaudeInvocation: claudeBin must be a non-empty string");
+  }
+  if (!Array.isArray(extraArgs)) {
+    throw new TypeError("buildHeadlessClaudeInvocation: extraArgs must be an array");
+  }
+  return {
+    command: claudeBin,
+    args: ["-p", prompt, ...extraArgs],
+    env: { ...baseEnv, ...runContextEnv(runId) },
+  };
+}

package/src/claude/hook-decisions.mjs

@@ -0,0 +1,129 @@
+/**
+ * Pure decision logic for the Claude Code dev-loop hooks (#773).
+ *
+ * The hook *scripts* are thin: they read the PreToolUse/PostToolUse stdin payload, gather facts
+ * (git tracked/ignored status, gate-evidence result), and call these pure deciders. Keeping the
+ * decisions here makes the deny/allow boundary fully unit-testable without spawning hooks, and
+ * keeps the Claude-specific stdin/stdout IO at the edge.
+ *
+ * Pure and side-effect free.
+ */
+
+import { resolveRunId } from "../loop/run-context.mjs";
+import {
+  isGhPrReadyCommand,
+  extractPrNumberFromGhPrReady,
+  extractRepoFlagFromGhPrReady,
+  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).
+ */
+
+const ALLOW = Object.freeze({ decision: "allow" });
+
+/**
+ * The agent type (Claude `agent_type` / the canonical agent name) that owns repo mutations.
+ * Only this subagent — not arbitrary subagents (Explore, Plan, generic Task agents) — may
+ * bypass the main-agent read-only boundary.
+ */
+export const DEV_LOOP_AGENT_TYPE = "dev-loop";
+
+/**
+ * Decide whether a PreToolUse Bash command must be blocked by the draft-gate boundary.
+ *
+ * Mirrors the Pi extension's `onUserBash`: the only blocked case is `gh pr ready` for the
+ * target repo without clean draft_gate evidence. Everything else (including merges, which
+ * trigger the post-merge step, not a block) is allowed through.
+ *
+ * @param {Object} params
+ * @param {string} params.command - The Bash command string.
+ * @param {string|null} [params.repoSlug] - Resolved owner/name of the cwd repo (null if unknown).
+ * @param {boolean} [params.gatePassed] - Whether `pre-pr-ready-gate` evidence exists for the PR.
+ * @param {string|null} [params.gateError] - Error detail when the gate guard could not run.
+ * @returns {HookDecision}
+ */
+export function decideBashGate({ command, repoSlug = null, gatePassed = false, gateError = null }) {
+  if (typeof command !== "string" || !isGhPrReadyCommand(command)) {
+    return ALLOW;
+  }
+
+  // An explicit `--repo other/repo` that is not the target → not our concern, pass through.
+  const explicitRepo = extractRepoFlagFromGhPrReady(command);
+  if (explicitRepo && explicitRepo.toLowerCase() !== TARGET_REPO_SLUG.toLowerCase()) {
+    return ALLOW;
+  }
+  // Only gate within the target repo (case-insensitive — callers may pass an un-lowercased slug).
+  if ((repoSlug ?? "").toLowerCase() !== TARGET_REPO_SLUG.toLowerCase()) {
+    return ALLOW;
+  }
+
+  const prNumber = extractPrNumberFromGhPrReady(command);
+  if (prNumber === null) {
+    return {
+      decision: "deny",
+      reason:
+        "gh pr ready blocked: could not determine the PR number from the command. Include the PR number explicitly.",
+    };
+  }
+
+  if (gateError) {
+    return {
+      decision: "deny",
+      reason: `gh pr ready blocked: draft-gate evidence check failed (${gateError}).`,
+    };
+  }
+
+  if (!gatePassed) {
+    return {
+      decision: "deny",
+      reason: `gh pr ready blocked: no visible clean draft_gate checkpoint verdict comment found for PR #${prNumber}.`,
+    };
+  }
+
+  return ALLOW;
+}
+
+/**
+ * Decide whether a PreToolUse Write/Edit must be blocked by the main-agent read-only boundary.
+ *
+ * Denies a mutation whose target is inside the repo working tree AND not gitignored, when the
+ * call originates from the MAIN agent. Allows it only inside the *dev-loop* subagent context:
+ * the CA2 run id (`DEVLOOPS_RUN_ID`) is present, or the Claude `agent_type` is the dev-loop
+ * agent. A generic subagent (Explore, Plan, an arbitrary Task agent) is NOT authorized — the
+ * contract requires mutations to flow through the dev-loop subagent specifically. Non-repo /
+ * gitignored paths are always allowed. Strict enforcement is opt-in via `enforce` (the hook
+ * derives it from `DEVLOOPS_MAIN_AGENT_READONLY=1`) so adopting the harness does not
+ * retroactively break a repo's own interactive dev; default is fail-open.
+ *
+ * @param {Object} params
+ * @param {string} params.filePath - Target file path.
+ * @param {boolean} params.isRepoMutation - True if inside the repo working tree AND not gitignored.
+ * @param {boolean} [params.enforce] - Strict mode (DEVLOOPS_MAIN_AGENT_READONLY=1).
+ * @param {Record<string,string|undefined>} [params.env] - Environment (for the CA2 run id).
+ * @param {string|null} [params.agentType] - Claude `agent_type` from the hook payload, if any.
+ * @returns {HookDecision}
+ */
+export function decideWriteGuard({ filePath, isRepoMutation, enforce = false, env = {}, agentType = null }) {
+  if (!enforce) {
+    return ALLOW; // strict enforcement not enabled — fail open
+  }
+  if (!isRepoMutation) {
+    return ALLOW; // non-repo or gitignored path (e.g. /tmp, tmp/) — allowed by the contract
+  }
+  // Authorized only inside the dev-loop subagent context: CA2 run id, or the dev-loop agent
+  // type. Any other subagent type is treated like the main agent and denied.
+  if (resolveRunId(env) || agentType === DEV_LOOP_AGENT_TYPE) {
+    return ALLOW;
+  }
+  return {
+    decision: "deny",
+    reason:
+      `Main-agent read-only boundary: refusing to mutate repository path "${filePath}". ` +
+      "All repository mutations must flow through the dev-loop subagent. " +
+      "See skills/docs/main-agent-contract.md.",
+  };
+}

package/src/harness/claude-extension-adapter.mjs

@@ -0,0 +1,102 @@
+import { execFile } from "node:child_process";
+
+import { createExtensionHarnessAdapter } from "./extension-adapter.mjs";
+
+/**
+ * Create the Claude Code extension-surface adapter.
+ *
+ * Implements the same `ExtensionHarnessAdapter` interface as the Pi adapter so
+ * `executeDevLoopsCommand` and the extension wiring run unchanged under Claude.
+ *
+ * - `exec` shells out via `bash -lc` (Claude has no native exec API in core).
+ * - lifecycle `on(...)` registrations are stored in `listeners` for hook-driven
+ *   dispatch (wired in CA4 / #773); they are not auto-fired here.
+ * - `registerCommand(...)` registrations are stored in `commands`.
+ * - Claude core has no interactive widget/status surface, so the default
+ *   `HarnessContext` reports `hasUI: false` and routes `ui` calls to a sink.
+ *
+ * @param {Object} [options]
+ * @param {string} [options.cwd] - Default cwd for exec and contexts (default: process.cwd()).
+ * @param {NodeJS.ProcessEnv} [options.env] - Env for exec (default: process.env).
+ * @param {(message: string, level: string) => void} [options.onNotify] - Optional sink for
+ *   `ui.notify` (e.g. console). Defaults to a no-op.
+ * @returns {import("./extension-adapter.mjs").ExtensionHarnessAdapter & {
+ *   listeners: Map<string, Function>,
+ *   commands: Map<string, import("./extension-adapter.mjs").HarnessCommandConfig>,
+ *   makeContext: (overrides?: {cwd?: string}) => import("./extension-adapter.mjs").HarnessContext,
+ * }}
+ */
+export function createClaudeExtensionAdapter({
+  cwd = process.cwd(),
+  env = process.env,
+  onNotify = () => {},
+} = {}) {
+  const listeners = new Map();
+  const commands = new Map();
+
+  function exec(command, options = {}) {
+    return new Promise((resolve) => {
+      execFile(
+        "bash",
+        ["-lc", command],
+        {
+          cwd: options.cwd ?? cwd,
+          env,
+          timeout: options.timeout ?? 0,
+          encoding: "utf8",
+          maxBuffer: 64 * 1024 * 1024,
+        },
+        (error, stdout, stderr) => {
+          if (error) {
+            // Match the documented HarnessExecResult contract: `code` is undefined when
+            // the process was killed (e.g. timeout). Consumers branch on `killed` first.
+            const killed = Boolean(error.killed);
+            resolve({
+              code: killed ? undefined : (typeof error.code === "number" ? error.code : 1),
+              stdout: stdout ?? "",
+              stderr: stderr ?? "",
+              killed,
+            });
+            return;
+          }
+          resolve({ code: 0, stdout: stdout ?? "", stderr: stderr ?? "", killed: false });
+        },
+      );
+    });
+  }
+
+  function makeContext({ cwd: ctxCwd } = {}) {
+    return {
+      cwd: ctxCwd ?? cwd,
+      hasUI: false,
+      ui: {
+        notify(message, level = "info") {
+          onNotify(message, level);
+        },
+        setWidget() {},
+        setStatus() {},
+      },
+    };
+  }
+
+  const adapter = createExtensionHarnessAdapter({
+    exec,
+    on(event, handler) {
+      listeners.set(event, handler);
+    },
+    registerCommand(name, config) {
+      commands.set(name, config);
+    },
+  });
+
+  // Freeze the composite so the validated interface guarantee from the factory carries
+  // through to the returned object (which also exposes the #773 dispatch registries).
+  return Object.freeze({
+    exec: adapter.exec,
+    on: adapter.on,
+    registerCommand: adapter.registerCommand,
+    listeners,
+    commands,
+    makeContext,
+  });
+}

package/src/harness/extension-adapter.mjs

@@ -0,0 +1,70 @@
+/**
+ * Extension-surface harness adapter interface.
+ *
+ * Abstracts the *extension surface* that the dev-loops runtime uses today — process
+ * execution, session lifecycle events, slash-command registration, and a UI surface —
+ * so the extension is no longer bound directly to Pi's `ExtensionAPI`/`ExtensionContext`.
+ *
+ * This is distinct from the context seam in `./adapter.mjs` (cwd/env/repo-root): that one
+ * answers "where/how am I running"; this one answers "how do I talk to the harness".
+ *
+ * Concrete adapters (Pi, Claude, test) implement this so call sites stay harness-agnostic.
+ * Keep it minimal — add a method only when a real call site needs it.
+ *
+ * @typedef {Object} HarnessExecResult
+ * @property {number} [code] - Process exit code (undefined when killed).
+ * @property {string} [stdout]
+ * @property {string} [stderr]
+ * @property {boolean} [killed] - Whether the process was killed (e.g. timeout).
+ *
+ * @typedef {Object} HarnessExecOptions
+ * @property {string} [cwd]
+ * @property {number} [timeout] - Timeout in milliseconds.
+ *
+ * @typedef {Object} HarnessUi
+ * @property {(message: string, level?: 'info'|'warning'|'error') => void} notify
+ * @property {(key: string, lines: string[]|undefined, options?: object) => void} setWidget
+ * @property {(key: string, text: string|undefined) => void} setStatus
+ *
+ * @typedef {Object} HarnessContext
+ * @property {string} cwd - Working directory for the current invocation.
+ * @property {boolean} hasUI - Whether an interactive UI surface is attached.
+ * @property {HarnessUi} ui - UI operations for this invocation.
+ *
+ * @typedef {'session_start'|'tool_result'|'user_bash'|'agent_end'} HarnessLifecycleEvent
+ *
+ * @typedef {Object} HarnessCommandConfig
+ * @property {string} description
+ * @property {(args: string|string[], ctx: HarnessContext) => unknown} handler
+ *
+ * @typedef {Object} ExtensionHarnessAdapter
+ * @property {(command: string, options?: HarnessExecOptions) => Promise<HarnessExecResult>} exec
+ * @property {(event: HarnessLifecycleEvent, handler: (event: unknown, ctx: HarnessContext) => unknown) => void} on
+ * @property {(name: string, config: HarnessCommandConfig) => void} registerCommand
+ */
+
+const REQUIRED_METHODS = ["exec", "on", "registerCommand"];
+
+/**
+ * Validate and freeze an extension-surface harness-adapter implementation.
+ *
+ * @param {Partial<ExtensionHarnessAdapter>} impl
+ * @returns {ExtensionHarnessAdapter}
+ */
+export function createExtensionHarnessAdapter(impl) {
+  if (!impl || typeof impl !== "object") {
+    throw new TypeError("createExtensionHarnessAdapter: impl must be an object");
+  }
+
+  for (const method of REQUIRED_METHODS) {
+    if (typeof impl[method] !== "function") {
+      throw new TypeError(`createExtensionHarnessAdapter: missing required method "${method}"`);
+    }
+  }
+
+  return Object.freeze({
+    exec: impl.exec,
+    on: impl.on,
+    registerCommand: impl.registerCommand,
+  });
+}

package/src/harness/index.mjs

@@ -1,3 +1,5 @@
 export { createHarnessAdapter, isHarnessAdapter } from "./adapter.mjs";
 export { createPiAdapter } from "./pi-adapter.mjs";
 export { createNoopAdapter } from "./noop-adapter.mjs";
+export { createExtensionHarnessAdapter } from "./extension-adapter.mjs";
+export { createClaudeExtensionAdapter } from "./claude-extension-adapter.mjs";

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

@@ -2,17 +2,18 @@
  * Async-start contract enforcement for the dev-loop startup path.
  *
  * This module enforces the requirement that dev-loop execution scripts
- * (outer-loop, watch-cycle, etc.) must run within a visible Pi-managed async
+ * (outer-loop, watch-cycle, etc.) must run within a visible harness-managed async
  * context rather than as detached local processes (nohup, disowned shell jobs,
  * tmux/screen sessions, ad hoc while/sleep loops, etc.).
  *
- * The enforcement seam is a startup check that verifies the presence of a
- * Pi async context marker. When the marker is absent, the check fails closed
+ * The enforcement seam is a startup check that verifies the presence of an
+ * async context marker. When the marker is absent, the check fails closed
  * and returns a machine-readable rejection rather than silently proceeding.
  *
- * Pi-managed async context markers (required when workflow.asyncStartMode is
- * `required`):
- * - PI_SUBAGENT_RUN_ID env var (set by Pi subagent framework for inspectable async runs)
+ * Async context markers (required when workflow.asyncStartMode is `required`),
+ * neutral-first — 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
@@ -22,14 +23,18 @@
  * This module is intentionally pure and side-effect free.
  */
 
+import { RUN_ID_MARKERS } from "./run-context.mjs";
+
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
 
-/** Environment variable names that indicate a Pi-managed async context. */
-export const PI_ASYNC_CONTEXT_MARKERS = Object.freeze([
-  "PI_SUBAGENT_RUN_ID",
-]);
+/**
+ * Environment variable names that indicate an async context, neutral-first.
+ * 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;
 
 /** Supported workflow async-start modes. */
 export const ASYNC_START_MODE = Object.freeze({
@@ -39,13 +44,13 @@ export const ASYNC_START_MODE = Object.freeze({
 
 /** Async-start validation result status values. */
 export const ASYNC_START_STATUS = Object.freeze({
-  /** A valid Pi-managed async context was detected. */
+  /** A valid harness-managed async context was detected. */
   VALID: "valid",
   /** The workflow explicitly allows non-async startup for this context. */
   ALLOWED: "allowed",
   /** The check was skipped because the caller is in snapshot/test mode. */
   SNAPSHOT_MODE: "snapshot_mode",
-  /** No Pi-managed async context was detected; fail closed. */
+  /** No harness-managed async context was detected; fail closed. */
   REJECTED: "rejected",
 });
 
@@ -54,7 +59,7 @@ export const ASYNC_START_STATUS = Object.freeze({
 // ---------------------------------------------------------------------------
 
 /**
- * Validate that the current execution context is a visible Pi-managed async run.
+ * Validate that the current execution context is a visible harness-managed async run.
  *
  * Returns a result object describing whether the check passed, was allowed by
  * config, or was rejected. Callers should treat `rejected` as a hard stop.
@@ -92,13 +97,13 @@ export function validateAsyncStartContext({
     };
   }
 
-  // Check for any Pi-managed async context marker
+  // Check for any async context marker (neutral DEVLOOPS_RUN_ID or the Pi alias)
   for (const marker of PI_ASYNC_CONTEXT_MARKERS) {
     const value = env[marker];
     if (typeof value === "string" && value.trim().length > 0) {
       return {
         status: ASYNC_START_STATUS.VALID,
-        reason: `Pi-managed async context detected via ${marker}.`,
+        reason: `Async context detected via ${marker}.`,
         detectedMarker: marker,
       };
     }
@@ -123,8 +128,8 @@ export function validateAsyncStartContext({
       status: ASYNC_START_STATUS.REJECTED,
       reason:
         `Detected ${sessionOnlyMarker}, but GitHub-first async-start requires a visible ` +
-        "Pi-managed subagent run id for inspectable startup/resume evidence. " +
-        "Set PI_SUBAGENT_RUN_ID to proceed. Any exception must come from repository-maintained workflow policy.",
+        "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,
     };
   }
@@ -134,7 +139,7 @@ export function validateAsyncStartContext({
       status: ASYNC_START_STATUS.REJECTED,
       reason:
         "Detected detached local background execution; detached/local fallback is diagnostic-only " +
-        "and does not satisfy the async-start contract. Restart via Pi-managed async mode. " +
+        "and does not satisfy the async-start contract. Restart via harness-managed async mode. " +
         "Any relaxed posture must come from repository-maintained workflow policy.",
       detectedMarker: null,
     };
@@ -144,10 +149,11 @@ export function validateAsyncStartContext({
   return {
     status: ASYNC_START_STATUS.REJECTED,
     reason:
-      "No Pi-managed async context detected. " +
-      "The dev-loop must run within a visible Pi async subagent session, " +
+      "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]} to proceed. Repository-maintained workflow policy controls any exceptions.`,
+      `Set ${PI_ASYNC_CONTEXT_MARKERS[0]} (or the PI_SUBAGENT_RUN_ID alias) to proceed. ` +
+      "Repository-maintained workflow policy controls any exceptions.",
     detectedMarker: null,
   };
 }

package/src/loop/bash-command-classify.mjs

@@ -0,0 +1,163 @@
+/**
+ * Pure classification of shell command strings for the dev-loop gate boundary.
+ *
+ * Shared by the Pi extension (`extension/post-merge-update.ts`, which re-exports these so its
+ * behavior is unchanged) and the Claude Code PreToolUse Bash hook. Keeping one source of truth
+ * means the `gh pr ready` / merge detection is identical across harnesses.
+ *
+ * Pure and side-effect free.
+ */
+
+/** The repository these gate guards apply to. */
+export const TARGET_REPO_SLUG = "mfittko/dev-loops";
+
+/** Flags known to take a value argument for `gh pr ready` (not boolean flags). */
+export const FLAGS_THAT_TAKE_VALUE = new Set(["-r", "--repo"]);
+
+/** @param {string|null|undefined} value @returns {string|null} */
+export function trimToNull(value) {
+  const trimmed = `${value ?? ""}`.trim();
+  return trimmed ? trimmed : null;
+}
+
+/**
+ * Normalize a git remote URL into an `owner/name` slug (lowercased), or null.
+ * @param {string} remoteUrl
+ * @returns {string|null}
+ */
+export function normalizeGitHubRepoSlug(remoteUrl) {
+  const normalized = trimToNull(remoteUrl);
+  if (!normalized) {
+    return null;
+  }
+
+  const patterns = [
+    /^git@github\.com:([^\s]+?)(?:\.git)?$/i,
+    /^https?:\/\/github\.com\/([^\s]+?)(?:\.git)?$/i,
+    /^ssh:\/\/git@github\.com\/([^\s]+?)(?:\.git)?$/i,
+    /^git:\/\/github\.com\/([^\s]+?)(?:\.git)?$/i,
+    /^git:github\.com\/([^\s]+?)(?:\.git)?$/i,
+  ];
+
+  for (const pattern of patterns) {
+    const match = normalized.match(pattern);
+    if (!match) {
+      continue;
+    }
+    return trimToNull(match[1])?.toLowerCase() ?? null;
+  }
+
+  return null;
+}
+
+function isGhPrMergeCommand(segment) {
+  if (!/^gh\s+pr\s+merge(?:\s|$)/i.test(segment)) {
+    return false;
+  }
+  const remainder = segment.replace(/^gh\s+pr\s+merge(?:\s|$)/i, "").trim();
+  if (!remainder) {
+    return true;
+  }
+  const firstArg = remainder.match(/^(\S+)/)?.[1]?.toLowerCase() ?? "";
+  return !["--help", "-h"].includes(firstArg);
+}
+
+function isGitMergeCompletionCommand(segment) {
+  if (!/^git\s+merge(?:\s|$)/i.test(segment)) {
+    return false;
+  }
+  const remainder = segment.replace(/^git\s+merge(?:\s|$)/i, "").trim();
+  if (!remainder) {
+    return true;
+  }
+  const firstArg = remainder.match(/^(\S+)/)?.[1]?.toLowerCase() ?? "";
+  return !["--abort", "--continue", "--quit", "--help", "-h"].includes(firstArg);
+}
+
+/** @param {string} command @returns {boolean} */
+export function isMergeCapableCommand(command) {
+  const normalized = command.trim();
+  if (!normalized) {
+    return false;
+  }
+  return normalized
+    .split(/\s*(?:&&|\|\||;|\|)\s*/)
+    .some((segment) => isGhPrMergeCommand(segment) || isGitMergeCompletionCommand(segment));
+}
+
+/** @param {string} command @returns {string} */
+export function firstShellSegment(command) {
+  return command.trim().split(/\s*(?:&&|\|\||;|\|)\s*/)[0]?.trim() ?? "";
+}
+
+/** @param {string} command @returns {boolean} */
+export function isGhPrReadyCommand(command) {
+  const segment = firstShellSegment(command);
+  if (!segment || !/^gh\s+pr\s+ready(?:\s|$)/i.test(segment)) {
+    return false;
+  }
+  const remainder = segment.replace(/^gh\s+pr\s+ready(?:\s|$)/i, "").trim();
+  if (!remainder) {
+    return true;
+  }
+  const args = remainder.split(/\s+/).map((a) => a.toLowerCase());
+  return !args.includes("--help") && !args.includes("-h");
+}
+
+/** @param {string} command @returns {number|null} */
+export function extractPrNumberFromGhPrReady(command) {
+  const segment = firstShellSegment(command);
+  if (!/^gh\s+pr\s+ready(?:\s|$)/i.test(segment)) {
+    return null;
+  }
+  const remainder = segment.replace(/^gh\s+pr\s+ready(?:\s|$)/i, "").trim();
+  if (!remainder) {
+    return null;
+  }
+  const tokens = remainder.split(/\s+/);
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i];
+    if (token.startsWith("-")) {
+      const flagName = token.replace(/=.*$/, "").toLowerCase();
+      if (!token.includes("=") && FLAGS_THAT_TAKE_VALUE.has(flagName)) {
+        i++;
+      }
+      continue;
+    }
+    if (/^\d+$/.test(token)) {
+      const num = Number(token);
+      if (num > 0) {
+        return num;
+      }
+    }
+    return null;
+  }
+  return null;
+}
+
+/** @param {string} command @returns {string|null} */
+export function extractRepoFlagFromGhPrReady(command) {
+  const segment = firstShellSegment(command);
+  if (!/^gh\s+pr\s+ready(?:\s|$)/i.test(segment)) {
+    return null;
+  }
+  const remainder = segment.replace(/^gh\s+pr\s+ready(?:\s|$)/i, "").trim();
+  if (!remainder) {
+    return null;
+  }
+  const tokens = remainder.split(/\s+/);
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i];
+    const lower = token.toLowerCase();
+    if (lower === "-r" || lower === "--repo") {
+      if (i + 1 < tokens.length && !tokens[i + 1].startsWith("-")) {
+        return tokens[i + 1];
+      }
+    }
+    const repoEqMatch = token.match(/^(?:--repo|-R)=(.+)$/i);
+    if (repoEqMatch) {
+      return repoEqMatch[1];
+    }
+  }
+  return null;
+}

package/src/loop/run-context.mjs

@@ -0,0 +1,157 @@
+/**
+ * Neutral run-id / async-context contract.
+ *
+ * The dev-loop async path historically keyed off Pi's `PI_SUBAGENT_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.
+ *
+ * This module is pure except for the explicit file/IO helpers (writeRunContext/readRunContext),
+ * which take an injectable `fs` and `root` for testability.
+ */
+
+import crypto from "node:crypto";
+import fsDefault from "node:fs";
+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.
+ */
+export const RUN_ID_MARKERS = Object.freeze(["DEVLOOPS_RUN_ID", "PI_SUBAGENT_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";
+
+/**
+ * Resolve the active run id from the environment, neutral marker first.
+ *
+ * @param {Record<string, string|undefined>} [env]
+ * @returns {string|null} The trimmed run id, or null when none is set.
+ */
+export function resolveRunId(env = process.env) {
+  for (const marker of RUN_ID_MARKERS) {
+    const value = env?.[marker];
+    if (typeof value === "string" && value.trim().length > 0) {
+      return value.trim();
+    }
+  }
+  return null;
+}
+
+/**
+ * Mint a fresh neutral run id.
+ *
+ * @returns {string} `devloops-<uuid>` (e.g. "devloops-3f2c1e84-...-9a0b")
+ */
+export function mintRunId() {
+  return `devloops-${crypto.randomUUID()}`;
+}
+
+/**
+ * Build the env fragment that propagates a run id to child processes.
+ *
+ * Sets the neutral var; child Bash scripts observe it via `resolveRunId`. Callers merge
+ * this into the child env (e.g. `{ ...process.env, ...runContextEnv(runId) }`).
+ *
+ * @param {string} runId
+ * @returns {{ DEVLOOPS_RUN_ID: string }}
+ */
+export function runContextEnv(runId) {
+  return { [NEUTRAL_RUN_ID_VAR]: runId };
+}
+
+/**
+ * Absolute path to the run-context state file for a repo root.
+ *
+ * @param {string} root - Repository root (or any base dir).
+ * @returns {string}
+ */
+export function runContextPath(root) {
+  return path.join(root, ".pi", RUN_CONTEXT_FILENAME);
+}
+
+/**
+ * Persist the run-context state file (for inspection/recovery).
+ *
+ * @param {object} params
+ * @param {string} params.runId
+ * @param {string} params.root
+ * @param {string} [params.mintedAt] - ISO timestamp; defaults to now. Tests pass a fixed
+ *   value for determinism; real runs get a useful inspection/recovery timestamp.
+ * @param {typeof import("node:fs")} [params.fs]
+ * @returns {string} The path written.
+ */
+export function writeRunContext({ runId, root, mintedAt, fs = fsDefault }) {
+  if (typeof runId !== "string" || runId.trim().length === 0) {
+    throw new TypeError("writeRunContext: runId must be a non-empty string");
+  }
+  const file = runContextPath(root);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const payload = {
+    runId: runId.trim(),
+    mintedAt: mintedAt ?? new Date().toISOString(),
+  };
+  fs.writeFileSync(file, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+  return file;
+}
+
+/**
+ * Read the run-context state file, or null when absent/unparseable.
+ *
+ * @param {object} params
+ * @param {string} params.root
+ * @param {typeof import("node:fs")} [params.fs]
+ * @returns {{ runId: string, mintedAt: string|null }|null}
+ */
+export function readRunContext({ root, fs = fsDefault }) {
+  const file = runContextPath(root);
+  try {
+    const raw = fs.readFileSync(file, "utf8");
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed.runId === "string" && parsed.runId.trim().length > 0) {
+      return { runId: parsed.runId.trim(), mintedAt: parsed.mintedAt ?? null };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 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.
+ *
+ * @param {object} [params]
+ * @param {Record<string, string|undefined>} [params.env]
+ * @param {string} [params.root]
+ * @param {string} [params.mintedAt] - ISO timestamp for the state file (determinism).
+ * @param {typeof import("node:fs")} [params.fs]
+ * @returns {{ runId: string, minted: boolean, statePath: string|null }}
+ */
+export function ensureRunId({ env = process.env, root, mintedAt, fs = fsDefault } = {}) {
+  const existing = resolveRunId(env);
+  if (existing) {
+    return { runId: existing, minted: false, statePath: null };
+  }
+  const runId = mintRunId();
+  let statePath = null;
+  if (typeof root === "string" && root.length > 0) {
+    statePath = writeRunContext({ runId, root, mintedAt, fs });
+  }
+  return { runId, minted: true, statePath };
+}

package/src/loop/worktree-guard.mjs

@@ -118,24 +118,45 @@ export function isListedWorktree(cwd, worktreePaths) {
 // ---------------------------------------------------------------------------
 
 /**
- * Environment variable name checked by `detectSubagentAvailability`.
+ * Neutral environment variable name checked by `detectSubagentAvailability`.
  *
- * Set `PI_SUBAGENT_AVAILABLE=1` when the runtime supports subagent dispatch.
+ * Set `DEVLOOPS_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 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,
+]);
+
 /**
  * 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.
+ * 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.
  *
  * @param {{ env?: Record<string, string | undefined> }} [options]
  * @returns {boolean}
  */
 export function detectSubagentAvailability({ env = process.env } = {}) {
-  return (env[PI_SUBAGENT_AVAILABLE_VAR] ?? "").trim() === "1";
+  for (const name of SUBAGENT_AVAILABLE_VARS) {
+    const raw = (env[name] ?? "").trim();
+    if (raw.length > 0) {
+      return raw === "1";
+    }
+  }
+  return false;
 }