@mmerterden/multi-agent-pipeline 20.2.0 → 20.3.0

package/pipeline/scripts/launch-request.mjs

@@ -0,0 +1,747 @@
+#!/usr/bin/env node
+/**
+ * @file launch-request.mjs  -  validate a launch request and turn it into the
+ * pickers Phase 0 may skip.
+ *
+ * A client that wants a run started without a terminal conversation writes a
+ * request file (launch-request.schema.json) and sets MA_LAUNCH_REQUEST to its
+ * path. Phase 0 Step 0.1 calls `resolve`; each answer then stands in for the
+ * picker run-questions.json names, and every other picker asks as it always did.
+ *
+ * With MA_LAUNCH_REQUEST unset the answer is `present: false` with an empty
+ * prefill and an empty state patch, so an interactive run writes nothing it did
+ * not write before. A variable naming a file that does not exist is the same
+ * answer plus a warning: the terminal path is the safe fallback, and a request
+ * nobody can read has no answers to apply.
+ *
+ * A request that IS present and wrong is rejected whole - exit 1, nothing
+ * pre-filled. Half-applying one would ask some questions and silently answer
+ * others with values nobody validated. The rules, beyond the schema:
+ *
+ *   - every answered id exists in run-questions.json and is answerable;
+ *   - a static question takes one of its option ids, a run-time-enumerated one
+ *     a value matching its `answer.pattern`, multi-select an array of them;
+ *   - `disabled-when` is enforced: `workspace: local` under `mode: autopilot`
+ *     is rejected, and so is `workspace: local` when `--repo` names a working
+ *     tree with uncommitted changes (Step 6b would check out a new branch over
+ *     them). Without `--repo` the tree is reported `unchecked`, and Phase 0
+ *     re-runs `resolve --repo "$PROJECT_ROOT"` at Step 5b before applying it.
+ *
+ * Answers are data. Nothing here or in Phase 0 reads an answer as an
+ * instruction: an answer selects an option, and a value that is not an option
+ * never reaches a picker.
+ *
+ * The input is data too, and it lands in the prompt of a session started with
+ * no permission prompts, so it is held to a shape instead of passed through:
+ *
+ *   - a structured reference: a Jira key, a GitHub issue URL
+ *     (https://github.com/<owner>/<repo>/issues/<n>), repo#N, #N, or a Jira
+ *     URL on the configured Jira host (prefs global.hosts.jira). It reaches
+ *     the prompt as it is;
+ *   - free text, on the desktop channel only (the bearer route, the CLI, and a
+ *     request file Phase 0 reads): one line of at most FREE_TEXT_MAX printable
+ *     characters, no quote, backslash or backtick, reaching the prompt as one
+ *     double-quoted argument so the dispatcher reads it as a task description.
+ *     The phone channel takes structured references only.
+ *
+ * Either way a newline, a control or format character, a leading "-", a token
+ * that looks like a flag, and a first token that names a pipeline op or a mode
+ * keyword is refused. Only the first token is held to the reserved words: free
+ * text reaches the prompt as one quoted argument, so a later word cannot route,
+ * and a structured reference is a single token. The op names are the command
+ * tree's ids plus the words the dispatcher's routing table routes on; the mode
+ * keywords are the modes in phases.json and launch.json, the request modes and
+ * the workspace options. Both are read from that data, never listed here. A command tree
+ * that cannot be read refuses free text rather than guessing.
+ *
+ * A launch names its working directory, and only a configured autopilot repo
+ * (config.json repos[].localPath) or one the desktop client registered with
+ * `register-repo` (launch-repos.json under the autopilot root) is accepted,
+ * compared by real path.
+ *
+ * Zero runtime dependencies (ADR-0004); the schema checks are hand-written and
+ * test/launch-request.test.mjs holds them to launch-request.schema.json.
+ *
+ * `plan` is the other half, for a client that starts the run itself: the argv,
+ * environment and working directory launch.json declares for the request's
+ * mode, with every placeholder filled. It only prints; nothing here spawns a
+ * host. `questions` and `spec` print run-questions.json and launch.json as the
+ * contract carries them, so a client reads the same bytes from the CLI as from
+ * contract-server.mjs.
+ *
+ * Usage:
+ *   node launch-request.mjs validate <file> [--repo <path>]
+ *   node launch-request.mjs resolve [<file>] [--repo <path>]   # file defaults to $MA_LAUNCH_REQUEST
+ *   node launch-request.mjs plan <file> --repo <path> --session-id <uuid> [--channel desktop|phone] [--redact]
+ *   node launch-request.mjs questions
+ *   node launch-request.mjs spec
+ *   node launch-request.mjs register-repo <absolute path>
+ *
+ * Output: one JSON object on stdout, always carrying contractVersion.
+ * Exit: 0 valid or absent, 1 invalid, 2 usage error, 3 register-repo from an
+ * unattended run.
+ *
+ * @module pipeline/scripts/launch-request
+ */
+
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  realpathSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { spawnSync } from "node:child_process";
+import { homedir } from "node:os";
+import { isAbsolute, join } from "node:path";
+import { catalog, commandsDir } from "./commands.mjs";
+import { runMain } from "../lib/fatal.mjs";
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+import { autopilotRoot, unattendedLogsRoot } from "../lib/pr-request-location.mjs";
+import { lockTimeoutFrom, updateJsonFileSync } from "../lib/json-file-lock.mjs";
+import { unattendedSettingsPath } from "../lib/unattended-settings-location.mjs";
+import { isUnattended } from "../lib/unattended.mjs";
+
+export const CONTRACT_VERSION = "1.0.0";
+export const MODES = ["interactive", "autopilot"];
+const TOP_KEYS = ["contractVersion", "input", "mode", "answers"];
+
+const readSchemaJson = (name) =>
+  JSON.parse(readFileSync(new URL(`../schemas/${name}`, import.meta.url), "utf8"));
+
+/** run-questions.json, as the `questions` subcommand prints it. */
+export function questionsDocument() {
+  return readSchemaJson("run-questions.json");
+}
+
+/** launch.json, as the `spec` subcommand prints it. */
+export function launchSpec() {
+  return readSchemaJson("launch.json");
+}
+
+export function loadQuestions() {
+  return questionsDocument().questions;
+}
+
+/**
+ * `clean`, `dirty`, or `unreadable` for a working tree. Unreadable counts as
+ * dirty wherever it matters: a tree git cannot describe is not one to check a
+ * branch out over.
+ */
+export function workingTreeState(repo) {
+  const r = spawnSync("git", ["-C", repo, "status", "--porcelain"], {
+    encoding: "utf8",
+    timeout: 10000,
+  });
+  if (r.status !== 0) return "unreadable";
+  return r.stdout.trim() === "" ? "clean" : "dirty";
+}
+
+const isString = (v, max) => typeof v === "string" && v.length >= 1 && v.length <= max;
+
+export const CHANNELS = ["desktop", "phone"];
+export const FREE_TEXT_MAX = 500;
+const JIRA_KEY = /^[A-Z][A-Z0-9]+-[0-9]+$/;
+const GITHUB_ISSUE_URL =
+  /^https:\/\/github\.com\/[A-Za-z0-9][A-Za-z0-9-]{0,38}\/([A-Za-z0-9._-]{1,100})\/issues\/[1-9][0-9]{0,9}$/;
+const REPO_ISSUE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}#[1-9][0-9]{0,9}$/;
+const ISSUE_NUMBER = /^#[1-9][0-9]{0,9}$/;
+const JIRA_URL = /^https:\/\/([A-Za-z0-9.-]+(?::[0-9]{1,5})?)\/browse\/([A-Z][A-Z0-9]+-[0-9]+)$/;
+const UNSAFE_CHAR = /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}"\\`]/u;
+const FLAG_TOKEN = /^-/;
+
+const normalizeHost = (h) =>
+  String(h ?? "")
+    .trim()
+    .toLowerCase()
+    .replace(/^https?:\/\//, "")
+    .replace(/\/.*$/, "")
+    .replace(/:.*$/, "")
+    .replace(/\.$/, "");
+
+/** The configured Jira host from prefs, normalized, or "" when there is none. */
+export function configuredJiraHost(env = process.env) {
+  const file = env.MA_PREFS_FILE || join(homedir(), ".claude", "multi-agent-preferences.json");
+  try {
+    return normalizeHost(JSON.parse(readFileSync(file, "utf8"))?.global?.hosts?.jira);
+  } catch {
+    return "";
+  }
+}
+
+/** The words the dispatcher's routing table routes on: the first word of each row's pattern. */
+function routingWords(dir) {
+  try {
+    const text = readFileSync(join(dir, "SKILL.md"), "utf8");
+    const start = text.indexOf("\n## Routing");
+    if (start === -1) return [];
+    const end = text.indexOf("\n## ", start + 1);
+    const section = text.slice(start, end === -1 ? undefined : end);
+    const words = [];
+    for (const line of section.split("\n")) {
+      const cell = /^\|\s*([^|]*)\|/.exec(line)?.[1] ?? "";
+      for (const m of cell.matchAll(/`([a-z][a-z0-9-]*)(?=[\s`[])/g)) words.push(m[1]);
+    }
+    return words;
+  } catch {
+    return [];
+  }
+}
+
+let reservedCache = null;
+
+/**
+ * The op names and mode keywords an input may not contain, read from the
+ * command tree, the dispatcher, phases.json, launch.json and run-questions.json.
+ * `ops` is null when the command tree cannot be read.
+ */
+export function reservedWords({ questions, spec } = {}) {
+  if (!questions && !spec && reservedCache) return reservedCache;
+  const words = computeReservedWords(questions ?? loadQuestions(), spec ?? launchSpec());
+  if (!questions && !spec) reservedCache = words;
+  return words;
+}
+
+function computeReservedWords(questions, spec) {
+  const dir = commandsDir();
+  const cat = catalog();
+  const ops = cat && dir ? new Set([...cat.commands.map((c) => c.id), ...routingWords(dir)]) : null;
+  const modes = new Set([
+    ...MODES,
+    ...Object.keys(readSchemaJson("phases.json").modes ?? {}),
+    ...Object.values(spec.hosts ?? {}).flatMap((h) => Object.keys(h.modes ?? {})),
+    ...(questions.find((q) => q.id === "workspace")?.options ?? []).map((o) => o.id),
+  ]);
+  return { ops, modes };
+}
+
+/**
+ * Which structured reference an input is, or null when it is none of them.
+ * A Jira URL counts only on `jiraHost`.
+ */
+export function structuredKind(input, jiraHost = "") {
+  if (typeof input !== "string") return null;
+  if (JIRA_KEY.test(input)) return "jira-id";
+  const gh = GITHUB_ISSUE_URL.exec(input);
+  if (gh) return /^\.+$/.test(gh[1]) ? null : "gh-url";
+  if (REPO_ISSUE.test(input)) return "gh-short";
+  if (ISSUE_NUMBER.test(input)) return "gh-num";
+  const jira = JIRA_URL.exec(input);
+  if (jira && jiraHost && normalizeHost(jira[1]) === normalizeHost(jiraHost)) return "jira-url";
+  return null;
+}
+
+/**
+ * Every reason `input` may not start a run on `channel`. Pure apart from the
+ * reserved words, which are handed in.
+ */
+export function inputErrors(input, { channel = "desktop", jiraHost = "", reserved } = {}) {
+  if (!isString(input, 4000))
+    return ["input must be a non-empty string of at most 4000 characters"];
+  const errors = [];
+  if (UNSAFE_CHAR.test(input)) {
+    errors.push(
+      "input may not carry a newline, a control or format character, a quote, a backslash or a backtick",
+    );
+  }
+  if (FLAG_TOKEN.test(input)) errors.push('input may not start with "-"');
+  const { ops, modes } = reserved ?? reservedWords();
+  const tokens = input.split(/\s+/).filter(Boolean);
+  for (const raw of tokens) {
+    if (FLAG_TOKEN.test(raw) && raw !== input) errors.push(`input may not carry a flag (${raw})`);
+  }
+  const first = (tokens[0] ?? "").toLowerCase().replace(/^[^a-z0-9-]+|[^a-z0-9-]+$/g, "");
+  if (ops?.has(first)) errors.push(`input may not start with the pipeline op "${first}"`);
+  if (modes.has(first)) errors.push(`input may not start with the mode keyword "${first}"`);
+  if (errors.length) return [...new Set(errors)];
+  if (structuredKind(input, jiraHost)) return [];
+  if (channel === "phone") {
+    return [
+      "the phone channel takes a structured input only: a Jira key, a GitHub issue URL, repo#N, #N, or a Jira URL on the configured host",
+    ];
+  }
+  if (!ops) return ["free text cannot be checked without the command tree; use a structured input"];
+  if (input.length > FREE_TEXT_MAX) return [`free text is at most ${FREE_TEXT_MAX} characters`];
+  if (input.trim() !== input || /^[/#]/.test(input) || !/\p{L}/u.test(input)) {
+    return ["free text is a task description: no leading or trailing space, no leading / or #"];
+  }
+  if (!/\s/.test(input)) {
+    return ["a single word that is not a structured reference is refused; free text is a sentence"];
+  }
+  if (/[a-z][a-z0-9+.-]*:\/\//i.test(input)) {
+    return ["free text may not carry a URL; a GitHub or Jira link is sent as the whole input"];
+  }
+  return [];
+}
+
+/** The input as the prompt receives it: a structured reference as is, free text quoted. */
+export function promptArgument(input, jiraHost = "") {
+  return structuredKind(input, jiraHost) ? input : `"${input}"`;
+}
+
+/**
+ * Every reason a request is not acceptable. Pure: the working-tree state is
+ * handed in, so the rule is testable without a repository.
+ *
+ * @param {unknown} req
+ * @param {{questions?: object[], workingTree?: "clean"|"dirty"|"unreadable"|"unchecked",
+ *   channel?: "desktop"|"phone", jiraHost?: string}} [opts]
+ * @returns {string[]}
+ */
+export function validateRequest(req, opts = {}) {
+  const questions = opts.questions ?? loadQuestions();
+  const workingTree = opts.workingTree ?? "unchecked";
+  const channel = opts.channel ?? "desktop";
+  const jiraHost = opts.jiraHost ?? configuredJiraHost();
+  const errors = [];
+  if (!req || typeof req !== "object" || Array.isArray(req))
+    return ["request is not a JSON object"];
+
+  for (const k of Object.keys(req)) {
+    if (!TOP_KEYS.includes(k)) errors.push(`unknown field ${k}`);
+  }
+  if (typeof req.contractVersion !== "string" || !/^1\.[0-9]+\.[0-9]+$/.test(req.contractVersion)) {
+    errors.push(`contractVersion must be 1.x.y (this pipeline speaks ${CONTRACT_VERSION})`);
+  }
+  if (!CHANNELS.includes(channel)) errors.push(`channel must be ${CHANNELS.join(" | ")}`);
+  else errors.push(...inputErrors(req.input, { channel, jiraHost, reserved: opts.reserved }));
+  if (!MODES.includes(req.mode)) errors.push(`mode must be ${MODES.join(" | ")}`);
+  const answers = req.answers;
+  if (!answers || typeof answers !== "object" || Array.isArray(answers)) {
+    errors.push("answers must be an object");
+    return errors;
+  }
+
+  const byId = new Map(questions.map((q) => [q.id, q]));
+  for (const [id, value] of Object.entries(answers)) {
+    const q = byId.get(id);
+    if (!q) {
+      errors.push(`answers.${id}: no such question in run-questions.json`);
+      continue;
+    }
+    if (!q.answerable) {
+      errors.push(`answers.${id}: this question is always asked and cannot be pre-filled`);
+      continue;
+    }
+    const multi = q.kind === "multi-select";
+    const values = multi ? value : [value];
+    if (multi && !Array.isArray(value)) {
+      errors.push(`answers.${id}: a multi-select answer is an array`);
+      continue;
+    }
+    if (!multi && typeof value !== "string") {
+      errors.push(`answers.${id}: a single-select answer is one string`);
+      continue;
+    }
+    for (const v of values) {
+      if (!isString(v, 200)) {
+        errors.push(`answers.${id}: every value is a non-empty string of at most 200 characters`);
+      } else if (q.options && !q.options.some((o) => o.id === v)) {
+        errors.push(`answers.${id}: "${v}" is not one of ${q.options.map((o) => o.id).join(", ")}`);
+      } else if (!q.options && q.answer && !new RegExp(q.answer.pattern).test(v)) {
+        errors.push(`answers.${id}: "${v}" does not match ${q.answer.pattern}`);
+      }
+    }
+    for (const rule of q["disabled-when"] ?? []) {
+      if (!values.includes(rule.option)) continue;
+      if (rule.mode && rule.mode === req.mode) {
+        errors.push(`answers.${id}: "${rule.option}" is not allowed in ${rule.mode} mode`);
+      }
+      if (
+        rule.workingTree === "dirty" &&
+        (workingTree === "dirty" || workingTree === "unreadable")
+      ) {
+        errors.push(
+          `answers.${id}: "${rule.option}" is not allowed on a working tree with uncommitted changes`,
+        );
+      }
+    }
+  }
+  return errors;
+}
+
+/**
+ * What Phase 0 applies: the pre-filled pickers and the one state field that
+ * records a request was used. Called only on a request validateRequest passed.
+ */
+export function prefillFor(req, questions = loadQuestions(), now = new Date()) {
+  const byId = new Map(questions.map((q) => [q.id, q]));
+  const prefill = {};
+  for (const [id, answer] of Object.entries(req.answers)) {
+    const q = byId.get(id);
+    prefill[id] = {
+      answer,
+      askedAt: q["asked-at"],
+      ...(q.stateField ? { stateField: q.stateField } : {}),
+    };
+  }
+  return {
+    prefill,
+    statePatch: {
+      launchRequest: {
+        contractVersion: req.contractVersion,
+        mode: req.mode,
+        answered: Object.keys(req.answers).sort(),
+        resolvedAt: now.toISOString(),
+      },
+    },
+  };
+}
+
+/**
+ * The whole resolve step as data, so the CLI and the tests read one answer.
+ *
+ * @param {{file?: string|null, repo?: string|null, env?: object, questions?: object[]}} args
+ */
+export function resolveRequest({ file = null, repo = null, env = process.env, questions } = {}) {
+  const qs = questions ?? loadQuestions();
+  const path = file || env.MA_LAUNCH_REQUEST || "";
+  const absent = { contractVersion: CONTRACT_VERSION, present: false, prefill: {}, statePatch: {} };
+  if (!path) return { code: 0, out: absent };
+  if (!existsSync(path)) {
+    return { code: 0, out: { ...absent, warning: "request-file-missing" } };
+  }
+  let req;
+  try {
+    req = JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return {
+      code: 1,
+      out: {
+        contractVersion: CONTRACT_VERSION,
+        present: true,
+        valid: false,
+        errors: ["request is not valid JSON"],
+      },
+    };
+  }
+  const workingTree = repo ? workingTreeState(repo) : "unchecked";
+  const errors = validateRequest(req, { questions: qs, workingTree });
+  if (errors.length) {
+    return {
+      code: 1,
+      out: { contractVersion: CONTRACT_VERSION, present: true, valid: false, errors },
+    };
+  }
+  return {
+    code: 0,
+    out: {
+      contractVersion: CONTRACT_VERSION,
+      present: true,
+      valid: true,
+      input: req.input,
+      mode: req.mode,
+      workingTree,
+      ...prefillFor(req, qs),
+    },
+  };
+}
+
+export const SESSION_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
+/** Where request files live, per launch.json requestFile.directory. */
+export function requestsDir(env = process.env) {
+  return env.MA_AUTOPILOT_ROOT
+    ? join(env.MA_AUTOPILOT_ROOT, "requests")
+    : join(homedir(), ".claude", "autopilot", "requests");
+}
+
+/**
+ * Write a request file the way launch.json says a client does: named for the
+ * session, mode 0600, in a 0700 directory, never over an existing file.
+ * Returns the path. Called only with a request validateRequest passed.
+ */
+export function writeRequestFile(req, sessionId, env = process.env) {
+  if (!SESSION_ID.test(sessionId)) throw new Error("session id is not a UUID");
+  const dir = requestsDir(env);
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  chmodSync(dir, 0o700);
+  const path = join(dir, `${sessionId}.json`);
+  writeFileSync(path, JSON.stringify(req, null, 2) + "\n", { mode: 0o600, flag: "wx" });
+  return path;
+}
+
+/** Where the desktop client's registered launch repos live. */
+export const launchReposPath = (env = process.env) => join(autopilotRoot(env), "launch-repos.json");
+
+const realDir = (p) => {
+  try {
+    const real = realpathSync(p);
+    return statSync(real).isDirectory() ? real : null;
+  } catch {
+    return null;
+  }
+};
+
+const expandHome = (p) => String(p ?? "").replace(/^~(?=\/|$)/, homedir());
+
+function readJsonOr(file, fallback) {
+  try {
+    return JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return fallback;
+  }
+}
+
+/** Real paths a launch may name: configured autopilot repos and registered ones. */
+export function allowedLaunchRepos(env = process.env) {
+  const config = readJsonOr(join(autopilotRoot(env), "config.json"), {});
+  const registered = readJsonOr(launchReposPath(env), {});
+  const paths = [
+    ...(Array.isArray(config?.repos) ? config.repos.map((r) => r?.localPath) : []),
+    ...(Array.isArray(registered?.repos) ? registered.repos : []),
+  ];
+  return new Set(
+    paths
+      .filter((p) => typeof p === "string" && p)
+      .map((p) => realDir(expandHome(p)))
+      .filter(Boolean),
+  );
+}
+
+/** Is `repoPath` a directory a launch may start in? Compared by real path. */
+export function launchRepoAllowed(repoPath, env = process.env) {
+  const real = typeof repoPath === "string" && isAbsolute(repoPath) ? realDir(repoPath) : null;
+  return Boolean(real) && allowedLaunchRepos(env).has(real);
+}
+
+/**
+ * Add a checkout to launch-repos.json: an absolute directory that is not the
+ * home directory or the filesystem root, stored by real path in a 0600 file.
+ * The read-modify-write holds the file's lock and replaces it atomically, so
+ * two registrations at once both land. Returns the stored path.
+ */
+export function registerRepo(repoPath, env = process.env) {
+  if (typeof repoPath !== "string" || !isAbsolute(repoPath))
+    throw new Error("the path must be absolute");
+  const real = realDir(repoPath);
+  if (!real) throw new Error("the path is not a directory");
+  if (real === "/" || real === realDir(homedir())) {
+    throw new Error("the home directory or the root is not a repository");
+  }
+  const file = launchReposPath(env);
+  mkdirSync(autopilotRoot(env), { recursive: true, mode: 0o700 });
+  updateJsonFileSync(
+    file,
+    (current) => {
+      const repos = new Set(Array.isArray(current?.repos) ? current.repos : []);
+      repos.add(real);
+      return { repos: [...repos].sort() };
+    },
+    { fallback: {}, mode: 0o600, timeoutMs: lockTimeoutFrom(env) },
+  );
+  return real;
+}
+
+/** The launch-plan fields that name this machine, dropped under redact. */
+export const LOCAL_PLAN_FIELDS = ["requestFile", "cwd", "argv", "env"];
+
+const fill = (template, values) =>
+  template.replace(/\{([a-zA-Z]+)\}/g, (whole, k) => (k in values ? values[k] : whole));
+
+/**
+ * What a client runs to start this request unattended, from launch.json. Pure
+ * apart from the working-tree state, which is handed in.
+ *
+ * @param {{request: object, requestFile: string, repoPath: string, sessionId: string,
+ *   workingTree?: string, spec?: object, questions?: object[], redact?: boolean,
+ *   channel?: "desktop"|"phone", jiraHost?: string, settingsFile?: string,
+ *   runLogsRoot?: string}} args
+ * @returns {{code: number, reason?: string, out: object}}
+ */
+export function planLaunch({
+  request,
+  requestFile,
+  repoPath,
+  sessionId,
+  settingsFile = unattendedSettingsPath(),
+  runLogsRoot = unattendedLogsRoot(),
+  workingTree = "unchecked",
+  spec = launchSpec(),
+  questions,
+  redact = false,
+  channel = "desktop",
+  jiraHost = configuredJiraHost(),
+}) {
+  const errors = validateRequest(request, { questions, workingTree, channel, jiraHost });
+  if (!SESSION_ID.test(String(sessionId ?? ""))) errors.push("session id must be a UUID");
+  if (typeof repoPath !== "string" || !isAbsolute(repoPath)) {
+    errors.push("the repository path must be absolute");
+  }
+  if (errors.length) {
+    return {
+      code: 1,
+      reason: "invalid-request",
+      out: { contractVersion: CONTRACT_VERSION, valid: false, errors },
+    };
+  }
+  const host = spec.hosts.claude;
+  const shape = host.supported ? host.modes?.[request.mode] : undefined;
+  if (!shape) {
+    return {
+      code: 1,
+      reason: "no-launch-shape",
+      out: {
+        contractVersion: CONTRACT_VERSION,
+        valid: false,
+        errors: [`launch.json declares no unattended launch for mode ${request.mode}`],
+      },
+    };
+  }
+  const values = {
+    input: promptArgument(request.input, jiraHost),
+    sessionId,
+    requestFile,
+    repoPath,
+    settingsFile,
+    runLogsRoot,
+  };
+  const plan = {
+    contractVersion: CONTRACT_VERSION,
+    valid: true,
+    verified: spec.verified === true,
+    host: "claude",
+    mode: request.mode,
+    sessionId,
+    requestFile,
+    bin: host.bin,
+    cwd: fill(host.cwd, values),
+    argv: shape.argv.map((a) => fill(a, values)),
+    env: Object.fromEntries(Object.entries(shape.env).map(([k, v]) => [k, fill(v, values)])),
+    shell: false,
+  };
+  if (redact) for (const k of LOCAL_PLAN_FIELDS) delete plan[k];
+  return { code: 0, out: plan };
+}
+
+function planMain(rest) {
+  let file = null;
+  let repo = null;
+  let sessionId = null;
+  let redact = false;
+  let channel = "desktop";
+  for (let i = 0; i < rest.length; i++) {
+    if (rest[i] === "--repo") repo = rest[++i] ?? null;
+    else if (rest[i] === "--session-id") sessionId = rest[++i] ?? null;
+    else if (rest[i] === "--redact") redact = true;
+    else if (rest[i] === "--channel") channel = rest[++i] ?? "";
+    else if (!file && !rest[i].startsWith("--")) file = rest[i];
+    else {
+      process.stderr.write(`launch-request: unknown argument ${rest[i]}\n`);
+      return 2;
+    }
+  }
+  if (!file || !repo || !sessionId || !CHANNELS.includes(channel)) {
+    process.stderr.write(
+      `usage: launch-request.mjs plan <file> --repo <path> --session-id <uuid> [--channel ${CHANNELS.join("|")}] [--redact]\n`,
+    );
+    return 2;
+  }
+  let request;
+  try {
+    request = JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    process.stderr.write("launch-request: the request file is missing or not JSON\n");
+    return 1;
+  }
+  if (!launchRepoAllowed(repo)) {
+    const out = {
+      contractVersion: CONTRACT_VERSION,
+      valid: false,
+      errors: ["the repository is neither a configured autopilot repo nor a registered one"],
+    };
+    process.stdout.write(JSON.stringify(out, null, 2) + "\n");
+    return 1;
+  }
+  const { code, out } = planLaunch({
+    request,
+    requestFile: file,
+    repoPath: repo,
+    sessionId,
+    workingTree: workingTreeState(repo),
+    redact,
+    channel,
+  });
+  process.stdout.write(JSON.stringify(out, null, 2) + "\n");
+  return code;
+}
+
+function registerMain(rest) {
+  if (rest.length !== 1) {
+    process.stderr.write("usage: launch-request.mjs register-repo <absolute path>\n");
+    return 2;
+  }
+  if (isUnattended()) {
+    process.stderr.write(
+      "launch-request: an unattended run may not register a launch repository\n",
+    );
+    return 3;
+  }
+  try {
+    const stored = registerRepo(rest[0]);
+    process.stdout.write(
+      JSON.stringify({ contractVersion: CONTRACT_VERSION, registered: stored }) + "\n",
+    );
+    return 0;
+  } catch (err) {
+    process.stderr.write(`launch-request: ${err.message}\n`);
+    return 2;
+  }
+}
+
+function main(argv) {
+  const [cmd, ...rest] = argv;
+  if (cmd === "questions" || cmd === "spec") {
+    if (rest.length) {
+      process.stderr.write(`launch-request: ${cmd} takes no arguments\n`);
+      return 2;
+    }
+    const doc = cmd === "questions" ? questionsDocument() : launchSpec();
+    process.stdout.write(JSON.stringify(doc, null, 2) + "\n");
+    return 0;
+  }
+  if (cmd === "plan") return planMain(rest);
+  if (cmd === "register-repo") return registerMain(rest);
+  let file = null;
+  let repo = null;
+  for (let i = 0; i < rest.length; i++) {
+    if (rest[i] === "--repo") repo = rest[++i] ?? null;
+    else if (!file && !rest[i].startsWith("--")) file = rest[i];
+    else {
+      process.stderr.write(`launch-request: unknown argument ${rest[i]}\n`);
+      return 2;
+    }
+  }
+  if (cmd !== "validate" && cmd !== "resolve") {
+    process.stderr.write(
+      "usage: launch-request.mjs validate <file> | resolve [<file>] [--repo <path>] | plan <file> --repo <path> --session-id <uuid> [--channel desktop|phone] | questions | spec | register-repo <path>\n",
+    );
+    return 2;
+  }
+  if (cmd === "validate" && !file) {
+    process.stderr.write("launch-request: validate needs a file\n");
+    return 2;
+  }
+  if (cmd === "validate" && !existsSync(file)) {
+    const out = {
+      contractVersion: CONTRACT_VERSION,
+      present: false,
+      valid: false,
+      errors: ["no such file"],
+    };
+    process.stdout.write(JSON.stringify(out, null, 2) + "\n");
+    return 1;
+  }
+  const { code, out } = resolveRequest({ file, repo });
+  if (out.warning) process.stderr.write(`launch-request: ${out.warning}, continuing without it\n`);
+  process.stdout.write(JSON.stringify(out, null, 2) + "\n");
+  return code;
+}
+
+if (invokedDirectly(import.meta.url)) {
+  runMain("launch-request", () => {
+    process.exitCode = main(process.argv.slice(2));
+  });
+}