dev-loops 0.6.0 → 0.7.2

package/scripts/loop/inspect-run-viewer-ci-changes.mjs

@@ -1,11 +1,13 @@
 #!/usr/bin/env node
 import { appendFile, readFile } from "node:fs/promises";
 import { buildParseError, formatCliError, isDirectCliRun } from "../_core-helpers.mjs";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult } from "../lib/jq-output.mjs";
+import { parseArgs } from "node:util";
 export const INSPECT_RUN_VIEWER_RELEVANT_EXACT_PATHS = Object.freeze([
   ".github/workflows/ci.yml",
   "package.json",
   "package-lock.json",
-  "playwright.inspect-run-viewer.config.mjs",
+  "playwright.config.mjs",
   "scripts/loop/_inspect-run-viewer-adapter.mjs",
   "scripts/loop/inspect-run-viewer.mjs",
   "scripts/loop/inspect-run-viewer-ci-changes.mjs",
@@ -22,9 +24,13 @@ Classify changed files to determine if inspect-run-viewer tests should run.
 Reads a newline-delimited file list and checks against known relevant paths.
 Options:
   --help, -h    Show this help
+
+${JQ_OUTPUT_USAGE}
+
 Exit codes:
   0   Success
   1   Error
+  2   Invalid --jq filter
 `;
 const parseError = buildParseError(USAGE);
 export function normalizeInspectRunViewerPath(filePath) {
@@ -52,21 +58,27 @@ export function classifyInspectRunViewerCiChanges(changedPaths = []) {
 }
 export async function runCli(
   argv = process.argv.slice(2),
-  { env = process.env, stdout = process.stdout } = {},
+  { env = process.env, stdout = process.stdout, stderr = process.stderr } = {},
 ) {
-  if (argv.length === 1 && (argv[0] === "--help" || argv[0] === "-h")) {
+  const { values, positionals } = parseArgs({
+    args: [...argv],
+    options: { help: { type: "boolean", short: "h" }, ...JQ_OUTPUT_PARSE_OPTIONS },
+    allowPositionals: true,
+    strict: false,
+  });
+  if (values.help) {
     stdout.write(HELP);
     return;
   }
-  if (argv.length !== 1) {
+  if (positionals.length !== 1) {
     throw parseError("inspect-run-viewer-ci-changes requires exactly one changed-files path argument");
   }
-  const rawPaths = await readFile(argv[0], "utf8");
+  const rawPaths = await readFile(positionals[0], "utf8");
   const result = classifyInspectRunViewerCiChanges(rawPaths.split(/\r?\n/u));
   if (env.GITHUB_OUTPUT) {
     await appendFile(env.GITHUB_OUTPUT, `inspect_run_viewer=${result.shouldRun}\n`, "utf8");
   }
-  stdout.write(`${JSON.stringify({ ok: true, ...result })}\n`);
+  process.exitCode = emitResult({ ok: true, ...result }, { jq: values.jq, silent: values.silent, stdout, stderr });
   return result;
 }
 if (isDirectCliRun(import.meta.url)) {

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

@@ -38,6 +38,63 @@ export {
   resetMermaidBrowserScriptCache,
   restartExistingPortListener,
 };
+// ponytail: lifetime timeout defaults to 8h so a forgotten direct-run viewer cannot leak indefinitely; callers pass lifetimeMs to override.
+export const DEFAULT_SERVER_LIFETIME_MS = 8 * 60 * 60 * 1000;
+
+// Wires signal handlers + a lifetime timeout so a directly-run viewer server is
+// always torn down instead of leaking across sessions. Returns an idempotent
+// teardown() that closes the server and detaches every handler it installed.
+export function installServerTeardown(
+  server,
+  {
+    signals = ["SIGINT", "SIGTERM"],
+    lifetimeMs = DEFAULT_SERVER_LIFETIME_MS,
+    onTeardown = () => {},
+    processImpl = process,
+    setTimeoutImpl = setTimeout,
+    clearTimeoutImpl = clearTimeout,
+  } = {},
+) {
+  let closed = false;
+  let lifetimeTimer = null;
+
+  const teardown = (reason = "teardown") => {
+    if (closed) {
+      return;
+    }
+    closed = true;
+    if (lifetimeTimer !== null) {
+      clearTimeoutImpl(lifetimeTimer);
+      lifetimeTimer = null;
+    }
+    for (const signal of signals) {
+      processImpl.removeListener(signal, signalHandler);
+    }
+    try {
+      onTeardown(reason);
+    } finally {
+      server.close();
+    }
+  };
+
+  function signalHandler(signal) {
+    teardown(signal);
+  }
+
+  for (const signal of signals) {
+    processImpl.on(signal, signalHandler);
+  }
+
+  if (Number.isFinite(lifetimeMs) && lifetimeMs > 0) {
+    lifetimeTimer = setTimeoutImpl(() => teardown("lifetime-timeout"), lifetimeMs);
+    // Do not let the teardown timer itself keep the event loop alive.
+    if (typeof lifetimeTimer?.unref === "function") {
+      lifetimeTimer.unref();
+    }
+  }
+
+  return teardown;
+}
 export async function runCli(
   argv = process.argv.slice(2),
   {
@@ -75,8 +132,14 @@ export async function runCli(
 }
 const isDirectRun = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
 if (isDirectRun) {
-  runCli().catch((error) => {
-    process.stderr.write(`${formatCliError(error)}\n`);
-    process.exitCode = 1;
-  });
+  runCli()
+    .then((server) => {
+      if (server) {
+        installServerTeardown(server);
+      }
+    })
+    .catch((error) => {
+      process.stderr.write(`${formatCliError(error)}\n`);
+      process.exitCode = 1;
+    });
 }

package/scripts/loop/inspect-run.mjs

@@ -23,6 +23,7 @@ import {
 } from "@dev-loops/core/loop/steering";
 import { validateSteeringStateTarget } from "./_steering-state-file.mjs";
 import { parseArgs } from "node:util";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 const USAGE = `Usage: inspect-run.mjs --repo <owner/name> --pr <number>
 Read-only run inspection for the Copilot PR outer-loop family.
 Produces a single JSON snapshot describing the current state of one
@@ -68,9 +69,11 @@ Error output (stderr, JSON):
     { "ok": false, "error": "...", "usage": "..." }
   Runtime failures:
     { "ok": false, "error": "..." }
+${JQ_OUTPUT_USAGE}
 Exit codes:
   0  Success
-  1  Argument error or unexpected runtime failure`.trim();
+  1  Argument error or unexpected runtime failure
+  2  Invalid --jq filter`.trim();
 const parseError = buildParseError(USAGE);
 export function parseInspectRunCliArgs(argv) {
   const options = {
@@ -90,6 +93,7 @@ export function parseInspectRunCliArgs(argv) {
       "steering-state-file": { type: "string" },
       "copilot-input": { type: "string" },
       "reviewer-input": { type: "string" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -126,6 +130,7 @@ export function parseInspectRunCliArgs(argv) {
       options.reviewerInputPath = requireTokenValue(token, parseError);
       continue;
     }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) continue;
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (!options.help) {
@@ -380,6 +385,7 @@ export async function runCli(
   argv = process.argv.slice(2),
   {
     stdout = process.stdout,
+    stderr = process.stderr,
     env = process.env,
     ghCommand = "gh",
   } = {},
@@ -390,7 +396,7 @@ export async function runCli(
     return;
   }
   const snapshot = await inspectRun(options, { env, ghCommand });
-  stdout.write(`${JSON.stringify(snapshot)}\n`);
+  process.exitCode = emitResult(snapshot, { jq: options.jq, silent: options.silent, stdout, stderr });
 }
 const isDirectRun = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
 if (isDirectRun) {

package/scripts/loop/outer-loop.mjs

@@ -26,6 +26,7 @@ import {
 } from "@dev-loops/core/loop/async-start-contract";
 import { loadDevLoopConfig, resolveConductorModel, resolveAutonomyStopAt, resolveWorkflowConfig } from "@dev-loops/core/config";
 import { parseArgs } from "node:util";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 const USAGE = `Usage: outer-loop.mjs --repo <owner/name> --pr <number>
 Thin outer-loop wrapper for the Copilot PR remediation loop.
 Detects current PR state from both the Copilot inner loop and the reviewer
@@ -84,9 +85,11 @@ Error output (stderr, JSON):
     { "ok": false, "error": "..." }
   Async-start contract rejection:
     { "ok": false, "error": "...", "asyncStartContract": "rejected" }
+${JQ_OUTPUT_USAGE}
 Exit codes:
   0  Success
-  1  Argument error, gh/git failure, or indeterminate state`.trim();
+  1  Argument error, gh/git failure, or indeterminate state
+  2  Invalid --jq filter`.trim();
 const parseError = buildParseError(USAGE);
 export function parseOuterLoopCliArgs(argv) {
   const options = {
@@ -106,6 +109,7 @@ export function parseOuterLoopCliArgs(argv) {
       "checkpoint-dir": { type: "string" },
       "copilot-input": { type: "string" },
       "reviewer-input": { type: "string" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -142,6 +146,7 @@ export function parseOuterLoopCliArgs(argv) {
       options.reviewerInputPath = requireTokenValue(token, parseError);
       continue;
     }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) continue;
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (!options.help) {
@@ -426,11 +431,10 @@ export async function runCli(
   }
   const result = await runOuterLoop(options, { env, ghCommand, gitCommand });
   if (result.ok === false) {
-    stderr.write(`${JSON.stringify(result)}\n`);
-    process.exitCode = 1;
+    process.exitCode = emitResult(result, { jq: options.jq, silent: options.silent, stdout: stderr, stderr });
     return;
   }
-  stdout.write(`${JSON.stringify(result)}\n`);
+  process.exitCode = emitResult(result, { jq: options.jq, silent: options.silent, stdout, stderr });
 }
 const isDirectRun = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
 if (isDirectRun) {

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

@@ -5,7 +5,7 @@ import { buildParseError, formatCliError, isDirectCliRun } from "../_core-helper
 import { parsePrNumber, requireTokenValue } 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 { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult } from "../lib/jq-output.mjs";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 import {
   assertRunnerOwnership,
   claimRunnerOwnership,
@@ -88,14 +88,7 @@ function parseCliArgs(argv) {
       options.requireExisting = true;
       continue;
     }
-    if (token.name === "jq") {
-      options.jq = requireTokenValue(token, parseError);
-      continue;
-    }
-    if (token.name === "silent") {
-      options.silent = true;
-      continue;
-    }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) continue;
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
   const validCommands = new Set(["status", "claim", "takeover", "assert", "release"]);

package/scripts/loop/pre-commit-branch-guard.mjs

@@ -5,11 +5,14 @@ import { parseArgs } from "node:util";
 import {
   isUnderWorktreePath, parseMainWorktreePath, isMainCheckout,
 } from "@dev-loops/core/loop/worktree-guard";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 
 const USAGE = `Usage:
   pre-commit-branch-guard.mjs --expected-branch <name> [--require-worktree] [--block-main-checkout]
 
-Verify the current git branch identity and/or worktree isolation before local commit steps.`;
+Verify the current git branch identity and/or worktree isolation before local commit steps.
+
+${JQ_OUTPUT_USAGE}`;
 
 const parseError = buildParseError(USAGE);
 
@@ -22,6 +25,7 @@ export function parseBranchGuardCliArgs(argv) {
       "expected-branch": { type: "string" },
       "require-worktree": { type: "boolean" },
       "block-main-checkout": { type: "boolean" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -38,6 +42,7 @@ export function parseBranchGuardCliArgs(argv) {
     if (token.name === "expected-branch") { options.expectedBranch = requireTokenValue(token, parseError, { flagPattern: /^-/u }); continue; }
     if (token.name === "require-worktree") { options.requireWorktree = true; continue; }
     if (token.name === "block-main-checkout") { options.blockMainCheckout = true; continue; }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) continue;
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (options.expectedBranch === undefined) { throw parseError("--expected-branch <name> is required"); }
@@ -48,12 +53,15 @@ export async function runCli(argv = process.argv.slice(2), { stdout = process.st
   const options = parseBranchGuardCliArgs(argv);
   if (options.help) { stdout.write(`${USAGE}\n`); return { ok: true, help: true }; }
 
+  const emit = (payload, target) => {
+    process.exitCode = emitResult(payload, { jq: options.jq, silent: options.silent, stdout: target, stderr });
+    return payload;
+  };
+
   const { stdout: branchOutput } = await runCommand(gitCommand, ["branch", "--show-current"], { cwd, env });
   const currentBranch = branchOutput.trim();
   if (currentBranch !== options.expectedBranch) {
-    const payload = { ok: false, error: "branch_mismatch", current: currentBranch, expected: options.expectedBranch };
-    stderr.write(`${JSON.stringify(payload)}\n`);
-    return payload;
+    return emit({ ok: false, error: "branch_mismatch", current: currentBranch, expected: options.expectedBranch }, stderr);
   }
 
   let worktreeOk = null, mainCheckoutBlocked = null;
@@ -64,22 +72,20 @@ export async function runCli(argv = process.argv.slice(2), { stdout = process.st
     }
     if (options.requireWorktree) {
       worktreeOk = isUnderWorktreePath(cwd);
-      if (!worktreeOk) { stderr.write(JSON.stringify({ ok: false, error: "not_in_worktree", cwd, requiredPrefix: "tmp/worktrees/" }) + "\n"); return { ok: false, error: "not_in_worktree" }; }
+      if (!worktreeOk) { return emit({ ok: false, error: "not_in_worktree", cwd, requiredPrefix: "tmp/worktrees/" }, stderr); }
     }
     if (options.blockMainCheckout) {
       const isMain = isMainCheckout(cwd, mainWorktreePath);
       mainCheckoutBlocked = !(isMain && !isUnderWorktreePath(cwd));
-      if (!mainCheckoutBlocked) { stderr.write(JSON.stringify({ ok: false, error: "main_checkout_blocked", cwd, mainWorktree: mainWorktreePath }) + "\n"); return { ok: false, error: "main_checkout_blocked" }; }
+      if (!mainCheckoutBlocked) { return emit({ ok: false, error: "main_checkout_blocked", cwd, mainWorktree: mainWorktreePath }, stderr); }
     }
     if (!options.requireWorktree) worktreeOk = null;
     if (!options.blockMainCheckout) mainCheckoutBlocked = null;
   }
 
-  const payload = { ok: true, branch: currentBranch, matched: true, worktreeOk, mainCheckoutBlocked };
-  stdout.write(`${JSON.stringify(payload)}\n`);
-  return payload;
+  return emit({ ok: true, branch: currentBranch, matched: true, worktreeOk, mainCheckoutBlocked }, stdout);
 }
 
 if (isDirectCliRun(import.meta.url)) {
-  runCli().then((result) => { if (result?.ok === false) { process.exitCode = 1; } }).catch((error) => { process.stderr.write(`${formatCliError(error)}\n`); process.exitCode = 1; });
+  runCli().catch((error) => { process.stderr.write(`${formatCliError(error)}\n`); process.exitCode = 1; });
 }

package/scripts/loop/pre-flight-gate.mjs

@@ -12,6 +12,7 @@ import {
   isListedWorktree,
   detectSubagentAvailability,
 } from "@dev-loops/core/loop/worktree-guard";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 const DEVLOOPS_PREFLIGHT_BYPASS_VAR = "DEVLOOPS_PREFLIGHT_BYPASS";
 const USAGE = `Usage:
   pre-flight-gate.mjs [--expected-branch <name>] [--check-subagents]
@@ -28,7 +29,9 @@ Violation output (stderr, JSON, exit 1):
   { "ok": false, "error": "<error_code>", "checks": { ... },
     "guidance": "<actionable instruction for the agent>" }
 Bypass:
-  DEVLOOPS_PREFLIGHT_BYPASS=1   Skip all checks (for development/testing only).`.trim();
+  DEVLOOPS_PREFLIGHT_BYPASS=1   Skip all checks (for development/testing only).
+
+${JQ_OUTPUT_USAGE}`.trim();
 const parseError = buildParseError(USAGE);
 export function parsePreFlightGateCliArgs(argv) {
   const options = {
@@ -42,6 +45,7 @@ export function parsePreFlightGateCliArgs(argv) {
       help: { type: "boolean", short: "h" },
       "expected-branch": { type: "string" },
       "check-subagents": { type: "boolean" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -66,6 +70,7 @@ export function parsePreFlightGateCliArgs(argv) {
       options.checkSubagents = true;
       continue;
     }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) continue;
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
   return options;
@@ -189,7 +194,7 @@ export async function runCli(
       checks: { worktree: true, branch: "skipped", subagents: "skipped" },
       summary: "pre-flight gate bypassed via DEVLOOPS_PREFLIGHT_BYPASS=1",
     };
-    stdout.write(`${JSON.stringify(payload)}\n`);
+    process.exitCode = emitResult(payload, { jq: options.jq, silent: options.silent, stdout, stderr });
     return payload;
   }
   const checks = { worktree: false, branch: "skipped", subagents: "skipped" };
@@ -230,7 +235,7 @@ export async function runCli(
       guidance: errors.map((e) => e.guidance).join("\n\n"),
       errors,
     };
-    stderr.write(`${JSON.stringify(payload)}\n`);
+    process.exitCode = emitResult(payload, { jq: options.jq, silent: options.silent, stdout: stderr, stderr });
     return payload;
   }
   const payload = {
@@ -238,16 +243,11 @@ export async function runCli(
     checks,
     summary: "all checks passed",
   };
-  stdout.write(`${JSON.stringify(payload)}\n`);
+  process.exitCode = emitResult(payload, { jq: options.jq, silent: options.silent, stdout, stderr });
   return payload;
 }
 if (isDirectCliRun(import.meta.url)) {
   runCli()
-    .then((result) => {
-      if (result?.ok === false) {
-        process.exitCode = 1;
-      }
-    })
     .catch((error) => {
       process.stderr.write(`${formatCliError(error)}\n`);
       process.exitCode = 1;

package/scripts/loop/pre-pr-ready-gate.mjs

@@ -10,6 +10,7 @@ import {
 import { parsePrNumber, requireTokenValue, runChild } from "../_cli-primitives.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 import { parseArgs } from "node:util";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 
 const USAGE = `Usage:
   pre-pr-ready-gate.mjs --repo <owner/name> --pr <number>
@@ -33,7 +34,8 @@ Output (stdout, JSON on success):
   }
 
 Error output (stderr, JSON):
-  { "ok": false, "error": "<reason>" }`.trim();
+  { "ok": false, "error": "<reason>" }
+${JQ_OUTPUT_USAGE}`.trim();
 
 const parseError = buildParseError(USAGE);
 const PR_VIEW_QUERY = `query($owner:String!, $name:String!, $number:Int!) { repository(owner:$owner, name:$name) { pullRequest(number:$number) { id, isDraft, headRefOid, state } } }`;
@@ -46,6 +48,7 @@ export function parsePrePrReadyGateCliArgs(argv) {
       help: { type: "boolean", short: "h" },
       repo: { type: "string" },
       pr: { type: "string" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -61,6 +64,7 @@ export function parsePrePrReadyGateCliArgs(argv) {
     if (token.name === "help") { options.help = true; return options; }
     if (token.name === "repo") { options.repo = requireTokenValue(token, parseError).trim(); continue; }
     if (token.name === "pr") { options.pr = parsePrNumber(requireTokenValue(token, parseError), parseError); continue; }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) continue;
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (options.repo === undefined || options.pr === undefined) {
@@ -183,11 +187,11 @@ export async function runCli(argv = process.argv.slice(2), runtime = {}) {
   }
   const result = await prePrReadyGate(options, runtime);
   if (!result.ok) {
-    process.stderr.write(`${JSON.stringify(result)}\n`);
-    process.exitCode = 1;
+    // Failure prints to stderr (existing contract); jq/silent apply there too.
+    process.exitCode = emitResult(result, { jq: options.jq, silent: options.silent, stdout: process.stderr, stderr: process.stderr });
     return result;
   }
-  process.stdout.write(`${JSON.stringify(result)}\n`);
+  process.exitCode = emitResult(result, { jq: options.jq, silent: options.silent, stdout: process.stdout, stderr: process.stderr });
   return result;
 }
 

package/scripts/loop/pre-write-remote-freshness-guard.mjs

@@ -2,8 +2,9 @@
 import { buildParseError, formatCliError, isDirectCliRun } from "../_core-helpers.mjs";
 import { requireTokenValue, runCommand } from "../_cli-primitives.mjs";
 import { parseArgs } from "node:util";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 
-const USAGE = `Usage: pre-write-remote-freshness-guard.mjs --branch <name>\nRefresh remote branch state before starting local file writes.`;
+const USAGE = `Usage: pre-write-remote-freshness-guard.mjs --branch <name>\nRefresh remote branch state before starting local file writes.\n\n${JQ_OUTPUT_USAGE}`;
 const parseError = buildParseError(USAGE);
 
 export function parseRemoteFreshnessGuardCliArgs(argv) {
@@ -13,6 +14,7 @@ export function parseRemoteFreshnessGuardCliArgs(argv) {
     options: {
       help: { type: "boolean", short: "h" },
       branch: { type: "string" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -27,6 +29,7 @@ export function parseRemoteFreshnessGuardCliArgs(argv) {
     }
     if (token.name === "help") { options.help = true; return options; }
     if (token.name === "branch") { options.branch = requireTokenValue(token, parseError, { flagPattern: /^-/u }); continue; }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) continue;
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (options.branch === undefined) throw parseError("--branch <name> is required");
@@ -39,10 +42,16 @@ export async function runCli(argv = process.argv.slice(2), { stdout = process.st
   await runCommand(gitCommand, ["fetch", "origin", options.branch], { cwd, env });
   const { stdout: logOutput } = await runCommand(gitCommand, ["log", `HEAD..origin/${options.branch}`, "--oneline"], { cwd, env });
   const newCommits = logOutput.split(/\r?\n/u).map(l => l.trim()).filter(l => l.length > 0);
-  if (newCommits.length === 0) { const p = { ok: true, status: "up_to_date" }; stdout.write(`${JSON.stringify(p)}\n`); return p; }
-  const p = { ok: false, error: "remote_ahead", newCommits }; stderr.write(`${JSON.stringify(p)}\n`); return p;
+  if (newCommits.length === 0) {
+    const p = { ok: true, status: "up_to_date" };
+    process.exitCode = emitResult(p, { jq: options.jq, silent: options.silent, stdout, stderr });
+    return p;
+  }
+  const p = { ok: false, error: "remote_ahead", newCommits };
+  process.exitCode = emitResult(p, { jq: options.jq, silent: options.silent, stdout: stderr, stderr });
+  return p;
 }
 
 if (isDirectCliRun(import.meta.url)) {
-  runCli().then(r => { if (r?.ok === false) process.exitCode = 1; }).catch(e => { process.stderr.write(`${formatCliError(e)}\n`); process.exitCode = 1; });
+  runCli().catch(e => { process.stderr.write(`${formatCliError(e)}\n`); process.exitCode = 1; });
 }

package/scripts/loop/provision-worktree.mjs

@@ -12,6 +12,15 @@
  * - Idempotent: skips a dest that is already correct.
  * - Does NOT run npm install (deps belong to `npm ci`-in-worktree).
  *
+ * Also (unconditionally, independent of .devloops): links the workspace
+ * package node_modules/@dev-loops/core -> ../../packages/core (relative,
+ * pointing at the WORKTREE's own packages/core). Without npm install/ci in a
+ * fresh worktree there is no node_modules at all, so scripts/**'s
+ * `@dev-loops/core` imports resolve UP-TREE to the nearest ancestor
+ * node_modules (the main checkout's) — silently testing main's core instead
+ * of the branch's (#1144). Stale/broken links are replaced; a real file/dir
+ * already occupying the slot is left alone (dest-conflict, never clobbered).
+ *
  * Prints a JSON summary of actions to stdout. Never throws on a per-entry
  * problem; exits 0 unless its own arguments are invalid.
  */
@@ -21,6 +30,7 @@ import { buildParseError, formatCliError, isDirectCliRun } from "../_core-helper
 import { requireTokenValue } from "../_cli-primitives.mjs";
 import { parseArgs } from "node:util";
 import { loadDevLoopConfig, resolveWorktreeConfig } from "@dev-loops/core/config";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 
 const USAGE = `Usage:
   provision-worktree.mjs --worktree-path <p> --repo-root <p>
@@ -34,7 +44,9 @@ Optional:
 Output (stdout, JSON):
   { "ok": true, "actions": [ { "mode": "copy"|"link"|"skip"|"reject", ... } ],
     "summary": { "copied": n, "linked": n, "skipped": n, "rejected": n,
-                 "warnings": n } }`.trim();
+                 "warnings": n } }
+
+${JQ_OUTPUT_USAGE}`.trim();
 
 const parseError = buildParseError(USAGE);
 
@@ -46,6 +58,7 @@ export function parseProvisionWorktreeCliArgs(argv) {
       help: { type: "boolean", short: "h" },
       "worktree-path": { type: "string" },
       "repo-root": { type: "string" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -66,6 +79,7 @@ export function parseProvisionWorktreeCliArgs(argv) {
       options.repoRoot = requireTokenValue(token, parseError, { flagPattern: /^-/u });
       continue;
     }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) continue;
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (!options.worktreePath) throw parseError("Missing required --worktree-path");
@@ -156,6 +170,45 @@ async function provisionLink(src, dest, logWarn) {
   return { mode: "link", src, dest };
 }
 
+/**
+ * Ensure node_modules/@dev-loops/core -> ../../packages/core (relative) in the
+ * worktree, pointing at the worktree's OWN packages/core — never the main
+ * checkout's (#1144). Idempotent: a correct link is a no-op; a stale/broken
+ * link is replaced; a real file/dir at the dest is a dest-conflict skip
+ * (never clobbered). node_modules is gitignored repo-wide, so this link is
+ * always untracked.
+ */
+async function ensureCoreWorkspaceLink(worktreePath, logWarn) {
+  const corePkgDir = path.join(worktreePath, "packages", "core");
+  const scopeDir = path.join(worktreePath, "node_modules", "@dev-loops");
+  const linkPath = path.join(scopeDir, "core");
+
+  if (!(await pathExists(corePkgDir))) {
+    logWarn(`workspace self-link source missing, skipping: ${corePkgDir}`);
+    return { mode: "skip", reason: "source-missing", src: corePkgDir, dest: linkPath };
+  }
+
+  const relTarget = path.relative(scopeDir, corePkgDir);
+  const existing = await fsp.readlink(linkPath).catch(() => null);
+  if (existing !== null) {
+    // Only the exact RELATIVE target is idempotent. An absolute (or otherwise
+    // differently-spelled) link that happens to resolve correctly is
+    // normalized to the relative form — absolute links break when the
+    // worktree moves under tmp/.
+    if (existing === relTarget) {
+      return { mode: "skip", reason: "exists", src: corePkgDir, dest: linkPath };
+    }
+    await fsp.rm(linkPath, { force: true }); // stale/absolute/broken — replace below
+  } else if (await pathExists(linkPath)) {
+    logWarn(`workspace self-link dest conflict (not a symlink), skipping: ${linkPath}`);
+    return { mode: "skip", reason: "dest-conflict", src: corePkgDir, dest: linkPath };
+  }
+
+  await fsp.mkdir(scopeDir, { recursive: true });
+  await fsp.symlink(relTarget, linkPath);
+  return { mode: "link", src: corePkgDir, dest: linkPath };
+}
+
 export async function provisionWorktree({ worktreePath, repoRoot }, { loadConfig = loadDevLoopConfig } = {}) {
   const root = path.resolve(repoRoot);
   const dst = path.resolve(worktreePath);
@@ -215,6 +268,24 @@ export async function provisionWorktree({ worktreePath, repoRoot }, { loadConfig
     }
   }
 
+  // Unconditional (not driven by .devloops, still applies under a fail-closed
+  // empty config) — the worktree's own package resolution is a structural
+  // need, not an opt-in copy/link entry.
+  try {
+    const selfLink = await ensureCoreWorkspaceLink(dst, logWarn);
+    actions.push({ entry: "node_modules/@dev-loops/core", ...selfLink });
+  } catch (err) {
+    const msg = (err && err.message) ? err.message : String(err);
+    logWarn(`workspace self-link failed, skipping: ${msg}`);
+    actions.push({
+      entry: "node_modules/@dev-loops/core",
+      mode: "skip",
+      reason: `link-failed: ${msg}`,
+      src: path.join(dst, "packages", "core"),
+      dest: path.join(dst, "node_modules", "@dev-loops", "core"),
+    });
+  }
+
   const summary = { copied: 0, linked: 0, skipped: 0, rejected: 0, warnings: warnings.length };
   for (const a of actions) {
     if (a.mode === "copy") summary.copied++;
@@ -225,14 +296,14 @@ export async function provisionWorktree({ worktreePath, repoRoot }, { loadConfig
   return { ok: true, actions, summary };
 }
 
-export async function runCli(argv = process.argv.slice(2), { stdout = process.stdout } = {}) {
+export async function runCli(argv = process.argv.slice(2), { stdout = process.stdout, stderr = process.stderr } = {}) {
   const options = parseProvisionWorktreeCliArgs(argv);
   if (options.help) {
     stdout.write(`${USAGE}\n`);
     return;
   }
   const result = await provisionWorktree(options);
-  stdout.write(`${JSON.stringify(result)}\n`);
+  process.exitCode = emitResult(result, { jq: options.jq, silent: options.silent, stdout, stderr });
 }
 
 if (isDirectCliRun(import.meta.url)) {