@mmerterden/multi-agent-pipeline 20.2.0 → 20.3.0

package/docs/server-readiness.md

@@ -40,27 +40,32 @@ npx @mmerterden/multi-agent-pipeline install --unattended --dry-run   # see it f
 npx @mmerterden/multi-agent-pipeline install --unattended             # write it
 ```
 
-It prints the whole profile with a reason per line before writing anything, and
-it is additive: an entry you added by hand survives, a narrower `Bash(...)` rule
-is kept alongside, unrelated settings are untouched, and a second run changes
-nothing. A `settings.json` that does not parse is refused rather than
-overwritten.
-
-By hand, the same thing is:
-
-```jsonc
-// ~/.claude/settings.json
-{
-  "permissions": {
-    "allow": ["Bash", "Edit", "Write", "Agent"]
-  }
-}
-```
-
-Grant the narrowest set the work needs. A server that only reviews does not
-need `Write` - though note that the shipped profile is deliberately broad,
-because a run builds and tests whatever the target repo uses and a narrow list
-is the one the first unfamiliar repo stops at.
+It prints the whole profile with a reason per line before writing anything,
+and writes it to `~/.claude/multi-agent-unattended.settings.json`, which the
+autopilot runner passes to each run with `claude --settings`.
+`~/.claude/settings.json`, the posture of every attended session, is not changed.
+The profile (`pipeline/schemas/unattended-profile.json`) is
+`permissions.defaultMode: "dontAsk"`, a narrow allow list (`Bash(git *)`,
+`Bash(xcodebuild *)`, `Bash(xcrun simctl *)`, `Edit`, `Write` and the rest,
+each with its reason), deny
+rules for merging, pushing and reading `~/.ssh`, `~/.aws`, `~/.gnupg` and
+`~/Library/Keychains`, and the toolkit's strict URL policy. `--unattended-sandbox`
+adds an OS sandbox block (`sandbox.enabled`, `failIfUnavailable`,
+`allowUnsandboxedCommands: false`, a network allowlist, `denyRead` for `~/.ssh`
+and `~/.aws`).
+
+It is additive over the profile file: an entry already there survives, a
+narrower `Bash(...)` rule is kept alongside without standing in for the
+profile's own entry, and a second run changes nothing. Permission lists merge
+across settings files, so a whole-`Bash` allow in `settings.json` still reaches
+an unattended run; the installer reports it and doctor warns, and neither
+removes it. If an earlier install wrote the profile into `settings.json`, the
+installer prints the move and removes exactly those entries from it. A profile
+file that does not parse is refused rather than overwritten.
+
+The permission list is the second line. The guard hook under
+`MULTI_AGENT_UNATTENDED=1` and a separate macOS user are the first and the
+boundary: `pipeline/multi-agent-refs/features/unattended-security.md`.
 
 `doctor --profile=server` reports this as `unattended-permissions`, against the
 same rule the writer applies.
@@ -142,8 +147,10 @@ empty and the ledger is a list of identical failures with no indication which
 came first. After `MA_AP_BREAKER_LIMIT` consecutive attempts that produced
 nothing (3 by default, 0 disables), the runner stops taking new work, writes the
 reason into `queue.json` so `autopilot-status` shows it, and says what to check.
-One successful attempt clears it. A run waiting for a person (`needs-input`) and
-an item arming refused (`blocked-*`) are deliberately not failures.
+One successful attempt clears it. A run waiting for a person (`needs-input`,
+`awaiting-answer`), an item arming refused (`blocked-*`), a run the runner lost
+across a restart (`died`) and a rate limit (which has its own backoff) are
+deliberately not failures.
 
 **Telemetry.** `ticks.jsonl` gets one JSON line per tick. The human log answers
 "what happened just now"; a server is only ever asked "how has this been
@@ -183,6 +190,6 @@ single-owner machine, not on a shared one.
 ## What this page does NOT cover
 
 - Turning any of it on. Every step here is the operator's to take.
-- Linux, Windows, systemd, Docker. Out of scope and staying there.
+- Any host other than macOS, and containers. Out of scope and staying there (ADR-0012).
 - Multi-user servers. Everything above assumes one account owns the install,
   the keychain and the queue.

package/index.js

@@ -92,7 +92,7 @@ if (command === "--version" || command === "-v" || command === "version") {
     npx @mmerterden/multi-agent-pipeline install --index-only Ship only the skills index (dynamic skill loading)
     npx @mmerterden/multi-agent-pipeline install --prune-external  Also remove pre-v15 catalog copies that differ from the shipped catalog
 
-  Uninstall (token-preserving - Keychain/Credential Manager untouched):
+  Uninstall (token-preserving - Keychain untouched):
     npx @mmerterden/multi-agent-pipeline uninstall            Interactive: remove from all installed targets
     npx @mmerterden/multi-agent-pipeline uninstall --yes      Skip prompt
     npx @mmerterden/multi-agent-pipeline uninstall --dry-run  Report what would be removed

package/install/_common.mjs

@@ -184,9 +184,7 @@ export function copyDir(src, dest, opts = {}) {
   // user-owned trees (rules/) so an update adds new baseline files but preserves
   // the user's locally-evolved copies. cpSync with force:false + errorOnExist:false
   // silently skips existing files.
-  // Normalize to forward slashes so exclude patterns (written posix-style)
-  // also match on win32, where cpSync hands back backslash paths.
-  const relOf = (source) => source.slice(src.length).split("\\").join("/").replace(/^\//, "");
+  const relOf = (source) => source.slice(src.length).replace(/^\//, "");
   // Junk is filtered on EVERY path, including the two that take no exclude
   // list: the point is that the caller never has to remember it.
   const filter = (source) => {
@@ -571,8 +569,8 @@ export function atomicWrite(path, content) {
 }
 
 /**
- * Count files in a directory tree (pure fs recursion - works on win32 where
- * `find` is unavailable, and avoids a subprocess per call). A plain-file path
+ * Count files in a directory tree (pure fs recursion - avoids a subprocess
+ * per call). A plain-file path
  * counts as 1, matching the old `find <path> -type f` behavior relied on by
  * the DEV_ONLY_SCRIPTS exclusion accounting.
  * @param {string} dir

package/install/_platform-filter.mjs

@@ -11,7 +11,7 @@
 
 import { readdirSync, writeFileSync } from "fs";
 import { join } from "path";
-import { isDryRun } from "./_common.mjs";
+import { copyFile, isDryRun } from "./_common.mjs";
 import { routeSkill } from "../pipeline/scripts/_stack-routing.mjs";
 
 /** Uninstall reads this to know exactly which external skill dirs are ours to remove. */
@@ -71,3 +71,25 @@ export function writeExternalSkillsManifest(dest, names) {
     /* best-effort - a missing manifest just means uninstall falls back */
   }
 }
+
+/**
+ * Copy every NOTICE-*.md from the external catalog into `dest`, beside the
+ * skill dirs, unchanged. Each one attributes a set of vendored skills to its
+ * upstream, so a host that receives the catalog locally carries the notices
+ * with it. All of them are copied whatever the stack filter kept: a notice
+ * costs nothing on disk and never enters a skills block. Uninstall removes
+ * them together with the manifest-listed dirs.
+ *
+ * @param {string} externalSrc - absolute path to `pipeline/skills/shared/external/`
+ * @param {string} dest - the installed skills directory
+ * @returns {number} files copied
+ */
+export function copyExternalNotices(externalSrc, dest) {
+  let n = 0;
+  for (const e of readdirSync(externalSrc, { withFileTypes: true })) {
+    if (!e.isFile() || !/^NOTICE-.*\.md$/.test(e.name)) continue;
+    copyFile(join(externalSrc, e.name), join(dest, e.name));
+    n++;
+  }
+  return n;
+}

package/install/_unattended-profile.mjs

@@ -1,113 +1,359 @@
 /**
- * _unattended-profile.mjs  -  the permission posture a machine with nobody at
- * the keyboard needs, written only when asked for.
+ * _unattended-profile.mjs  -  the posture a machine with nobody at the keyboard
+ * needs, written only when asked for.
  *
  * autopilot spawns its child with `--permission-prompts none`. That stops Claude
  * Code from ASKING; it grants nothing. The tools the child then calls still have
  * to be allowed somewhere, and on a fresh machine they are not - so the run
  * stops at the first tool call, silently, with no prompt anywhere for a person
- * to answer. It looks exactly like a queue that has nothing to do.
+ * to answer.
  *
- * This is opt-in and always will be. A default install writes no permissions at
- * all, because widening a permission set is not a thing an installer should do
- * to somebody who only wanted the pipeline files copied. `--unattended` prints
- * the full list and the reason for each line BEFORE writing anything, because
- * "the installer changed my permissions" should never be something a person
- * discovers afterwards.
+ * The profile is `permissions.defaultMode: "dontAsk"` (a call that would prompt
+ * is denied, not left waiting; any other mode already in the file is replaced),
+ * a narrow allow list, deny rules for what no unattended run does, the
+ * toolkit's strict URL policy and index deny list, and an OS sandbox block. The
+ * entries and their reasons live in pipeline/schemas/unattended-profile.json;
+ * lib/unattended-profile-check.mjs judges a file against it for this
+ * installer, for doctor and for the autopilot runner, which will not launch a
+ * child unless the file still holds the posture.
  *
- * The entries are broad on purpose, and that breadth is the cost of unattended
- * operation rather than an oversight. A pipeline run builds, tests, edits, and
- * shells out to whatever the repo's own toolchain is; an allowlist narrow
- * enough to be interesting would be one the first unfamiliar repo breaks. The
- * honest framing is: this is a machine you have decided to let run on its own.
+ * The sandbox is the boundary: Seatbelt on macOS, enforced for every Bash
+ * command and every process it starts, with writes limited to the working
+ * directory, the session temp directory and the unattended run directory, and
+ * egress limited to the listed hosts. The file tools and MCP tools are outside
+ * it; the Edit and Read deny rules cover the file tools, and agent-guard.sh
+ * under MULTI_AGENT_UNATTENDED=1 is a second layer over all of them
+ * (multi-agent-refs/features/unattended-security.md).
+ *
+ * It is written to its own file, ~/.claude/multi-agent-unattended.settings.json
+ * (pipeline/lib/unattended-settings-location.mjs), which the autopilot runner
+ * hands to each child with `claude --settings`. ~/.claude/settings.json is the
+ * attended posture and is not touched, with one exception: when it carries the
+ * profile the v20.2.1 install wrote there (install/unattended-profile-legacy.json),
+ * exactly those entries are removed from it.
+ *
+ * Opt-in, printed in full with a reason per line BEFORE anything is written.
+ * Allow and deny rules are additive; a sandbox block already in the file is
+ * corrected to the shipped one, keeping its extra deny entries and dropping
+ * whatever widens it.
  *
  * @module install/_unattended-profile
  */
 
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { unattendedSettingsPath } from "../pipeline/lib/unattended-settings-location.mjs";
+import { prefsHosts, profileGaps } from "../pipeline/lib/unattended-profile-check.mjs";
+
+const PROFILE_PATH = join(
+  dirname(dirname(fileURLToPath(import.meta.url))),
+  "pipeline",
+  "schemas",
+  "unattended-profile.json",
+);
+
+/** The profile data, as shipped. */
+export function loadUnattendedProfile(path = PROFILE_PATH) {
+  return JSON.parse(readFileSync(path, "utf-8"));
+}
+
+const PROFILE = loadUnattendedProfile();
+const LEGACY = JSON.parse(
+  readFileSync(
+    join(dirname(fileURLToPath(import.meta.url)), "unattended-profile-legacy.json"),
+    "utf-8",
+  ),
+);
+
+/** Allow rules and their reasons: [rule, why][]. */
+export const UNATTENDED_ALLOW = PROFILE.allow;
+/** Deny rules and their reasons: [rule, why][]. */
+export const UNATTENDED_DENY = PROFILE.deny;
+/** Env entries: [key, value, why][]. */
+export const UNATTENDED_ENV = PROFILE.env;
+
+const hasRule = (list, rule) => list.some((a) => String(a) === rule);
+
+function readSettingsFile(path) {
+  if (!existsSync(path)) return {};
+  try {
+    return JSON.parse(readFileSync(path, "utf-8")) || {};
+  } catch (err) {
+    // A settings file that does not parse is not ours to rewrite: overwriting
+    // it would lose whatever is in there.
+    throw new Error(`${path} is not valid JSON, so it will not be modified: ${err.message}`, {
+      cause: err,
+    });
+  }
+}
+
+/**
+ * The profile entries an earlier install wrote into settings.json, when it
+ * carries that install's signature: the profile's defaultMode and its whole
+ * deny set. Returns the labels to remove, [] when the signature is absent.
+ */
+function legacyEntries(settings) {
+  const perms = settings.permissions || {};
+  const allow = Array.isArray(perms.allow) ? perms.allow.map(String) : [];
+  const deny = Array.isArray(perms.deny) ? perms.deny.map(String) : [];
+  const signed =
+    perms.defaultMode === LEGACY.defaultMode && LEGACY.deny.every((rule) => deny.includes(rule));
+  if (!signed) return [];
+  const env = settings.env || {};
+  return [
+    `defaultMode:${LEGACY.defaultMode}`,
+    ...LEGACY.allow.filter((r) => allow.includes(r)),
+    ...LEGACY.deny.map((r) => `deny:${r}`),
+    ...LEGACY.env.filter(([k, v]) => env[k] === v).map(([k, v]) => `env:${k}=${v}`),
+  ];
+}
+
+const union = (a, b) => [...new Set([...(Array.isArray(a) ? a.map(String) : []), ...b])];
+
+/**
+ * The sandbox block to write: the shipped one, with the extra deny entries
+ * and other keys of a block already in the file kept, and everything that
+ * would widen it (an excluded command, an extra write path or domain, a
+ * re-opened read, a lifted protection) dropped.
+ *
+ * @param {object|undefined} existing
+ * @param {string[]} extraHosts
+ */
+function sandboxBlock(existing, extraHosts) {
+  const { $comment: _omit, ...want } = PROFILE.sandbox;
+  const cur = existing && typeof existing === "object" ? existing : {};
+  const {
+    excludedCommands: _ex,
+    allowAppleEvents: _ae,
+    enableWeakerNestedSandbox: _wn,
+    ...keep
+  } = cur;
+  const curFs = cur.filesystem && typeof cur.filesystem === "object" ? cur.filesystem : {};
+  const { disabled: _d, allowRead: _ar, ...keepFs } = curFs;
+  const curNet = cur.network && typeof cur.network === "object" ? cur.network : {};
+  const { allowAllUnixSockets: _us, ...keepNet } = curNet;
+  return {
+    ...keep,
+    ...Object.fromEntries(Object.entries(want).filter(([, v]) => typeof v !== "object")),
+    filesystem: {
+      ...keepFs,
+      allowWrite: [...want.filesystem.allowWrite],
+      denyWrite: union(curFs.denyWrite, want.filesystem.denyWrite),
+      denyRead: union(curFs.denyRead, want.filesystem.denyRead),
+    },
+    network: {
+      ...keepNet,
+      ...Object.fromEntries(Object.entries(want.network).filter(([, v]) => !Array.isArray(v))),
+      allowMachLookup: [...want.network.allowMachLookup],
+      allowedDomains: [...new Set([...want.network.allowedDomains, ...extraHosts])],
+    },
+  };
+}
 
 /**
- * Tool name plus why an unattended run cannot proceed without it. The reason is
- * printed, not just stored: a list of fifteen tool names with no reasons is a
- * list nobody audits.
+ * What applying the profile would do. describe and apply both read this, so
+ * the printed plan and the write cannot disagree.
+ *
+ * @param {object} current the profile file's parsed content, or {}
+ * @param {{home?: string, settings?: object, extraHosts?: string[]}} [opts]
+ *   settings: ~/.claude/settings.json, parsed, for the whole-Bash warning and
+ *   the migration; extraHosts: the prefs hosts, read from home when omitted
  */
-export const UNATTENDED_ALLOW = [
-  ["Bash", "every build, test, git and gh call the pipeline makes"],
-  ["Edit", "Phase 3 cannot change a file without it"],
-  ["Write", "new files, and every artefact a phase leaves behind"],
-  ["Read", "reading the repo it was pointed at"],
-  ["Glob", "finding files by pattern instead of shelling out to find"],
-  ["Grep", "the same, for content"],
-  ["Agent", "Phase 1 and Phase 4 dispatch subagents"],
-  ["Skill", "the phase specs are skills"],
-  ["WebFetch", "issue and ticket bodies referenced by URL"],
-  ["TaskCreate", "the phase tracker's task list"],
-  ["TaskUpdate", "the same"],
-  ["TaskList", "the same"],
-  ["TaskGet", "the same"],
-];
+export function planUnattendedProfile(current = {}, { home = "", settings, extraHosts } = {}) {
+  const perms = current.permissions || {};
+  const allow = Array.isArray(perms.allow) ? perms.allow.map(String) : [];
+  const deny = Array.isArray(perms.deny) ? perms.deny.map(String) : [];
+  const env = current.env || {};
+  const attended =
+    settings ?? (home ? readSettingsFile(join(home, ".claude", "settings.json")) : {});
+  const attendedAllow = Array.isArray(attended.permissions?.allow)
+    ? attended.permissions.allow.map(String)
+    : [];
+  const hosts = extraHosts ?? (home ? prefsHosts(home) : []);
+  const rows = [];
+
+  const mode = perms.defaultMode;
+  const wantMode = PROFILE.defaultMode.value;
+  const modeLabel = `defaultMode:${wantMode}`;
+  if (mode === wantMode)
+    rows.push({ label: modeLabel, why: PROFILE.defaultMode.why, mark: "already" });
+  else if (mode === undefined || mode === "default" || mode === "manual")
+    rows.push({ label: modeLabel, why: PROFILE.defaultMode.why, mark: "add" });
+  else
+    rows.push({
+      label: modeLabel,
+      why: `${PROFILE.defaultMode.why}; replaces ${mode}, which would let an unattended run act without the allow list`,
+      mark: "replace",
+    });
+
+  for (const { rule, why } of PROFILE.wideAllows) {
+    if (hasRule(attendedAllow, rule)) rows.push({ label: `warn:${rule}`, why, mark: "warn" });
+  }
+  for (const [rule, why] of PROFILE.allow) {
+    rows.push({ label: rule, why, mark: hasRule(allow, rule) ? "already" : "add" });
+  }
+  for (const [rule, why] of PROFILE.deny) {
+    rows.push({ label: `deny:${rule}`, why, mark: hasRule(deny, rule) ? "already" : "add" });
+  }
+  for (const [key, value, why] of PROFILE.env) {
+    let mark = "add";
+    if (env[key] === value) mark = "already";
+    else if (env[key] !== undefined) mark = "kept";
+    rows.push({ label: `env:${key}=${value}`, why, mark });
+  }
+  const present = current.sandbox && typeof current.sandbox === "object";
+  const target = sandboxBlock(current.sandbox, hosts);
+  let sandboxMark = "add";
+  if (present)
+    sandboxMark =
+      JSON.stringify(current.sandbox) === JSON.stringify(target) ? "already" : "correct";
+  rows.push({
+    label: "sandbox",
+    why: "OS sandbox for Bash and everything it starts: required, no unsandboxed retry, no excluded commands, writes limited to the worktree and the unattended run directory, protected host files denied, credential stores unreadable, network limited to the listed hosts",
+    mark: sandboxMark,
+  });
+  for (const label of legacyEntries(attended)) {
+    rows.push({
+      label: `migrate:${label}`,
+      why: "written into ~/.claude/settings.json by an earlier install; it moves to the profile file",
+      mark: "migrate",
+    });
+  }
+  return { rows, extraHosts: hosts };
+}
+
+const MARK_TEXT = {
+  add: "will be added",
+  already: "already there",
+  kept: "kept as is",
+  replace: "will be replaced",
+  correct: "will be corrected",
+  warn: "left in settings.json",
+  migrate: "removed from settings.json",
+};
 
 /**
  * Render the profile for a human to read before it is applied.
  *
- * @param {string[]} already entries the settings file already carries
+ * @param {object} current the profile file's parsed content, or {}
+ * @param {{home?: string, settings?: object}} [opts]
  * @returns {string}
  */
-export function describeUnattendedProfile(already = []) {
+export function describeUnattendedProfile(current = {}, opts = {}) {
+  const { rows } = planUnattendedProfile(current || {}, opts);
+  const target = opts.home ? unattendedSettingsPath(opts.home) : unattendedSettingsPath();
   const lines = [
-    "  Unattended permission profile  -  these go into ~/.claude/settings.json",
-    "  under permissions.allow. Nothing is removed; existing entries are kept.",
+    `  Unattended permission profile  -  these go into ${target},`,
+    "  which the autopilot runner passes to each run with `claude --settings`.",
+    "  ~/.claude/settings.json (the attended posture) is not changed.",
+    "  An entry is 'already there' only when that exact rule is present.",
     "",
   ];
-  for (const [tool, why] of UNATTENDED_ALLOW) {
-    const mark = already.includes(tool) ? "already there" : "will be added";
-    lines.push(`    ${tool.padEnd(12)} ${why}  (${mark})`);
+  for (const r of rows) {
+    lines.push(`    ${r.label.padEnd(44)}  ${r.why}  (${MARK_TEXT[r.mark]})`);
   }
   lines.push("");
-  lines.push("  This is broad, and that breadth is what unattended operation costs: a run");
-  lines.push("  builds and tests whatever the target repo uses, so a narrow list is one the");
-  lines.push("  first unfamiliar repo stops at, with nobody there to answer.");
+  lines.push(
+    "  The OS sandbox is the boundary for Bash; the deny rules cover the file tools it does",
+  );
+  lines.push(
+    "  not reach, and agent-guard is a second layer under MULTI_AGENT_UNATTENDED=1. The runner",
+  );
+  lines.push(
+    "  refuses to launch unless this file still holds the posture. See features/unattended-security.md.",
+  );
   return lines.join("\n");
 }
 
+function removeLegacy(settings, labels) {
+  const perms = { ...(settings.permissions || {}) };
+  const env = { ...(settings.env || {}) };
+  for (const label of labels) {
+    if (label.startsWith("defaultMode:")) delete perms.defaultMode;
+    else if (label.startsWith("deny:")) {
+      const rule = label.slice("deny:".length);
+      perms.deny = (perms.deny || []).filter((r) => String(r) !== rule);
+    } else if (label.startsWith("env:")) delete env[label.slice("env:".length).split("=")[0]];
+    else perms.allow = (perms.allow || []).filter((r) => String(r) !== label);
+  }
+  for (const k of ["allow", "deny"])
+    if (Array.isArray(perms[k]) && !perms[k].length) delete perms[k];
+  const out = { ...settings, permissions: perms, env };
+  if (!Object.keys(perms).length) delete out.permissions;
+  if (!Object.keys(env).length) delete out.env;
+  return out;
+}
+
 /**
- * Merge the profile into settings.json. Additive only, and idempotent: running
- * it twice changes nothing the second time, and an entry a person added by hand
- * survives.
+ * The profile file's next content: `current` with every "add", "replace" and
+ * "correct" row of the plan applied. Pure; applyUnattendedProfile writes it.
+ *
+ * @param {object} current the profile file's parsed content, or {}
+ * @param {{home?: string, settings?: object, extraHosts?: string[]}} [opts]
+ * @returns {object}
+ */
+export function buildUnattendedProfile(current = {}, opts = {}) {
+  const { rows, extraHosts } = planUnattendedProfile(current, { settings: {}, ...opts });
+  const perms = { ...(current.permissions || {}) };
+  const allow = Array.isArray(perms.allow) ? [...perms.allow] : [];
+  const deny = Array.isArray(perms.deny) ? [...perms.deny] : [];
+  const next = { ...current };
+  for (const { label, mark } of rows) {
+    if (!["add", "replace", "correct"].includes(mark)) continue;
+    if (label.startsWith("defaultMode:")) perms.defaultMode = label.slice("defaultMode:".length);
+    else if (label.startsWith("deny:")) deny.push(label.slice("deny:".length));
+    else if (label.startsWith("env:")) {
+      const [key, ...rest] = label.slice("env:".length).split("=");
+      next.env = { ...(next.env || {}), [key]: rest.join("=") };
+    } else if (label === "sandbox") next.sandbox = sandboxBlock(current.sandbox, extraHosts);
+    else allow.push(label);
+  }
+  perms.allow = allow;
+  if (deny.length) perms.deny = deny;
+  next.permissions = perms;
+  return next;
+}
+
+/**
+ * Write the profile into its own settings file. Idempotent: running it twice
+ * changes nothing the second time.
  *
  * @param {{home:string, dryRun?:boolean}} opts
- * @returns {{path:string, added:string[], already:string[], written:boolean}}
+ * @returns {{path:string, added:string[], warned:string[], migrated:string[], removed:string[], already:string[], kept:string[], written:boolean}}
  */
 export function applyUnattendedProfile({ home, dryRun = false }) {
-  const path = join(home, ".claude", "settings.json");
-  let settings = {};
-  if (existsSync(path)) {
-    try {
-      settings = JSON.parse(readFileSync(path, "utf-8"));
-    } catch (err) {
-      // A settings file that does not parse is the user's, not ours to
-      // rewrite: overwriting it would lose whatever is in there.
-      throw new Error(`${path} is not valid JSON, so it will not be modified: ${err.message}`, {
-        cause: err,
-      });
-    }
+  const path = unattendedSettingsPath(home);
+  const settingsPath = join(home, ".claude", "settings.json");
+  const current = readSettingsFile(path);
+  const settings = readSettingsFile(settingsPath);
+  const { rows, extraHosts } = planUnattendedProfile(current, { home, settings });
+  const pick = (...marks) => rows.filter((r) => marks.includes(r.mark)).map((r) => r.label);
+  const added = pick("add", "replace", "correct");
+  const migrated = pick("migrate").map((l) => l.slice("migrate:".length));
+  const result = {
+    path,
+    added,
+    warned: pick("warn").map((l) => l.slice("warn:".length)),
+    migrated,
+    removed: [],
+    already: pick("already"),
+    kept: pick("kept"),
+  };
+  if (dryRun || (!added.length && !migrated.length)) return { ...result, written: false };
+
+  if (added.length) {
+    const next = buildUnattendedProfile(current, { home, settings, extraHosts });
+    const gaps = profileGaps(next, PROFILE, { extraHosts });
+    if (gaps.sandbox.length || gaps.permissions.length)
+      throw new Error(
+        `the profile would still fall short: ${[...gaps.sandbox, ...gaps.permissions].join("; ")}`,
+      );
+    writeFileSync(path, `${JSON.stringify(next, null, 2)}\n`, { mode: 0o600 });
   }
-  const permissions = settings.permissions || {};
-  const allow = Array.isArray(permissions.allow) ? [...permissions.allow] : [];
-  const already = [];
-  const added = [];
-  for (const [tool] of UNATTENDED_ALLOW) {
-    if (allow.some((a) => String(a) === tool || String(a).startsWith(`${tool}(`)))
-      already.push(tool);
-    else {
-      allow.push(tool);
-      added.push(tool);
-    }
+  if (migrated.length) {
+    writeFileSync(settingsPath, `${JSON.stringify(removeLegacy(settings, migrated), null, 2)}\n`);
   }
-  if (dryRun || !added.length) return { path, added, already, written: false };
-
-  settings.permissions = { ...permissions, allow };
-  writeFileSync(path, `${JSON.stringify(settings, null, 2)}\n`);
-  return { path, added, already, written: true };
+  return { ...result, written: true };
 }