dev-loops 0.1.3 → 0.2.0

package/scripts/claude/headless-dev-loop.mjs

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+/**
+ * Headless dev-loop entry for Claude Code (#775).
+ *
+ * Runs the dev-loop non-interactively via `claude -p` (the Claude Agent SDK headless path),
+ * with the repo's `.claude/settings.json` hooks (gate + read-only guard, #773) active. It mints
+ * a neutral DEVLOOPS_RUN_ID (CA2) and propagates it into the spawned `claude` env so the headless
+ * session is recognized as the dev-loop subagent context by the write-guard.
+ *
+ * Usage:
+ *   node scripts/claude/headless-dev-loop.mjs [--issue <n> | --pr <n>] [--prompt <text>]
+ *                                             [--claude-bin <path>] [--dry-run]
+ *
+ * --issue/--pr select the target; with neither, the prompt targets the current state.
+ * --prompt overrides the generated dev-loop prompt entirely.
+ * --claude-bin overrides the `claude` binary path.
+ * --dry-run prints the resolved command + the DEVLOOPS_RUN_ID without spawning `claude`
+ *   (CI-safe; no API key / `claude` binary required).
+ */
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { ensureRunId } from "@dev-loops/core/loop/run-context";
+import {
+  buildDevLoopPrompt,
+  buildHeadlessClaudeInvocation,
+  DEFAULT_CLAUDE_BIN,
+} from "@dev-loops/core/claude/headless-entry";
+
+function parseArgs(argv) {
+  const opts = { dryRun: false, claudeBin: DEFAULT_CLAUDE_BIN };
+  const requireValue = (name, i) => {
+    const v = argv[i + 1];
+    if (v === undefined || v.startsWith("--")) throw new Error(`${name} requires a value`);
+    return v;
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--dry-run") opts.dryRun = true;
+    else if (a === "--issue") { opts.issue = requireValue(a, i); i++; }
+    else if (a === "--pr") { opts.pr = requireValue(a, i); i++; }
+    else if (a === "--claude-bin") { opts.claudeBin = requireValue(a, i); i++; }
+    else if (a === "--prompt") { opts.prompt = requireValue(a, i); i++; }
+    else throw new Error(`unknown argument: ${a}`);
+  }
+  if (opts.issue != null && opts.pr != null) {
+    throw new Error("--issue and --pr are mutually exclusive");
+  }
+  return opts;
+}
+
+function main(argv) {
+  let opts;
+  try {
+    opts = parseArgs(argv);
+  } catch (error) {
+    process.stderr.write(JSON.stringify({ ok: false, error: error.message }) + "\n");
+    return 1;
+  }
+  const repoRoot = path.resolve(fileURLToPath(new URL("../../", import.meta.url)));
+
+  // --dry-run is side-effect-free: mint a run id in-memory without persisting the state file.
+  const { runId } = ensureRunId({ env: process.env, root: opts.dryRun ? undefined : repoRoot });
+  const prompt = opts.prompt ?? buildDevLoopPrompt({ issue: opts.issue, pr: opts.pr });
+  const { command, args, env } = buildHeadlessClaudeInvocation({
+    prompt,
+    runId,
+    claudeBin: opts.claudeBin,
+  });
+
+  if (opts.dryRun) {
+    process.stdout.write(
+      JSON.stringify({ ok: true, dryRun: true, command, args, runId, DEVLOOPS_RUN_ID: env.DEVLOOPS_RUN_ID }, null, 2) + "\n",
+    );
+    return 0;
+  }
+
+  const res = spawnSync(command, args, { cwd: repoRoot, env, stdio: "inherit" });
+  if (res.error) {
+    process.stderr.write(
+      JSON.stringify({ ok: false, error: `failed to spawn ${command}: ${res.error.message}` }) + "\n",
+    );
+    return 127;
+  }
+  return res.status ?? 1;
+}
+
+process.exit(main(process.argv.slice(2)));

package/scripts/claude/headless-info-smoke.mjs

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+/**
+ * Headless read-only dev-loop info smoke (#775).
+ *
+ * Exercises a read-only dev-loop info path non-interactively (no LLM, no interactive session,
+ * no `@earendil-works/pi-*`), so CI / the Docker image can verify the headless info surface.
+ * Parallel to the Pi Docker smoke (dual-harness). Exits 0 on success.
+ *
+ * Default: `dev-loops status` — a fully offline readiness snapshot that needs no GitHub auth
+ * (it reports "needs setup" rather than failing), so it is safe in a hermetic CI verify job.
+ *
+ * `--loop-info --issue <n>` (or `--pr <n>`) additionally runs `dev-loops loop info`, which
+ * queries GitHub and therefore needs read access (a token / `gh` auth). Opt-in: skipped by
+ * default so the smoke stays secret-free.
+ *
+ * Usage: node scripts/claude/headless-info-smoke.mjs [--loop-info --issue <n> | --pr <n>]
+ */
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+function parseArgs(argv) {
+  const opts = { loopInfo: false };
+  const requireValue = (name, i) => {
+    const v = argv[i + 1];
+    if (v === undefined || v.startsWith("--")) throw new Error(`${name} requires a value`);
+    return v;
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--loop-info") opts.loopInfo = true;
+    else if (a === "--issue") { opts.issue = requireValue(a, i); i++; }
+    else if (a === "--pr") { opts.pr = requireValue(a, i); i++; }
+    else throw new Error(`unknown argument: ${a}`);
+  }
+  if (opts.issue != null && opts.pr != null) {
+    throw new Error("--issue and --pr are mutually exclusive");
+  }
+  return opts;
+}
+
+function runCli(cliEntry, repoRoot, args) {
+  return spawnSync(process.execPath, [cliEntry, ...args], { cwd: repoRoot, encoding: "utf8" });
+}
+
+function main(argv) {
+  let opts;
+  try {
+    opts = parseArgs(argv);
+  } catch (error) {
+    process.stderr.write(JSON.stringify({ ok: false, error: error.message }) + "\n");
+    return 1;
+  }
+  const repoRoot = path.resolve(fileURLToPath(new URL("../../", import.meta.url)));
+  const cliEntry = path.join(repoRoot, "cli", "index.mjs");
+
+  // Offline, secret-free read-only info path — the CI/Docker smoke.
+  const statusRes = runCli(cliEntry, repoRoot, ["status"]);
+  if (statusRes.status !== 0) {
+    process.stderr.write(
+      JSON.stringify({ ok: false, error: "headless `dev-loops status` smoke failed", status: statusRes.status, stderr: statusRes.stderr }) + "\n",
+    );
+    return statusRes.status ?? 1;
+  }
+  process.stdout.write(statusRes.stdout);
+
+  // Opt-in GitHub-backed info path (needs read access; not run by the hermetic CI smoke).
+  if (opts.loopInfo) {
+    if (opts.issue == null && opts.pr == null) {
+      process.stderr.write(
+        JSON.stringify({ ok: false, error: "--loop-info requires an explicit --issue <n> or --pr <n> target" }) + "\n",
+      );
+      return 1;
+    }
+    const target = opts.pr ? ["--pr", String(opts.pr)] : ["--issue", String(opts.issue)];
+    const infoRes = runCli(cliEntry, repoRoot, ["loop", "info", ...target]);
+    if (infoRes.status !== 0) {
+      process.stderr.write(
+        JSON.stringify({ ok: false, error: "headless `dev-loops loop info` smoke failed (needs GitHub read access)", status: infoRes.status, stderr: infoRes.stderr }) + "\n",
+      );
+      return infoRes.status ?? 1;
+    }
+    process.stdout.write(infoRes.stdout);
+  }
+
+  process.stdout.write(JSON.stringify({ ok: true, smoke: "headless-info", loopInfo: opts.loopInfo }) + "\n");
+  return 0;
+}
+
+process.exit(main(process.argv.slice(2)));

package/scripts/github/_review-thread-mutations.mjs

@@ -207,6 +207,9 @@ export function authorMatchesFilter(commentAuthorLogin, authorFilter) {
   if (normalizedLogin.length === 0 || normalizedFilter.length === 0) {
     return false;
   }
+  if (normalizedFilter.toLowerCase() === "all") {
+    return true;
+  }
   if (normalizedFilter.toLowerCase() === "copilot") {
     return isCopilotLogin(normalizedLogin) || normalizedLogin.toLowerCase() === "copilot";
   }

package/scripts/github/reply-resolve-review-threads.mjs

@@ -17,11 +17,11 @@ Required:
   --repo <owner/name>   Repository slug (e.g. owner/repo)
   --pr <number>         Pull request number
 Optional:
-  --author <login>      Match threads containing a comment from this author (default: Copilot)
+  --author <login>      Match threads containing a comment from this author (default: all)
   --message <text>      Reply body text; provide exactly one message source via --message or stdin
   --resolve             Resolve each matched thread after the reply succeeds
 Output (stdout, JSON):
-  { "ok": true, "repo": "owner/name", "pr": 17, "author": "Copilot", "resolve": true,
+  { "ok": true, "repo": "owner/name", "pr": 17, "author": "all", "resolve": true,
     "matchedThreadCount": 2, "repliedThreadCount": 2, "resolvedThreadCount": 2,
     "skippedThreadCount": 1, "results": [{ ... }] }
 Error output (stderr, JSON):
@@ -39,7 +39,7 @@ export function parseReplyResolveThreadsCliArgs(argv) {
     help: false,
     repo: undefined,
     pr: undefined,
-    author: "Copilot",
+    author: "all",
     message: undefined,
     resolve: false,
   };

package/scripts/github/upsert-checkpoint-verdict.mjs

@@ -8,6 +8,7 @@ import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 import { loadPrGateCoordinationContext } from "../loop/detect-pr-gate-coordination-state.mjs";
 import { evaluatePrGateCoordination, PR_CHECKPOINT_ACTION } from "@dev-loops/core/loop/pr-gate-coordination";
 import { STATE } from "@dev-loops/core/loop/copilot-loop-state";
+import { resolveRunId } from "@dev-loops/core/loop/run-context";
 import { claimRunnerOwnership } from "../loop/_pr-runner-coordination.mjs";
 import { detectStaleRunner } from "../loop/_stale-runner-detection.mjs";
 import { detectInternalOnly } from "../loop/detect-internal-only-pr.mjs";
@@ -452,7 +453,7 @@ export async function upsertCheckpointVerdict(options, { env = process.env, ghCo
   // Root cause 1: allow resurrected sessions to claim ownership when the previous
   // run's coordination record is stale. Without this, a new run ID is rejected even
   // though the old run is dead, forcing manual file deletion.
-  const envRunId = typeof env?.PI_SUBAGENT_RUN_ID === "string" ? env.PI_SUBAGENT_RUN_ID.trim() : "";
+  const envRunId = resolveRunId(env) ?? "";
   if (envRunId) {
     try {
       const staleCheck = await detectStaleRunner({ repo: options.repo, pr: options.pr, cwd: repoRoot });
@@ -606,7 +607,7 @@ export async function upsertCheckpointVerdict(options, { env = process.env, ghCo
   if (existing) {
     const updated = await updateComment({ repo: options.repo, commentId: existing.commentId, body: desiredBody }, { env, ghCommand });
     // Post-update verification: verify the updated comment is visible via direct API fetch by comment ID.
-    // PI_SUBAGENT_RUN_ID is set (production context).
+    // A run id is set (production context) — DEVLOOPS_RUN_ID, or the PI_SUBAGENT_RUN_ID alias.
     let updateVerificationWarning = null;
     if (envRunId) {
       let verified = await verifyComment({ repo: options.repo, commentId: updated.commentId }, { env, ghCommand });
@@ -639,7 +640,7 @@ export async function upsertCheckpointVerdict(options, { env = process.env, ghCo
   // comment is not yet returned by paginated list endpoints. A direct fetch
   // by comment ID confirms the comment is persisted, preventing the evidence
   // checker from falsely reporting "missing" and triggering a duplicate post.
-  // Only active when PI_SUBAGENT_RUN_ID is set (production context).
+  // Only active when a run id is set (production context) — DEVLOOPS_RUN_ID or the PI_SUBAGENT_RUN_ID alias.
   let verified = true;
   let verificationWarning = null;
   if (envRunId) {

package/scripts/loop/_pr-runner-coordination.mjs

@@ -1,6 +1,7 @@
 import path from "node:path";
 import process from "node:process";
 import { parseRepoSlugParts } from "@dev-loops/core/github/repo-slug";
+import { resolveRunId } from "@dev-loops/core/loop/run-context";
 import {
   loadStateFile as loadSharedStateFile,
   saveStateFile as saveSharedStateFile,
@@ -581,7 +582,7 @@ export async function ensureAsyncRunnerOwnership({
   claimIfMissing = true,
   requireExisting = false,
 } = {}) {
-  const runId = normalizeRunId(env?.PI_SUBAGENT_RUN_ID);
+  const runId = normalizeRunId(resolveRunId(env));
   if (runId === null) {
     return {
       ok: true,

package/scripts/loop/copilot-pr-handoff.mjs

@@ -2,6 +2,7 @@
 import { buildParseError, formatCliError, isCopilotLogin, isDirectCliRun, normalizeTimestamp } from "../_core-helpers.mjs";
 import { parsePrNumber, requireOptionValue, runChild } from "../_cli-primitives.mjs";
 import { detectRepoSlug, parseRepoSlug } from "@dev-loops/core/github/repo-slug";
+import { resolveRunId } from "@dev-loops/core/loop/run-context";
 import path from "node:path";
 import { loadDevLoopConfig, resolveRefinement } from "@dev-loops/core/config";
 import { autoDetectSnapshot } from "./detect-copilot-loop-state.mjs";
@@ -315,9 +316,9 @@ export async function runHandoff(options, { env = process.env, ghCommand = "gh"
   let interpretation = interpretLoopState(snapshot, refinementConfig);
 
   // Check for human comments since last subagent action
-  // Only active in async subagent context (PI_SUBAGENT_RUN_ID set)
+  // Only active in async subagent context (DEVLOOPS_RUN_ID, or the PI_SUBAGENT_RUN_ID alias, set)
   let humanCommentCheck = { paused: false };
-  if (env.PI_SUBAGENT_RUN_ID) {
+  if (resolveRunId(env)) {
     humanCommentCheck = await detectRecentHumanComments(
       { repo: options.repo, pr: options.pr, claimedAtMs: runnerOwnership?.activeRun?.claimedAt ? new Date(runnerOwnership.activeRun.claimedAt).getTime() : undefined },
       { env, ghCommand },

package/scripts/loop/detect-stale-runner.mjs

@@ -3,6 +3,7 @@ import process from "node:process";
 import { buildParseError, formatCliError, isDirectCliRun } from "../_core-helpers.mjs";
 import { parsePrNumber, requireOptionValue } from "../_cli-primitives.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
+import { resolveRunId as resolveEnvRunId } from "@dev-loops/core/loop/run-context";
 import {
   detectStaleRunner,
   STALE_RUNNER_ERROR,
@@ -19,9 +20,9 @@ Optional:
                         Override the staleness threshold (default 30 minutes,
                         or $PI_DEV_LOOP_STALE_RUNNER_MAX_AGE_MS).
   --run-id <id>         Override the active run id (default: read from
-                        PI_SUBAGENT_RUN_ID). When supplied, the detector
-                        additionally verifies the current run id is still
-                        the active owner.
+                        DEVLOOPS_RUN_ID, falling back to the PI_SUBAGENT_RUN_ID
+                        alias). When supplied, the detector additionally verifies
+                        the current run id is still the active owner.
 Output (stdout, JSON; always includes staleRunnerCheck):
   {
     "ok": true,
@@ -100,10 +101,7 @@ function resolveRunId(explicitRunId, env) {
   if (typeof explicitRunId === "string" && explicitRunId.trim().length > 0) {
     return explicitRunId.trim();
   }
-  if (typeof env?.PI_SUBAGENT_RUN_ID === "string" && env.PI_SUBAGENT_RUN_ID.trim().length > 0) {
-    return env.PI_SUBAGENT_RUN_ID.trim();
-  }
-  return null;
+  return resolveEnvRunId(env);
 }
 function buildStaleRunnerCheck(detection) {
   if (detection.status === "no_owner_record") {

package/scripts/loop/info.mjs

@@ -5,6 +5,7 @@ import { fileURLToPath } from "node:url";
 import { buildParseError, formatCliError, isDirectCliRun } from "../_core-helpers.mjs";
 import { requireOptionValue, parsePositiveInteger } from "../_cli-primitives.mjs";
 import { detectRepoSlug, normalizeRepoSlug } from "@dev-loops/core/github/repo-slug";
+import { runContextEnv } from "@dev-loops/core/loop/run-context";
 
 // REPO_ROOT resolves to the git repo root (scripts/loop/info.mjs → scripts/ → repo/)
 const REPO_ROOT = path.resolve(fileURLToPath(new URL("..", import.meta.url)), "..");
@@ -186,12 +187,12 @@ function buildPrInfo(prNumber, repo, cwd) {
 function buildIssueInfo(issueNumber, repo, cwd) {
   const issueData = ghJson(["issue", "view", String(issueNumber), "--repo", repo, "--json", "number,title,body,state,labels,assignees,milestone,url"], cwd);
   
-  // Run startup resolver with synthetic PI_SUBAGENT_RUN_ID to avoid
+  // Run startup resolver with a synthetic neutral run id to avoid
   // async-start contract rejection for GitHub-first issue routes.
   let startupBundle = null;
   try {
     const startupScript = path.join(REPO_ROOT, "scripts/loop/resolve-dev-loop-startup.mjs");
-    const env = { ...process.env, PI_SUBAGENT_RUN_ID: "info-readonly-placeholder" };
+    const env = { ...process.env, ...runContextEnv("info-readonly-placeholder") };
     const raw = execFileSync(process.execPath, [startupScript, "--issue", String(issueNumber)], {
       cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], env,
     });

package/scripts/loop/inspect-run-viewer/server.mjs

@@ -27,6 +27,7 @@ import {
 } from "../_inspect-run-viewer-adapter.mjs";
 import { dedupeRepoSlugOptions, repoSlugEquals } from "@dev-loops/core/github/repo-slug";
 import { buildDevLoopHandoffEnvelope } from "@dev-loops/core/loop/handoff-envelope";
+import { runContextEnv } from "@dev-loops/core/loop/run-context";
 import { loadDevLoopConfig } from "@dev-loops/core/config";
 
 const execFile = promisify(execFileCallback);
@@ -100,7 +101,7 @@ async function runResolverForTarget(target, { repoRoot = process.cwd() } = {}) {
     throw new Error("Cannot resolve handoff envelope: target repo is required");
   }
   const args = ["scripts/loop/resolve-dev-loop-startup.mjs", "--pr", String(target.pr)];
-  const env = { ...process.env, PI_SUBAGENT_RUN_ID: "viewer-operator-tool" };
+  const env = { ...process.env, ...runContextEnv("viewer-operator-tool") };
   const { stdout, stderr } = await execFile("node", args, { cwd: repoRoot, timeout: 30000, env });
   try {
     return JSON.parse(stdout);

package/scripts/loop/outer-loop.mjs

@@ -68,9 +68,9 @@ Stop reasons:
                                        HEAD does not match PR head commit
   unknown_state                        Unrecognized combined state
 Async-start contract:
-  This loop must run within a visible Pi-managed async context when
+  This loop must run within a visible harness-managed async context when
   workflow.asyncStartMode is set to required (default). It fails closed unless
-  PI_SUBAGENT_RUN_ID is set, to prevent hidden detached-process fallback
+  DEVLOOPS_RUN_ID (or the PI_SUBAGENT_RUN_ID alias) is set, to prevent hidden detached-process fallback
   (nohup, disowned shell jobs, etc.). Snapshot/test input mode
   (both --copilot-input and --reviewer-input) is exempt. Any relaxed
   async-start posture is maintainer-controlled repository policy, not an

package/scripts/loop/pr-runner-coordination.mjs

@@ -3,6 +3,7 @@ import process from "node:process";
 import { buildParseError, formatCliError, isDirectCliRun } from "../_core-helpers.mjs";
 import { parsePrNumber, requireOptionValue } from "../_cli-primitives.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
+import { resolveRunId as resolveEnvRunId } from "@dev-loops/core/loop/run-context";
 import {
   assertRunnerOwnership,
   claimRunnerOwnership,
@@ -16,7 +17,8 @@ const USAGE = `Usage:
   pr-runner-coordination.mjs assert --repo <owner/name> --pr <number> [--run-id <id>] [--require-existing]
   pr-runner-coordination.mjs release --repo <owner/name> --pr <number> [--run-id <id>]
 Durable one-runner-per-PR coordination helper.
-If --run-id is omitted for claim/assert/release/takeover, PI_SUBAGENT_RUN_ID is used.
+If --run-id is omitted for claim/assert/release/takeover, DEVLOOPS_RUN_ID is used
+(falling back to the PI_SUBAGENT_RUN_ID alias).
 Output:
   stdout: { "ok": true, ... }
   stderr: { "ok": false, "error": "...", ... }
@@ -81,9 +83,7 @@ function parseCliArgs(argv) {
 function resolveRunId(explicitRunId, env) {
   return typeof explicitRunId === "string" && explicitRunId.trim().length > 0
     ? explicitRunId.trim()
-    : (typeof env?.PI_SUBAGENT_RUN_ID === "string" && env.PI_SUBAGENT_RUN_ID.trim().length > 0
-      ? env.PI_SUBAGENT_RUN_ID.trim()
-      : null);
+    : resolveEnvRunId(env);
 }
 export async function runPrRunnerCoordination(options, { env = process.env, cwd = process.cwd() } = {}) {
   if (options.command === "status") {

package/skills/docs/main-agent-contract.md

@@ -59,14 +59,27 @@ directly.
 
 ## Enforcement posture
 
-- This contract is enforced by convention and review, not by tool-level guards.
-- Mechanical enforcement (pre-commit hooks, tool-level write guards) is a
-  non-goal for this document and may be addressed in follow-up work.
-- A `dev-loop` async subagent should reject delegation attempts that bypass
-  the contract (e.g., direct mutation requests from the main agent).
+- Under **Pi**, this contract is enforced by convention and review.
+- Under **Claude Code**, the **Edit/Write tool** path is enforced **mechanically** by a
+  `PreToolUse` Write/Edit hook (`.claude/hooks/pre-tool-use-write-guard.mjs`, wired via
+  `.claude/settings.json` for this repo's own sessions and via `.claude/hooks/hooks.json` for the
+  Claude plugin): a Write/Edit whose target is inside the repo working tree and not
+  gitignored is **denied** when it originates from the main agent, and allowed only inside the
+  `dev-loop` subagent context (detected via the neutral `DEVLOOPS_RUN_ID` run-id contract, or
+  the dev-loop `agent_type` — a generic subagent is not authorized).
+  Strict enforcement is opt-in via `DEVLOOPS_MAIN_AGENT_READONLY=1` (default fail-open) so
+  adopting the harness does not retroactively break a repo's own interactive dev; full run-id
+  propagation into the Claude subagent context completes with the headless/agent wiring.
+- **Scope of mechanical enforcement:** the hook covers the Edit and Write tools. Bash-driven
+  repo mutations the contract also forbids (`git commit`/`git push`/branch creation, in-place
+  edits like `sed -i`, shell redirection `> file` / `tee`) run through the Bash tool and remain
+  **convention-enforced** for now; the only Bash command the gate hook blocks is the ungated
+  `gh pr ready`. Tightening Bash-mutation coverage is possible follow-up.
+- A companion `PreToolUse` Bash hook reproduces the `gh pr ready` draft-gate guard.
+- A `dev-loop` async subagent should still reject delegation attempts that bypass the contract.
 
 ## Non-goals
 
-- Tool-level enforcement (file-write guards, pre-commit hooks)
+- Pre-commit hooks (out of scope; the boundary is enforced at the Claude tool layer).
 - Changing dev-loop resolver behavior
 - Modifying the subagent API itself