@mmerterden/multi-agent-pipeline 20.28.0 → 20.30.0

package/pipeline/scripts/agent-guard.py

@@ -2,15 +2,18 @@
 """Decision core for agent-guard.sh (see that file for the hook contract).
 
 Reads the PreToolUse payload JSON on stdin and prints exactly one decision:
-  BLOCK_ATTRIB | BLOCK_FORCE | BLOCK_UNATTENDED<TAB>reason | BLOCK_PARSE | OK
+  BLOCK_ATTRIB | BLOCK_FORCE | BLOCK_NOVERIFY<TAB>reason | BLOCK_READONLY<TAB>reason |
+  BLOCK_UNATTENDED<TAB>reason | BLOCK_PARSE | ASK<TAB>hook-json |
+  DENY<TAB>reason | OK
 
 Never executes the command. shlex.split only tokenizes shell-like text; a
 `$(...)` in the command is a literal token, never a subshell. The processes it
 does start are read-only `git rev-parse` / `git diff --name-only` calls on a
 path, with argv and no shell.
 
-Attended (MULTI_AGENT_UNATTENDED unset): the attribution and force-push rules
-only, and any error prints OK (fail-open) so a guard bug cannot break a
+Attended (MULTI_AGENT_UNATTENDED unset): the attribution (argv and -F
+message files), force-push and hook-skipping rules, plus the confirmations in
+_guard_rules.ask_reason, and any error prints OK (fail-open) so a guard bug cannot break a
 legitimate tool call. Unattended: unattended_policy.py is consulted as well,
 and an error prints BLOCK_PARSE (fail-closed).
 """
@@ -22,6 +25,9 @@ import signal
 import sys
 import unicodedata
 
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import _guard_rules  # noqa: E402
+
 # An internal deadline well under the hook timeout: if the guard cannot decide
 # in this long, it prints the blocking verdict when unattended (fail-closed) and
 # the allow verdict when attended (a guard bug must not break legitimate work).
@@ -43,6 +49,7 @@ PROTECTED = {"main", "master", "develop"}
 REMOTES = {"origin", "upstream"}
 ATTRIBUTION = re.compile(
     r"co-authored-by:\s*(claude|anthropic|opus|sonnet|haiku|fable)"
+    r"|co-authored-by:[^\n]*\bcopilot\b"
     r"|noreply@anthropic\.com"
     r"|generated with\s+.*claude"
     r"|\U0001F916\s*generated"
@@ -276,16 +283,62 @@ def _nested_payload(toks: list):
     return None
 
 
+def _attributed(text: str) -> bool:
+    return bool(ATTRIBUTION.search(text) or ATTRIBUTION.search(normalize_for_match(text)))
+
+
+# The directory the hook payload names as the session's cwd; message files a
+# command names relative to it are read from there.
+PAYLOAD_CWD = {"dir": None}
+
+
+def _command_rules(cmd: str) -> str:
+    """Rules 1b, 3, 4 and 5, judged on the line's simple commands with heredoc
+    bodies removed and only where the program is the command word
+    (_guard_rules.command_segments / command_word). A `cd` moves later
+    segments into another directory."""
+    pending_ask = None
+    cwd = None
+    for seg, toks in _guard_rules.command_segments(cmd):
+        if toks and toks[0] in ("{", "}"):
+            toks = toks[1:]
+        if toks and toks[0] in ("cd", "pushd"):
+            cwd = _cd_target(toks, cwd)
+            continue
+        here = cwd or PAYLOAD_CWD["dir"]
+        # Rule 1b: the commit message given as a file (-F / --file).
+        for path in _guard_rules.message_files(toks):
+            if _attributed(_guard_rules.read_bounded(path, here)):
+                return "BLOCK_ATTRIB"
+        # Rule 5: history writes in a repository listed as read-only.
+        reason = _guard_rules.read_only_git_reason(toks, here)
+        if reason:
+            return "BLOCK_READONLY\t" + reason
+        # Rule 3: skipping the repository's git hooks.
+        reason = _guard_rules.no_verify(toks)
+        if reason:
+            return "BLOCK_NOVERIFY\t" + reason
+        # Rule 4: writes a person confirms (issue closure, Jira transition).
+        ask = _guard_rules.ask_reason(toks, seg, here)
+        if ask and not pending_ask:
+            pending_ask = "ASK\t" + ask
+    return pending_ask or "OK"
+
+
 def decide(cmd: str, depth: int = 0) -> str:
     low = cmd.lower()
     segs = segments(flatten(cmd))
 
-    # Rule 1: AI attribution inside a git commit.
+    # Rule 1: AI attribution inside a git commit, read from what the commit
+    # records (_guard_rules.commit_text), never from a neighbouring command.
     commits = re.search(r"git\s+commit", low) or any(
         git_subcommand(toks) == "commit" for _, toks in segs
     )
-    if commits and (ATTRIBUTION.search(cmd) or ATTRIBUTION.search(normalize_for_match(cmd))):
+    if commits and _attributed(_guard_rules.commit_text(cmd, PAYLOAD_CWD["dir"])):
         return "BLOCK_ATTRIB"
+    if commits and _guard_rules.ai_generated(cmd, PAYLOAD_CWD["dir"]):
+        return "BLOCK_ATTRIB"
+    pending_ask = None
 
     # Rule 2: force-push to a protected branch. Evaluate each push segment on its
     # own so a neighbouring command's flags cannot implicate it. A `cd` earlier
@@ -301,7 +354,9 @@ def decide(cmd: str, depth: int = 0) -> str:
         payload = _nested_payload(toks)
         if payload and depth < MAX_DEPTH:
             verdict = decide(payload, depth + 1)
-            if verdict != "OK":
+            if verdict.startswith("ASK"):
+                pending_ask = pending_ask or verdict
+            elif verdict != "OK":
                 return verdict
             continue
         if git_subcommand(toks) != "push" and not re.search(r"git\s+push", seg.lower()):
@@ -310,7 +365,12 @@ def decide(cmd: str, depth: int = 0) -> str:
         if verdict != "OK":
             return verdict
 
-    return "OK"
+    verdict = _command_rules(cmd)
+    if verdict.startswith("ASK"):
+        return pending_ask or verdict
+    if verdict != "OK":
+        return verdict
+    return pending_ask or "OK"
 
 
 def _cd_target(toks: list, cwd):
@@ -530,6 +590,46 @@ def fallback_verdict(text: str) -> str:
     return "OK"
 
 
+FILE_TOOLS = {"Edit", "Write", "NotebookEdit", "MultiEdit"}
+
+
+# Permission modes in which a hook's "ask" has no documented prompt to raise.
+# The hooks reference documents "ask" as forcing a prompt (and states it for
+# auto mode); it says nothing for bypassPermissions or dontAsk, where the
+# permission prompt is switched off. There the guard denies with the reason
+# and names the channel the user's answer travels through: the model asks,
+# confirm-command.mjs records a yes for that exact command (sha256, ten
+# minutes, one use), and the rerun finds it. Attended only: unattended, the
+# record is never read.
+NO_PROMPT_MODES = {"bypassPermissions", "dontAsk"}
+
+
+def ask_verdict(reason: str, data: dict, strict: bool) -> str:
+    """ASK<TAB>json for a prompt, DENY<TAB>reason where no prompt can be
+    raised, BLOCK_UNATTENDED<TAB>reason when nobody is there to answer."""
+    if strict:
+        return "BLOCK_UNATTENDED\t" + reason
+    if data.get("permission_mode") in NO_PROMPT_MODES:
+        # With prompts switched off the native ask cannot be raised, so the
+        # recorded confirmation stands in for it. In every other mode the
+        # prompt is the confirmation and a record must not skip it.
+        if _guard_rules.confirmed((data.get("tool_input") or {}).get("command", "")):
+            return "OK"
+        return (
+            "DENY\t" + reason + " (permission prompts are off in this mode: ask the user with AskUserQuestion; on yes, "
+            "record it with node \"$HOME/.claude/scripts/confirm-command.mjs\" --command '<the exact command>' "
+            "and run the command again, unchanged, within 10 minutes)"
+        )
+    out = {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "ask",
+            "permissionDecisionReason": "agent-guard: " + reason,
+        }
+    }
+    return "ASK\t" + json.dumps(out)
+
+
 def unattended() -> bool:
     """MULTI_AGENT_UNATTENDED=1 in the hook's own environment - the launcher's,
     never anything the run wrote (lib/unattended.sh ma_unattended)."""
@@ -687,9 +787,20 @@ def main() -> None:
     try:
         data = json.loads(seen["text"])
         cmd = (data.get("tool_input") or {}).get("command", "")
+        if isinstance(data.get("cwd"), str) and data.get("cwd"):
+            PAYLOAD_CWD["dir"] = data["cwd"]
         if isinstance(cmd, str):
             seen["text"], seen["raw"] = cmd, False
         verdict = decide(cmd) if isinstance(cmd, str) and cmd else "OK"
+        if verdict == "OK" and data.get("tool_name") in FILE_TOOLS:
+            ti = data.get("tool_input") or {}
+            reason = _guard_rules.read_only_file_reason(
+                ti.get("file_path") or ti.get("notebook_path") or "", PAYLOAD_CWD["dir"]
+            )
+            if reason:
+                verdict = "BLOCK_READONLY\t" + reason
+        if verdict.startswith("ASK"):
+            verdict = ask_verdict(verdict.split("\t", 1)[1], data, strict)
         if verdict == "OK" and strict:
             sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
             import unattended_policy

package/pipeline/scripts/agent-guard.sh

@@ -2,10 +2,20 @@
 # agent-guard.sh  -  PreToolUse guard for the multi-agent pipeline.
 #
 # Turns prompt-level rules into deterministic, OS-enforced gates:
-#   1. No AI/assistant attribution in git commit messages (Co-Authored-By: Claude,
-#      "Generated with Claude Code", robot emoji, Anthropic no-reply address).
+#   1. No AI/assistant attribution in git commit messages (Co-Authored-By: Claude
+#      or Copilot, "Generated with Claude Code", "Generated by AI", robot emoji,
+#      Anthropic no-reply address), on the command line or in a `-F` file.
 #   2. No force-push to a protected branch (main / master / develop), whichever
 #      remote, push options or `git -C` directory the push names.
+#   2b. No skipping the repository's git hooks (commit / push / merge with
+#      --no-verify, commit -n, -c core.hooksPath=...).
+#   2c. No literal credential on a Bash command line (argv-secret-scan.mjs).
+#   2e. No Edit / Write, git commit or git push inside a repository listed in
+#      prefs.global.readOnlyRepos (a reference checkout).
+#   2d. A person confirms (permissionDecision "ask") closing a GitHub issue, a
+#      PR body with Closes/Fixes/Resolves #N and a Jira transition POST. Where
+#      the permission mode raises no prompt (bypassPermissions, dontAsk) the
+#      call is denied with the reason instead; unattended it is blocked.
 #   3. With MULTI_AGENT_UNATTENDED=1 in the hook's environment only: no outward
 #      writes (push, PR, issue, tracker publishers, mutating API calls), no
 #      Keychain reads, no fetch outside the network allowlist, no package
@@ -15,7 +25,7 @@
 # Contract (Claude Code PreToolUse hook, matcher Bash and Edit|Write|NotebookEdit):
 #   - Reads the tool-call JSON on stdin: {"tool_name":..., "tool_input":{...}, "cwd":...}.
 #   - Exit 2  -> BLOCK the tool call (reason on stderr, shown to the model).
-#   - Exit 0  -> allow.
+#   - Exit 0  -> allow, or, with hook JSON on stdout, ask the user to confirm.
 #
 # Safety design:
 #   - The command string is ONLY parsed/pattern-matched, NEVER executed or eval'd
@@ -52,6 +62,27 @@ CUR_BRANCH="$(git rev-parse --abbrev-ref HEAD 2>/dev/null || true)"
 
 DECISION="$(printf '%s' "$PAYLOAD" | CUR_BRANCH="$CUR_BRANCH" python3 "$HELPER" 2>/dev/null || true)"
 
+# A literal credential on a Bash command line is refused before anything else
+# is said about the call (argv-secret-scan.mjs, the outbound gate's credential
+# shapes). Only rule names are printed, never the value.
+case "$DECISION" in
+  OK|ASK*|DENY*)
+    case "$PAYLOAD" in
+      *'"tool_name":"Bash"'*|*'"tool_name": "Bash"'*)
+        if command -v node >/dev/null 2>&1 && [ -f "$HERE/argv-secret-scan.mjs" ]; then
+          RULES="$(printf '%s' "$PAYLOAD" | node "$HERE/argv-secret-scan.mjs" 2>/dev/null)"
+          if [ "$?" = "7" ]; then
+            echo "BLOCKED by agent-guard: the command line carries a literal credential ($RULES)." >&2
+            echo "Read it from the credential store or an environment variable instead; a value typed" >&2
+            echo "into argv lands in the transcript, the process table and every log that echoes it." >&2
+            exit 2
+          fi
+        elif [ "$STRICT" = "1" ]; then
+          refuse_unjudged "node or argv-secret-scan.mjs is unavailable for the credential scan"
+        fi ;;
+    esac ;;
+esac
+
 case "$DECISION" in
   BLOCK_ATTRIB)
     echo "BLOCKED by agent-guard: the commit message carries AI/assistant attribution." >&2
@@ -62,6 +93,22 @@ case "$DECISION" in
     echo "BLOCKED by agent-guard: force-push to a protected branch (main/master/develop) is not allowed." >&2
     echo "Rewriting shared history is a data-loss risk. Push a normal commit, or force-push a feature branch." >&2
     exit 2 ;;
+  BLOCK_READONLY*)
+    echo "BLOCKED by agent-guard: ${DECISION#BLOCK_READONLY?}." >&2
+    echo "Read it, cite it and port the change to the repository you are working in." >&2
+    exit 2 ;;
+  BLOCK_NOVERIFY*)
+    echo "BLOCKED by agent-guard: ${DECISION#BLOCK_NOVERIFY?}." >&2
+    echo "The repository's own hooks (lint, tests, secret checks) are part of the commit contract." >&2
+    echo "Fix what they report and commit without skipping them." >&2
+    exit 2 ;;
+  ASK*)
+    # The hook JSON the host reads: permissionDecision "ask" forces a prompt.
+    printf '%s\n' "${DECISION#ASK?}"
+    exit 0 ;;
+  DENY*)
+    echo "BLOCKED by agent-guard: ${DECISION#DENY?}." >&2
+    exit 2 ;;
   BLOCK_UNATTENDED*)
     echo "BLOCKED by agent-guard (unattended policy): ${DECISION#BLOCK_UNATTENDED?}." >&2
     echo "This run has nobody watching it. Outward writes go through pr-request.json and the runner;" >&2

package/pipeline/scripts/argv-secret-scan.mjs

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+/**
+ * argv-secret-scan.mjs  -  a Bash command line that carries a literal
+ * credential is refused before it runs.
+ *
+ * agent-guard.sh pipes the PreToolUse payload here for every Bash call. A
+ * credential typed into a command line lands in the transcript, the shell
+ * history of whatever runs it, the process table and any log that echoes
+ * argv; the outbound gate (lib/outbound-gate.mjs) already knows the shapes, so
+ * its `certain` rules are applied to the command text.
+ *
+ * Three adjustments keep it to credentials that can leak:
+ *   - A credential URL to a local host (localhost, 127.x, ::1, *.local) or with
+ *     a placeholder pair (`postgres:postgres`, `user:pass`) is a dev DSN, not a
+ *     secret, and is removed before the scan (withoutLocalCredentials).
+ *   - Shell variable references (`$TOKEN`, `${TOKEN}`) and command
+ *     substitutions (`$(...)`) are removed before the scan. A command that
+ *     reads its secret from the environment or the credential store is the
+ *     correct way to do it, and a clone URL whose password part is
+ *     `${TOKEN}` must not read as a URL with credentials.
+ *   - Rules that match a marker rather than a value
+ *     (`service-account-json`, `private-key-block`) are skipped: grepping for
+ *     the marker is how an audit finds the leak.
+ *
+ * Output never contains the matched value, only rule names.
+ *
+ * Exit: 0 clean (or not a Bash payload), 7 a literal credential found,
+ * 2 the payload could not be read.
+ *
+ * @module pipeline/scripts/argv-secret-scan
+ */
+
+import { readFileSync } from "node:fs";
+
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+import { scan } from "../lib/outbound-gate.mjs";
+
+const MARKER_RULES = new Set(["service-account-json", "private-key-block"]);
+
+/** The command with variable references and substitutions removed. */
+export function withoutReferences(cmd) {
+  let out = String(cmd);
+  // Innermost substitutions first, until none are left.
+  for (let i = 0; i < 8 && /\$\([^()]*\)/.test(out); i++) out = out.replace(/\$\([^()]*\)/g, "");
+  out = out.replace(/`[^`]*`/g, "");
+  out = out.replace(/\$\{[^}]*\}/g, "");
+  out = out.replace(/\$[A-Za-z_][A-Za-z0-9_]*/g, "");
+  return out;
+}
+
+const URL_CREDS = /\b([a-z][a-z0-9+.-]*:\/\/)([^\s/:@]+):([^\s/@]+)@(\[[^\]\s]+\]|[^\s/:?#'"]+)/gi;
+const LOCAL_HOST =
+  /^(?:localhost|127(?:\.\d{1,3}){3}|0\.0\.0\.0|\[::1\]|::1|[\w.-]+\.(?:local|localhost|test|example|invalid))$/i;
+const PLACEHOLDERS = new Set([
+  "user",
+  "username",
+  "pass",
+  "password",
+  "secret",
+  "postgres",
+  "root",
+  "admin",
+  "test",
+  "example",
+  "changeme",
+  "default",
+]);
+
+/**
+ * The command with credentials removed from URLs that cannot leak anything:
+ * a local host (a dev database DSN), or a placeholder pair (`user:pass`,
+ * `postgres:postgres`). A credential URL to any other host is left for the
+ * scan.
+ */
+export function withoutLocalCredentials(cmd) {
+  return String(cmd).replace(URL_CREDS, (all, scheme, user, pass, host) => {
+    const placeholder =
+      user === pass ||
+      (PLACEHOLDERS.has(user.toLowerCase()) && PLACEHOLDERS.has(pass.toLowerCase()));
+    return LOCAL_HOST.test(host) || placeholder ? `${scheme}${host}` : all;
+  });
+}
+
+/**
+ * Names of the credential rules a command line matches.
+ *
+ * @param {string} cmd
+ * @returns {string[]}
+ */
+export function literalSecrets(cmd) {
+  if (typeof cmd !== "string" || !cmd) return [];
+  const found = scan(withoutLocalCredentials(withoutReferences(cmd))).filter(
+    (f) => f.certain && !MARKER_RULES.has(f.rule),
+  );
+  return [...new Set(found.map((f) => f.rule))];
+}
+
+function main() {
+  let payload;
+  try {
+    payload = JSON.parse(readFileSync(0, "utf8"));
+  } catch {
+    process.exitCode = 2;
+    return;
+  }
+  if (payload?.tool_name !== "Bash") return;
+  const rules = literalSecrets(payload?.tool_input?.command);
+  if (rules.length) {
+    process.stdout.write(`${rules.join(", ")}\n`);
+    process.exitCode = 7;
+  }
+}
+
+if (invokedDirectly(import.meta.url)) main();

package/pipeline/scripts/autopilot-control.mjs

@@ -16,8 +16,17 @@
  *               under `autopilot/abandoned/<task-id>` and kept, a clean one is
  *               removed. Without --now nothing in flight is touched.
  *
- * Turning the mode on stays /multi-agent:autopilot-on: it picks repositories
- * with the user.
+ *   on --repo <owner/name>... [--configure-only]
+ *               the writing half of /multi-agent:autopilot-on, for a selection
+ *               already made: config.json keeps exactly the selected repos
+ *               (each must already be configured; adding a new one, with its
+ *               sources and label, stays the terminal picker), every
+ *               credential the result needs is probed (autopilot-arming.mjs
+ *               probeCredentials), and unless --configure-only or a probe
+ *               fails, the schedule plist is rendered and loaded and the awake
+ *               agent installed. An empty selection is refused.
+ *   on-preview --repo <owner/name>...
+ *               what `on` would keep, drop and probe, writing nothing.
  *
  * Injectable for tests: MA_AUTOPILOT_ROOT, MA_AUTOPILOT_LABEL,
  * MA_AUTOPILOT_PLIST, MA_AP_LAUNCH_AGENTS, MA_AP_LAUNCHCTL_BIN,
@@ -26,14 +35,28 @@
  * Usage:
  *   node autopilot-control.mjs status
  *   node autopilot-control.mjs off [--now]
+ *   node autopilot-control.mjs on --repo <owner/name>... [--configure-only]
+ *   node autopilot-control.mjs on-preview --repo <owner/name>...
  *
- * Exit: 0 done, 2 usage, 3 status could not be built.
+ * With MA_CONTROL_JSON_ERRORS=1 a refusal is also printed on stdout as
+ * {error: {code, message}}, for contract-server.mjs, which runs this script
+ * as a child process.
+ *
+ * Exit: 0 done, 1 `on` refused, 2 usage, 3 status could not be built.
  *
  * @module pipeline/scripts/autopilot-control
  */
 
 import { execFileSync, spawnSync } from "node:child_process";
-import { existsSync, readFileSync, rmSync } from "node:fs";
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -45,7 +68,9 @@ import {
   sessionIsLive,
   stashWorktree,
 } from "./autopilot-runner.mjs";
-import { removeAwake } from "./autopilot-awake.mjs";
+import { installAwake, removeAwake } from "./autopilot-awake.mjs";
+import { probeCredentials } from "./autopilot-arming.mjs";
+import { configRefusal } from "./_autopilot-config.mjs";
 import { updateState } from "./gate-ledger.mjs";
 import { autopilotRoot } from "../lib/pr-request-location.mjs";
 import { runMain } from "../lib/fatal.mjs";
@@ -55,7 +80,12 @@ export const CONTRACT_VERSION = "1.0.0";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 
-export class ControlError extends Error {}
+export class ControlError extends Error {
+  constructor(message, code = "internal") {
+    super(message);
+    this.code = code;
+  }
+}
 
 function readJson(path, fallback) {
   try {
@@ -196,6 +226,155 @@ export async function autopilotOff({ now = false, env = process.env } = {}) {
   return { enabled: false, stoppedInFlight };
 }
 
+const SCHEDULE_TEMPLATE = "multi-agent-autopilot.plist.template";
+
+/** The installed tree keeps templates/ beside scripts/; the repo keeps it in install/. */
+function scheduleTemplate(env) {
+  const home = env.HOME || homedir();
+  return (
+    [
+      env.MA_AP_SCHEDULE_TEMPLATE,
+      join(HERE, "..", "templates", SCHEDULE_TEMPLATE),
+      join(HERE, "..", "..", "install", "templates", SCHEDULE_TEMPLATE),
+      ...[".claude", ".copilot", ".codex"].map((d) =>
+        join(home, d, "templates", SCHEDULE_TEMPLATE),
+      ),
+    ]
+      .filter(Boolean)
+      .find((p) => existsSync(p)) ?? null
+  );
+}
+
+const xml = (v) => String(v).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+
+function which(bin, env) {
+  const r = spawnSync("/bin/sh", ["-c", `command -v ${bin}`], {
+    env,
+    encoding: "utf8",
+    timeout: 5000,
+  });
+  return r.status === 0 ? r.stdout.trim() : "";
+}
+
+/** The schedule plist, rendered with the seven placeholders autopilot-on fills. */
+export function renderSchedule(config, env = process.env) {
+  const tpl = scheduleTemplate(env);
+  if (!tpl)
+    throw new ControlError(
+      `${SCHEDULE_TEMPLATE} is not installed - re-run the installer`,
+      "not-installed",
+    );
+  const home = env.HOME || homedir();
+  const values = {
+    NODE: env.MA_AP_NODE_BIN || process.execPath,
+    TICK: join(HERE, "autopilot-runner.mjs"),
+    LABEL: env.MA_AUTOPILOT_LABEL || "com.multi-agent.autopilot",
+    ROOT: autopilotRoot(env),
+    INTERVAL: Number.isInteger(config?.scanIntervalSeconds) ? config.scanIntervalSeconds : 120,
+    HOME: home,
+    CLAUDE: env.MA_AP_CLAUDE_BIN || which("claude", env),
+  };
+  return readFileSync(tpl, "utf8").replace(/\{\{([A-Z]+)\}\}/g, (m, k) =>
+    k in values ? xml(values[k]) : m,
+  );
+}
+
+function readPrefs(env) {
+  const path =
+    env.MULTI_AGENT_PREFS ||
+    env.MA_PREFS_FILE ||
+    join(env.HOME || homedir(), ".claude", "multi-agent-preferences.json");
+  return readJson(path, {});
+}
+
+/**
+ * What `on` would do for a selection: the config it writes and the probe of
+ * every credential that config needs. Writes nothing.
+ *
+ * @param {{repos: string[], env?: object}} opts  nameWithOwner of each selected repo
+ */
+export function autopilotOnPlan({ repos, env = process.env }) {
+  const selected = [...new Set(Array.isArray(repos) ? repos : [])];
+  if (!selected.length) {
+    throw new ControlError(
+      "no repository selected; autopilot is never turned on without one",
+      "no-selection",
+    );
+  }
+  const root = autopilotRoot(env);
+  const config = readJson(join(root, "config.json"), null);
+  const configured = Array.isArray(config?.repos) ? config.repos : [];
+  const names = configured.map((r) => r?.nameWithOwner);
+  const missing = selected.filter((n) => !names.includes(n));
+  if (missing.length) {
+    throw new ControlError(
+      `not configured yet: ${missing.join(", ")} - add a repository with /multi-agent:autopilot-on in a terminal, which asks its sources and label`,
+      "repo-not-configured",
+    );
+  }
+  const next = { ...config, repos: configured.filter((r) => selected.includes(r?.nameWithOwner)) };
+  const refusal = configRefusal(next);
+  if (refusal) throw new ControlError(refusal, "invalid-config");
+  const probe = probeCredentials({ config: next, prefs: readPrefs(env), env });
+  return {
+    config: next,
+    keep: selected,
+    drop: names.filter((n) => !selected.includes(n)),
+    probe: {
+      ready: probe.ready,
+      problems: probe.problems.map((p) => p.message),
+      warnings: probe.warnings,
+    },
+  };
+}
+
+/**
+ * Turn continuous mode on for a selection of configured repositories.
+ *
+ * @param {{repos: string[], configureOnly?: boolean, env?: object}} opts
+ * @returns {{enabled: boolean, scheduled: boolean, repos: string[], dropped: string[],
+ *   probe: {ready: boolean, problems: string[], warnings: string[]}, awake: boolean|null}}
+ */
+export function autopilotOn({ repos, configureOnly = false, env = process.env }) {
+  const plan = autopilotOnPlan({ repos, env });
+  const root = autopilotRoot(env);
+  mkdirSync(root, { recursive: true, mode: 0o700 });
+  const file = join(root, "config.json");
+  const tmp = join(root, `.config.json.${process.pid}`);
+  writeFileSync(tmp, JSON.stringify(plan.config, null, 2) + "\n", { mode: 0o600 });
+  chmodSync(tmp, 0o600);
+  renameSync(tmp, file);
+  const base = { repos: plan.keep, dropped: plan.drop, probe: plan.probe };
+  if (configureOnly || !plan.probe.ready) {
+    return { enabled: false, scheduled: false, awake: null, ...base };
+  }
+  const label = env.MA_AUTOPILOT_LABEL || "com.multi-agent.autopilot";
+  const agents = env.MA_AP_LAUNCH_AGENTS || join(env.HOME || homedir(), "Library", "LaunchAgents");
+  const plist = env.MA_AUTOPILOT_PLIST || join(agents, `${label}.plist`);
+  mkdirSync(agents, { recursive: true });
+  const ptmp = `${plist}.${process.pid}.tmp`;
+  writeFileSync(ptmp, renderSchedule(plan.config, env), { mode: 0o644 });
+  renameSync(ptmp, plist);
+  const loaded =
+    launchctl(["bootstrap", `gui/${process.getuid()}`, plist], env) ||
+    launchctl(["load", plist], env);
+  if (!loaded) {
+    throw new ControlError("launchd refused the schedule plist", "launchd-refused");
+  }
+  const awake = installAwake({ env });
+  return { enabled: true, scheduled: true, awake: awake.loaded, ...base };
+}
+
+function refuse(err, code) {
+  process.stderr.write(`autopilot-control: ${err.message}\n`);
+  if (process.env.MA_CONTROL_JSON_ERRORS === "1") {
+    process.stdout.write(
+      `${JSON.stringify({ error: { code: err.code, message: err.message } })}\n`,
+    );
+  }
+  return code;
+}
+
 async function main(argv) {
   const [mode, ...rest] = argv;
   if (mode === "status" && !rest.length) {
@@ -203,8 +382,8 @@ async function main(argv) {
       process.stdout.write(`${JSON.stringify(autopilotStatus())}\n`);
       return 0;
     } catch (err) {
-      process.stderr.write(`autopilot-control: ${err.message}\n`);
-      return 3;
+      if (!(err instanceof ControlError)) throw err;
+      return refuse(err, 3);
     }
   }
   if (mode === "off" && rest.every((a) => a === "--now")) {
@@ -212,7 +391,33 @@ async function main(argv) {
     process.stdout.write(`${JSON.stringify(out)}\n`);
     return 0;
   }
-  process.stderr.write("usage: autopilot-control.mjs status | off [--now]\n");
+  if (mode === "on" || mode === "on-preview") {
+    const repos = [];
+    let configureOnly = false;
+    for (let i = 0; i < rest.length; i++) {
+      if (rest[i] === "--repo" && rest[i + 1]) repos.push(rest[++i]);
+      else if (rest[i] === "--configure-only" && mode === "on") configureOnly = true;
+      else return usage();
+    }
+    try {
+      const out =
+        mode === "on"
+          ? autopilotOn({ repos, configureOnly })
+          : (({ config: _c, ...plan }) => plan)(autopilotOnPlan({ repos }));
+      process.stdout.write(`${JSON.stringify(out)}\n`);
+      return 0;
+    } catch (err) {
+      if (!(err instanceof ControlError)) throw err;
+      return refuse(err, 1);
+    }
+  }
+  return usage();
+}
+
+function usage() {
+  process.stderr.write(
+    "usage: autopilot-control.mjs status | off [--now] | on --repo <owner/name>... [--configure-only] | on-preview --repo <owner/name>...\n",
+  );
   return 2;
 }