dev-loops 0.4.0 → 0.6.0

package/scripts/lib/jq-output.mjs

@@ -0,0 +1,297 @@
+// Shared --jq / --silent output helper for the JSON-emitting dev-loops scripts
+// (issue #981, subsumes #963). One helper applied uniformly so the loop never
+// falls back to `gh api | python3` or inline `node -e` to read tool JSON.
+//
+// Convention (also documented in skills/dev-loop/SKILL.md):
+//   prefer the dev-loops subcommand
+//     -> `--silent`/`-s` for a yes/no status check (zero output, exit code only)
+//     -> `--jq <filter>` to extract a field from the result
+//     -> `gh --jq` on a raw gh call
+//     -> NEVER `| python3` or `node -e`.
+//
+// jq subset (NOT full jq — fails closed clearly on anything outside this):
+//   .                identity
+//   .field           field access (also .a.b.c chains)
+//   .field[]         iterate an array field
+//   .[]              iterate an array / object values
+//   .[N] / .field[N] index access
+//   a | b            pipe
+//   select(<pred>)   filter the current value(s) by a predicate
+//   length           count of array/string/object
+//   keys             sorted object keys (or array indices)
+//   predicates inside select: .x == <lit>, !=, <, <=, >, >=, and a bare path
+//                  (truthy test). <lit> is a JSON string/number/true/false/null.
+// Anything else -> JqFilterError (fail closed).
+
+export class JqFilterError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "JqFilterError";
+    this.isJqFilterError = true;
+  }
+}
+
+// A jq "stream" is an array of values (jq filters are many-valued). We thread an
+// array through each pipe stage. Identity is [value].
+
+function parseLiteral(token) {
+  const trimmed = token.trim();
+  if (trimmed === "true") return { ok: true, value: true };
+  if (trimmed === "false") return { ok: true, value: false };
+  if (trimmed === "null") return { ok: true, value: null };
+  if (/^-?\d+(\.\d+)?$/.test(trimmed)) return { ok: true, value: Number(trimmed) };
+  if (
+    (trimmed.startsWith('"') && trimmed.endsWith('"') && trimmed.length >= 2) ||
+    (trimmed.startsWith("'") && trimmed.endsWith("'") && trimmed.length >= 2)
+  ) {
+    return { ok: true, value: trimmed.slice(1, -1) };
+  }
+  return { ok: false };
+}
+
+// Resolve a single-value path expression like `.`, `.a.b`, `.a[0].b`, `.[2]`.
+// Returns undefined for a missing path (jq yields null; we map missing->undefined
+// then callers coerce). Throws JqFilterError on malformed path syntax.
+function resolvePath(value, path) {
+  const trimmed = path.trim();
+  if (trimmed === "") {
+    // An empty path is never valid jq (no empty filter). Fail closed so
+    // malformed predicates like `select()` or `==5` don't pass as identity.
+    throw new JqFilterError("Empty path expression");
+  }
+  if (trimmed === ".") return value;
+  if (!trimmed.startsWith(".")) {
+    throw new JqFilterError(`Unsupported path (must start with '.'): ${path}`);
+  }
+  // Tokenize into .field and [index] steps.
+  const stepRe = /\.([A-Za-z_][A-Za-z0-9_]*)|\[(\d+)\]/g;
+  let cursor = value;
+  // Root index access (`.[N]`) starts with a leading '.' that is not part of any
+  // step token; consume it so the first `[N]` match aligns at the cursor.
+  let lastIndex = trimmed.startsWith(".[") ? 1 : 0;
+  stepRe.lastIndex = lastIndex;
+  let match;
+  let consumedAny = false;
+  while ((match = stepRe.exec(trimmed)) !== null) {
+    if (match.index !== lastIndex) {
+      throw new JqFilterError(`Unsupported path syntax near: ${trimmed.slice(lastIndex)}`);
+    }
+    lastIndex = stepRe.lastIndex;
+    consumedAny = true;
+    if (cursor === undefined || cursor === null) {
+      cursor = undefined;
+      continue;
+    }
+    if (match[1] !== undefined) {
+      cursor = typeof cursor === "object" && !Array.isArray(cursor) ? cursor[match[1]] : undefined;
+    } else {
+      const idx = Number(match[2]);
+      cursor = Array.isArray(cursor) ? cursor[idx] : undefined;
+    }
+  }
+  if (!consumedAny || lastIndex !== trimmed.length) {
+    throw new JqFilterError(`Unsupported path syntax: ${path}`);
+  }
+  return cursor;
+}
+
+function evaluatePredicate(value, predicate) {
+  const cmpRe = /^(.*?)(==|!=|<=|>=|<|>)(.*)$/;
+  const m = predicate.match(cmpRe);
+  if (!m) {
+    // Bare path => truthy test.
+    const resolved = resolvePath(value, predicate);
+    return resolved !== undefined && resolved !== null && resolved !== false;
+  }
+  const [, leftRaw, op, rightRaw] = m;
+  // jq maps a missing path to null; resolvePath yields undefined -> normalize.
+  const resolvedLeft = resolvePath(value, leftRaw);
+  const left = resolvedLeft === undefined ? null : resolvedLeft;
+  const lit = parseLiteral(rightRaw);
+  if (!lit.ok) {
+    throw new JqFilterError(`Unsupported predicate operand: ${rightRaw.trim()}`);
+  }
+  const right = lit.value;
+  switch (op) {
+    case "==":
+      return left === right;
+    case "!=":
+      return left !== right;
+    case "<":
+    case "<=":
+    case ">":
+    case ">=": {
+      // jq never coerces across types (number < string always); JS would. Fail
+      // closed when operand types differ so numeric-string fields don't misfire.
+      if (typeof left !== typeof right) {
+        throw new JqFilterError(`Cannot order-compare ${typeof left} and ${typeof right}`);
+      }
+      if (op === "<") return left < right;
+      if (op === "<=") return left <= right;
+      if (op === ">") return left > right;
+      return left >= right;
+    }
+    default:
+      throw new JqFilterError(`Unsupported operator: ${op}`);
+  }
+}
+
+// Apply one pipe stage to a stream (array of values), returning a new stream.
+function applyStage(stream, rawStage) {
+  const stage = rawStage.trim();
+  if (stage === "") {
+    throw new JqFilterError("Empty filter stage");
+  }
+  if (stage === "length") {
+    return stream.map((v) => {
+      if (Array.isArray(v) || typeof v === "string") return v.length;
+      if (v && typeof v === "object") return Object.keys(v).length;
+      throw new JqFilterError("length: input must be array, string, or object");
+    });
+  }
+  if (stage === "keys") {
+    return stream.map((v) => {
+      if (Array.isArray(v)) return v.map((_, i) => i);
+      if (v && typeof v === "object") return Object.keys(v).sort();
+      throw new JqFilterError("keys: input must be array or object");
+    });
+  }
+  const selectMatch = stage.match(/^select\((.*)\)$/);
+  if (selectMatch) {
+    return stream.filter((v) => evaluatePredicate(v, selectMatch[1]));
+  }
+  // Top-level comparison expression yields a boolean per input (e.g. .x=="y").
+  if (/(==|!=|<=|>=|<|>)/.test(stage)) {
+    return stream.map((v) => evaluatePredicate(v, stage));
+  }
+  // Iteration: a path ending in [] (incl. bare .[]).
+  if (stage === ".[]") {
+    return stream.flatMap((v) => iterate(v));
+  }
+  if (stage.endsWith("[]")) {
+    const base = stage.slice(0, -2);
+    return stream.flatMap((v) => iterate(resolvePath(v, base)));
+  }
+  // Plain path access (single value per input).
+  return stream.map((v) => resolvePath(v, stage));
+}
+
+function iterate(v) {
+  if (Array.isArray(v)) return v;
+  if (v && typeof v === "object") return Object.values(v);
+  throw new JqFilterError("Cannot iterate (.[]) over a non-array/object value");
+}
+
+// Split on top-level pipes, ignoring | inside quotes or parentheses.
+function splitPipes(filter) {
+  const parts = [];
+  let depth = 0;
+  let quote = null;
+  let current = "";
+  for (const ch of filter) {
+    if (quote) {
+      current += ch;
+      if (ch === quote) quote = null;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch;
+      current += ch;
+      continue;
+    }
+    if (ch === "(") depth += 1;
+    if (ch === ")") depth -= 1;
+    if (ch === "|" && depth === 0) {
+      parts.push(current);
+      current = "";
+      continue;
+    }
+    current += ch;
+  }
+  parts.push(current);
+  return parts;
+}
+
+// Evaluate a jq-subset filter against a value. Returns the jq "stream" (array of
+// result values). Throws JqFilterError on unsupported syntax.
+export function evaluateJqFilter(value, filter) {
+  if (typeof filter !== "string" || filter.trim() === "") {
+    throw new JqFilterError("Empty --jq filter");
+  }
+  let stream = [value];
+  for (const stage of splitPipes(filter)) {
+    stream = applyStage(stream, stage);
+  }
+  return stream;
+}
+
+// jq truthiness for --silent: matches `jq -e` exit semantics — the status is
+// based on the LAST output value (empty output is falsy; a value is truthy
+// unless it is null or false).
+function streamIsTruthy(stream) {
+  if (stream.length === 0) return false;
+  const last = stream[stream.length - 1];
+  return last !== null && last !== false && last !== undefined;
+}
+
+function renderJqStream(stream) {
+  // jq prints each value on its own line; single value => just that value.
+  return stream
+    .map((v) => (typeof v === "string" ? v : JSON.stringify(v ?? null)))
+    .join("\n");
+}
+
+// Standard option block to merge into a parseArgs `options` map so every script
+// exposes the same flags.
+export const JQ_OUTPUT_PARSE_OPTIONS = {
+  jq: { type: "string" },
+  silent: { type: "boolean", short: "s" },
+};
+
+// Shared USAGE fragment so every script documents the flags identically.
+export const JQ_OUTPUT_USAGE = `Output filtering:
+  --jq <filter>             Apply a jq-subset filter to the result and print it
+                            (field access, .[]/.[N], pipes, select(...), ==,!=,<,<=,>,>=, length, keys).
+                            Invalid filter fails closed (stderr + exit 2).
+  --silent, -s              Suppress stdout; map result to exit code only
+                            (0 = pass/truthy, 1 = fail/falsy). Composes with --jq as a predicate.`;
+
+// Apply --jq / --silent to a result object and emit. Returns the exit code the
+// CLI should use (0 success / truthy, 1 falsy or non-ok, 2 invalid filter).
+// Without jq/silent the result is printed verbatim as JSON (unchanged shape).
+//
+//   ok: success of the underlying result (defaults to result.ok !== false).
+export function emitResult(
+  result,
+  {
+    jq = undefined,
+    silent = false,
+    stdout = process.stdout,
+    stderr = process.stderr,
+    ok = result?.ok !== false,
+  } = {},
+) {
+  if (jq !== undefined) {
+    let stream;
+    try {
+      stream = evaluateJqFilter(result, jq);
+    } catch (error) {
+      if (error instanceof JqFilterError) {
+        // Fail closed, distinct from a clean "predicate false". Exit 2.
+        stderr.write(`${JSON.stringify({ ok: false, error: `--jq: ${error.message}` })}\n`);
+        return 2;
+      }
+      throw error;
+    }
+    if (silent) {
+      return streamIsTruthy(stream) ? 0 : 1;
+    }
+    stdout.write(`${renderJqStream(stream)}\n`);
+    return ok ? 0 : 1;
+  }
+  if (silent) {
+    return ok ? 0 : 1;
+  }
+  stdout.write(`${JSON.stringify(result)}\n`);
+  return ok ? 0 : 1;
+}

package/scripts/loop/_handoff-contract.mjs

@@ -28,6 +28,7 @@ const SUBAGENT_ACTIONS = new Set([
   "request_review",
   "rerequest_review",
   "run_pre_approval",
+  "run_ui_e2e",
 ]);
 function normalizeContractValue(value) {
   return typeof value === "string" ? value.trim().toLowerCase() : null;

package/scripts/loop/check-retro-tooling.mjs

@@ -0,0 +1,246 @@
+#!/usr/bin/env node
+/**
+ * check-retro-tooling
+ *
+ * Deterministic, dependency-free verifier for the internal-tooling-only rule
+ * (issue #982). Given a transcript of the shell commands the agent ran during a
+ * dev-loop run, it detects AGENT-LEVEL raw escape-hatch calls that should have
+ * gone through internal dev-loops tooling:
+ *   - `gh ...` (incl. `gh api`, `gh ... --jq`)
+ *   - `python` / `python3`
+ *   - `node -e` / `node --eval`
+ *
+ * These three are the same breach: reaching past the dev-loops tooling to read
+ * or parse tool output with a raw call. The verifier returns the list of
+ * violations so the retrospective author can record them in
+ * `behavioralReview.rawCallViolations` and set `behavioralReview.internalToolingOnly`.
+ *
+ * Input source (how the harness feeds it):
+ *   Newline-delimited shell commands — one top-level command per line — as the
+ *   agent actually invoked them. Pass via a file (`--transcript <path>`) or pipe
+ *   on stdin. Each line is one Bash-tool invocation's command string.
+ *
+ * ALLOWED (NOT a violation):
+ *   - dev-loops subcommands and `node scripts/....mjs` invocations. Those scripts
+ *     legitimately call gh/GraphQL/etc. internally — that IS the tooling.
+ *   - A small explicit allowlist of write-ops that have no internal wrapper today:
+ *     `gh pr merge`, `gh pr ready`, `gh issue create`, `gh issue edit`. These are
+ *     recorded as `allowedWriteOps` rather than violations so the gate is not
+ *     blocked forever on an unavoidable gap. Document/close the gap with a wrapper
+ *     to remove them from the allowlist.
+ *
+ * VIOLATION (agent-level raw call):
+ *   - `gh ...` at the start of a command segment (start of line, or after
+ *     `&&`, `||`, `|`, `;`) that is not in the write-op allowlist.
+ *   - `python` / `python3` at the start of a command segment.
+ *   - `node -e` / `node --eval` (inline eval) at the start of a command segment.
+ *
+ * Head normalization (before classifying a segment, fail-closed):
+ *   - strips leading `NAME=value ` env-assignment prefixes (`GH_TOKEN=x gh api`)
+ *   - strips a leading wrapper binary from {sudo, env, xargs, time, nice, command}
+ *     and re-classifies the remainder (`sudo gh api`, `xargs gh api`, `env gh api`)
+ *   - reduces a path-prefixed binary to its basename (`./node_modules/.bin/gh`,
+ *     `/usr/bin/python3`) so the real tool is matched.
+ *
+ * Known limitations (honest):
+ *   - Segment splitting is a simple top-level split on `&&`, `||`, `|`, `;` and
+ *     does NOT fully parse shell quoting/substitution. A `;`/`|` inside a quoted
+ *     argument can over-report (flags a harmless inner token). It catches the
+ *     common raw-call forms (incl. the env/wrapper/path-prefixed ones above), but
+ *     deeply obfuscated calls — command substitution `$(...)`, aliases, `eval` —
+ *     may evade it. Prefer single-line, single-purpose commands in transcripts.
+ */
+import { readFileSync } from "node:fs";
+import process from "node:process";
+import { parseArgs } from "node:util";
+import { isDirectCliRun } from "@dev-loops/core/cli/helpers";
+
+const USAGE = `Usage: node scripts/loop/check-retro-tooling.mjs [--transcript <path>] [--json]
+
+Reads a newline-delimited transcript of agent shell commands (from --transcript
+or stdin) and reports agent-level raw gh/python/node -e calls (internal-tooling-only
+rule, issue #982).
+
+Options:
+  --transcript <path>   File of newline-delimited commands (default: read stdin)
+  --json                Emit machine-readable JSON (default: human summary)
+
+Exit codes:
+  0  No violations
+  1  One or more violations found
+  2  Argument/runtime error`;
+
+/**
+ * Write-ops that currently have no internal dev-loops wrapper. Recorded
+ * distinctly so the gate is not blocked forever on an unavoidable gap.
+ * Keep this set SMALL and explicit; remove an entry once a wrapper exists.
+ * @type {ReadonlyArray<RegExp>}
+ */
+const ALLOWED_WRITE_OPS = Object.freeze([
+  /^gh\s+pr\s+merge\b/,
+  /^gh\s+pr\s+ready\b/,
+  /^gh\s+issue\s+create\b/,
+  /^gh\s+issue\s+edit\b/,
+]);
+
+/** Split a command line into top-level segments on &&, ||, |, ;. */
+function splitSegments(line) {
+  return line
+    .split(/&&|\|\||\||;/g)
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+}
+
+/** Wrapper binaries whose first argument is the real command to classify. */
+const WRAPPER_BINARIES = new Set(["sudo", "env", "xargs", "time", "nice", "command"]);
+
+/**
+ * Strip prefixes that hide the real command head, fail-closed (over-report is
+ * fine, under-report is the bug):
+ *   - leading `NAME=value ` env-assignment tokens (any number)
+ *   - leading wrapper binaries (`sudo`, `env`, `xargs`, ...) — recurse on the rest
+ *   - a path-prefixed binary (`./x/gh`, `/usr/bin/python3`) → reduce head to its basename
+ * Returns the segment with a bare, classifiable command head.
+ */
+function normalizeSegmentHead(segment) {
+  let s = segment.trim();
+  // (a) strip leading env-assignment tokens: NAME=value. The value may be
+  //   unquoted (`X=1`) or a single/double-quoted string that itself contains
+  //   spaces (`X="a b"`); match the quoted form first so the space inside the
+  //   quotes is not mistaken for the token separator (would under-report).
+  const ENV_ASSIGN = /^[A-Za-z_][A-Za-z0-9_]*=(?:"[^"]*"|'[^']*'|\S*)\s+(?=\S)/;
+  while (ENV_ASSIGN.test(s)) {
+    s = s.replace(ENV_ASSIGN, "");
+  }
+  // (c) reduce a path-prefixed head to its basename so `.../gh` → `gh`
+  s = s.replace(/^(\S*\/)([^/\s]+)/, "$2");
+  // (b) strip a leading wrapper binary, then re-normalize the remainder
+  const head = s.split(/\s+/, 1)[0];
+  if (WRAPPER_BINARIES.has(head)) {
+    const rest = s.slice(head.length).trim();
+    if (rest.length > 0) return normalizeSegmentHead(rest);
+  }
+  return s;
+}
+
+/**
+ * Classify a single command segment.
+ * @returns {{ kind: "violation"|"allowedWriteOp"|"clean", tool?: string }}
+ */
+function classifySegment(rawSegment) {
+  const segment = normalizeSegmentHead(rawSegment);
+  // `node scripts/....mjs` (or any script path) is allowed tooling; only inline
+  // eval forms are violations. Check node first so script invocations pass.
+  if (/^node\b/.test(segment)) {
+    // Inline eval (`-e`/`--eval`) is a violation only before the script path:
+    // once a non-flag token (the script) appears, a later `--eval` is just a
+    // script argument, not Node's inline-eval mode (avoids false positives).
+    const tokens = segment.split(/\s+/).slice(1);
+    for (const tok of tokens) {
+      if (tok === "-e" || tok === "--eval" || /^--eval=/.test(tok)) {
+        return { kind: "violation", tool: "node -e" };
+      }
+      if (!tok.startsWith("-")) break; // script path reached
+    }
+    return { kind: "clean" };
+  }
+  if (/^gh\b/.test(segment)) {
+    if (ALLOWED_WRITE_OPS.some((re) => re.test(segment))) {
+      return { kind: "allowedWriteOp", tool: "gh" };
+    }
+    return { kind: "violation", tool: "gh" };
+  }
+  if (/^python3?\b/.test(segment)) {
+    return { kind: "violation", tool: /^python3\b/.test(segment) ? "python3" : "python" };
+  }
+  return { kind: "clean" };
+}
+
+/**
+ * Analyze a transcript of newline-delimited shell commands.
+ *
+ * @param {string} transcript
+ * @returns {{ violations: string[], allowedWriteOps: string[], internalToolingOnly: boolean }}
+ */
+export function analyzeTranscript(transcript) {
+  const violations = [];
+  const allowedWriteOps = [];
+  const lines = String(transcript ?? "").split(/\r?\n/);
+  for (const raw of lines) {
+    const line = raw.trim();
+    if (line.length === 0 || line.startsWith("#")) continue;
+    for (const segment of splitSegments(line)) {
+      const result = classifySegment(segment);
+      if (result.kind === "violation") {
+        violations.push(`${result.tool}: ${segment}`);
+      } else if (result.kind === "allowedWriteOp") {
+        allowedWriteOps.push(segment);
+      }
+    }
+  }
+  return { violations, allowedWriteOps, internalToolingOnly: violations.length === 0 };
+}
+
+function parseCliArgs(argv) {
+  let values;
+  try {
+    ({ values } = parseArgs({
+      args: argv,
+      options: {
+        transcript: { type: "string" },
+        json: { type: "boolean" },
+        help: { type: "boolean", short: "h" },
+      },
+      strict: true,
+      allowPositionals: false,
+    }));
+  } catch (err) {
+    throw Object.assign(new Error(err instanceof Error ? err.message : String(err)), { usage: USAGE });
+  }
+  return values;
+}
+
+function readStdin() {
+  try {
+    return readFileSync(0, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+async function run(argv, { stdout, stderr }) {
+  const values = parseCliArgs(argv);
+  if (values.help) {
+    stdout.write(`${USAGE}\n`);
+    return 0;
+  }
+  const transcript = values.transcript
+    ? readFileSync(values.transcript, "utf8")
+    : readStdin();
+
+  const { violations, allowedWriteOps, internalToolingOnly } = analyzeTranscript(transcript);
+
+  if (values.json) {
+    stdout.write(`${JSON.stringify({ ok: internalToolingOnly, internalToolingOnly, rawCallViolations: violations, allowedWriteOps })}\n`);
+  } else if (internalToolingOnly) {
+    stdout.write(`internalToolingOnly: true — no agent-level raw gh/python/node -e calls found.\n`);
+    if (allowedWriteOps.length > 0) {
+      stdout.write(`Allowed write-ops (no wrapper yet): ${allowedWriteOps.length}\n`);
+    }
+  } else {
+    stderr.write(`internalToolingOnly: false — ${violations.length} raw-call violation(s):\n`);
+    for (const v of violations) stderr.write(`  - ${v}\n`);
+  }
+  return internalToolingOnly ? 0 : 1;
+}
+
+if (isDirectCliRun(import.meta.url)) {
+  run(process.argv.slice(2), { stdout: process.stdout, stderr: process.stderr }).then(
+    (code) => { process.exitCode = typeof code === "number" ? code : 0; },
+    (error) => {
+      const usage = error instanceof Error && typeof error.usage === "string" ? `\n${error.usage}` : "";
+      process.stderr.write(`${error instanceof Error ? error.message : String(error)}${usage}\n`);
+      process.exitCode = 2;
+    },
+  );
+}

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

@@ -17,6 +17,7 @@ import {
   enforceExternalHealthyWaitTimeout,
 } from "@dev-loops/core/loop/timeout-policy";
 import { parseArgs } from "node:util";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult } from "../lib/jq-output.mjs";
 import {
   DEFAULT_POLL_INTERVAL_MS,
   COPILOT_REVIEW_WAIT_TIMEOUT_MS,
@@ -69,9 +70,11 @@ Error output (stderr, JSON):
     { "ok": false, "error": "...", "usage": "..." }
   gh/runtime failures:
     { "ok": false, "error": "..." }
+${JQ_OUTPUT_USAGE}
 Exit codes:
   0  Success
-  1  Argument error or gh failure`.trim();
+  1  Argument error or gh failure
+  2  Invalid --jq filter`.trim();
 const WATCH_STATES = new Set([
   STATE.WAITING_FOR_COPILOT_REVIEW,
 ]);
@@ -134,6 +137,8 @@ export function parseHandoffCliArgs(argv, { cwd = process.cwd() } = {}) {
     repo: undefined,
     pr: undefined,
     watchStatus: undefined,
+    jq: undefined,
+    silent: false,
   };
   const { tokens } = parseArgs({
     args: [...argv],
@@ -142,6 +147,7 @@ export function parseHandoffCliArgs(argv, { cwd = process.cwd() } = {}) {
       repo: { type: "string" },
       pr: { type: "string" },
       "watch-status": { type: "string" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -177,6 +183,14 @@ export function parseHandoffCliArgs(argv, { cwd = process.cwd() } = {}) {
       options.watchStatus = watchStatus;
       continue;
     }
+    if (token.name === "jq") {
+      options.jq = requireTokenValue(token, parseError);
+      continue;
+    }
+    if (token.name === "silent") {
+      options.silent = true;
+      continue;
+    }
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (options.pr === undefined) {
@@ -519,10 +533,14 @@ export async function runCli(
     return;
   }
   const result = await runHandoff(options, { env, ghCommand });
-  stdout.write(`${JSON.stringify(result)}\n`);
+  return emitResult(result, { jq: options.jq, silent: options.silent, stdout });
 }
 if (isDirectCliRun(import.meta.url)) {
-  runCli().catch((error) => {
+  runCli().then((code) => {
+    if (typeof code === "number") {
+      process.exitCode = code;
+    }
+  }).catch((error) => {
     process.stderr.write(`${formatCliError(error)}\n`);
     process.exitCode = 1;
   });