@damiangilgonzalez/harness 1.3.12 → 1.3.14

package/scripts/install-apply.js

@@ -2,13 +2,17 @@
 import { rmSync, existsSync, cpSync, lstatSync, mkdirSync, readFileSync, realpathSync, writeFileSync, appendFileSync, readdirSync } from 'node:fs';
 import { join, dirname, relative, resolve, sep } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
+import { spawnSync } from 'node:child_process';
 import { planInstall } from './install-plan.js';
 import { targetPaths, writeSkill, wireHook, unwireHook, baseDir, TARGET_IDS } from '../targets/index.js';
+import { shadowTarget } from '../targets/agents-md-shadow.js';
 import {
   targetHasAgents, reconcileAgents, agentPath, agentNames,
-  resolveAgentNames, agentByName, allAgentNames, readDeveloperTier,
+  resolveAgentNames, agentByName, allAgentNames, readDeveloperTier, writeDeveloperTier,
 } from '../targets/agents.js';
+import { projectOptOuts } from '../targets/opt-outs.js';
 import { readState, writeState } from './lib/state.js';
+import { withDefaultSkillFloor } from './lib/default-skill-floor.js';
 import { readManifest, writeManifest } from './lib/manifest-file.js';
 import { createBackup } from './lib/backups.js';
 import {
@@ -66,14 +70,20 @@ function ensureBase(id, cwd, baseVersions) {
 export function generatedHookFiles({ target, cwd, policy }) {
   if (target !== 'claude') return [];
   const lifecycle = [
+    // Committed, not machine state — and therefore the one entry here that, if omitted, leaves an
+    // executable behind in a tree the user pushes.
+    join(cwd, '.claude', 'rsc-bootstrap.mjs'),
     join(cwd, '.rsc', 'session-start.mjs'),
     join(cwd, '.rsc', 'worklog-checkpoint.mjs'),
     join(cwd, '.rsc', 'hook-once.mjs'),
     join(cwd, '.rsc', 'worktree-reaper.mjs'),
   ];
-  if (policy?.codeHooks === false) return [...lifecycle, join(cwd, '.rsc', 'suggest-always-on.md')];
-  return [...lifecycle,
-    join(cwd, '.rsc', 'ship-guard.mjs'), join(cwd, '.rsc', 'danger-guard.mjs'),
+  // The danger guard is declared on its own terms (#273): present unless the plan says otherwise,
+  // whether or not the code guards are.
+  const danger = policy?.dangerGuard === false ? [] : [join(cwd, '.rsc', 'danger-guard.mjs')];
+  if (policy?.codeHooks === false) return [...lifecycle, ...danger, join(cwd, '.rsc', 'suggest-always-on.md')];
+  return [...lifecycle, ...danger,
+    join(cwd, '.rsc', 'ship-guard.mjs'),
     join(cwd, '.rsc', 'gitmoji-guard.mjs'), join(cwd, '.rsc', 'userprompt-gate.mjs'),
     join(cwd, '.rsc', 'sello.mjs')];
 }
@@ -109,6 +119,12 @@ export function managedPathsForInstall({ skillIds, agentIds = [], target, home,
       out.push(step.to, ...generatedHookFiles({ target, cwd, policy }));
     }
   }
+  // The shadow CLAUDE.md that keeps a natively-read AGENTS.md from doubling the always-on body.
+  // Written by whichever of the two adapters is wired second, so it is declared for both families,
+  // not just for claude. A claude install must assume its own wiring: settings.json does not name
+  // it yet at plan time.
+  const shadow = shadowTarget(cwd, { assumeClaudeWired: target === 'claude' });
+  if (shadow) out.push(shadow);
   return [...new Set(out)];
 }
 
@@ -116,17 +132,56 @@ export function managedPathsForInstall({ skillIds, agentIds = [], target, home,
 // which is machine-local and therefore lost on every clone: a team that disarmed the
 // gitmoji guard found it armed again on the next checkout, with nobody having decided
 // that. They are decisions, so they belong in the committed declaration.
+//
+// Two distinctions this function exists to keep, both of which used to be collapsed:
+//
+//   ABSENT is not EMPTY. In a clone `.rsc/` does not exist, and reading "no markers here" as
+//   "the team re-armed everything" would have sync quietly delete the decision it came to
+//   rebuild. Unreadable returns null — "I know nothing" — and the caller keeps what was
+//   declared. A readable directory with no markers returns [], which IS a statement: somebody
+//   deleted the last marker, and deleting it is how a gate gets re-armed.
+//
+//   Not every switch is the team's to make. `.no-harness` and friends are decisions of one
+//   machine (see targets/opt-outs.js), and committing them would impose one laptop's answer on
+//   every future clone. They stay local, and never reach the declaration.
 function localDecisions(cwd) {
   const dir = join(cwd, '.rsc');
-  let optOuts = [];
+  let optOuts = null;
   try {
-    optOuts = readdirSync(dir).filter((f) => f.startsWith('.no-')).map((f) => f.slice(4)).sort();
-  } catch { /* no .rsc yet */ }
+    optOuts = projectOptOuts(readdirSync(dir).filter((f) => f.startsWith('.no-')).map((f) => f.slice(4)));
+  } catch { /* no .rsc yet → null, meaning "unknown", never "none" */ }
   let tier = null;
   try { tier = JSON.parse(readFileSync(join(dir, 'developer.json'), 'utf8')).tier ?? null; } catch { /* unset */ }
   return { optOuts, tier };
 }
 
+// The other half of the same promise: what the declaration says is rebuilt as the real local
+// state a hook can see. Hooks are materialized standalone under `.rsc/` and decide with one
+// `existsSync` — they cannot read the manifest, and making them read it would let a `git pull`
+// change how somebody's session behaves in silence, which `project-manifest` ruled out on
+// purpose. So the manifest is applied HERE, inside the install the person chose to run.
+//
+// Only ever on a machine where `.rsc/` did not exist: there, "no marker" carries no information
+// and the declaration is all there is. Where `.rsc/` is already built, the local state is the
+// authority — otherwise the next sync would silently undo a re-arm, and the gate coming back
+// would look like a bug in the guard rather than a decision nobody made.
+export function hydrateLocalDecisions(cwd, manifest) {
+  const applied = { optOuts: [], tier: null };
+  if (!manifest) return applied;
+  const dir = join(cwd, '.rsc');
+  for (const name of projectOptOuts(manifest.optOuts)) {
+    const file = join(dir, `.no-${name}`);
+    if (existsSync(file)) continue;
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(file, `Declared in .rsc.json by this project; rebuilt here by rsc ${CLI_VERSION}.\n`);
+    applied.optOuts.push(name);
+  }
+  if (manifest.tier && !existsSync(join(dir, 'developer.json'))) {
+    applied.tier = writeDeveloperTier(cwd, manifest.tier);
+  }
+  return applied;
+}
+
 // Record the decision, merging so a second assistant never erases the first: installing
 // into codex on a machine that already had claude is adding, not replacing. Union, sorted
 // where order carries no meaning, so the file stays diffable and a merge conflict stays
@@ -146,17 +201,25 @@ export function recordInManifest({ cwd, target, skillIds, agentIds = [], catalog
     ownSkills: prev.ownSkills || [],
     catalogVersion,
     tier: tier ?? prev.tier ?? null,
-    optOuts: optOuts.length ? optOuts : (prev.optOuts || []),
+    optOuts: optOuts ?? projectOptOuts(prev.optOuts),
     memory: prev.memory,
     onboarding: onboarding ?? prev.onboarding,
   });
 }
 
 export async function applyInstall({ skillIds = [], agentIds = [], target, home, cwd = process.cwd(), operation = 'install', dryRun = false, policy, onboarding }) {
+  // Read BEFORE anything can create it — the backup writes under `.rsc/`, and one line later the
+  // answer would always be "yes, it exists". This single boolean is what separates a clone (the
+  // declaration is the only thing that knows what the team decided) from a built machine (the
+  // local markers are the authority, and a pull must not overwrite them).
+  const fromScratch = !existsSync(join(cwd, '.rsc'));
   const paths = targetPaths(target, home, cwd);
   const plan = planInstall({ skillIds, target, home, cwd, hooks: policy?.alwaysOn !== false });
   const managedPaths = managedPathsForInstall({ skillIds, agentIds, target, home, cwd, policy });
   if (dryRun) return { dryRun: true, skills: skillIds, agents: agentIds, paths: managedPaths };
+  // Rebuild the declared decisions first, so everything below (the agent tier especially) reads
+  // the state the team declared rather than the default it would otherwise assume.
+  if (fromScratch) hydrateLocalDecisions(cwd, readManifest(cwd));
   const state = readState(paths.stateFile);
   const backup = createBackup({ cwd, operation, target, paths: managedPaths, cliVersion: CLI_VERSION });
   // Decide base refresh per skill (see baseVersionsFile): a base is re-materialized when
@@ -219,6 +282,7 @@ export async function applyInstall({ skillIds = [], agentIds = [], target, home,
     baseAgents: policy.baseAgents !== false,
     alwaysOn: policy.alwaysOn !== false,
     codeHooks: policy.codeHooks !== false,
+    dangerGuard: policy.dangerGuard !== false,
     gitmojiGuard: policy.gitmojiGuard !== false,
     memory: policy.memory !== false,
     context7: policy.context7 === true,
@@ -237,8 +301,30 @@ export async function applyInstall({ skillIds = [], agentIds = [], target, home,
   mkdirSync(dirname(versionFile(cwd)), { recursive: true });
   writeFileSync(versionFile(cwd), CLI_VERSION + '\n');
   recordInManifest({ cwd, target, skillIds, agentIds, onboarding });
+  // The worktree cleanup's trigger. It lives in `.git/hooks/`, which is NOT cloned, so it has to be
+  // (re)written by every operation that touches a user's repo — install, sync and repair all land
+  // here. Target-agnostic on purpose: it is a git hook, not an assistant hook, and a cleanup that
+  // only worked for one of the sixteen assistants would be a cleanup nobody could rely on. The
+  // reaper travels with it for the same reason; until now only the Claude adapter materialized it,
+  // although `managedPathsForInstall` has always declared it for every target.
+  // Only where the accepted plan governs code hooks. An operations harness — company, research,
+  // content — declares a narrower set of paths, and writing a git hook it never agreed to would be
+  // acting outside the plan the user accepted (P4). Caught by the onboarding route-inventory gate,
+  // which is exactly the kind of catch that justifies its existence.
+  // The answer used to be discarded, so a hook that could not arm looked exactly like one that
+  // did — and the only place that could have noticed, `doctor`, was reading the same wrong path.
+  // Reported 2026-09-18. Carried out, never thrown: the harness installing is the point, and the
+  // merge hook is a convenience layered on top of it.
+  let mergeHook = { installed: false, state: 'skipped' };
+  try {
+    if (policy?.codeHooks === false) throw new Error('code hooks not governed by the accepted plan');
+    mkdirSync(join(cwd, '.rsc'), { recursive: true });
+    cpSync(join(ROOT, 'targets', 'worktree-reaper.mjs'), join(cwd, '.rsc', 'worktree-reaper.mjs'));
+    const { installMergeHook } = await import('../targets/worktree-reaper.mjs');
+    if (existsSync(join(cwd, '.git'))) mergeHook = installMergeHook(cwd);
+  } catch (err) { mergeHook = { installed: false, state: 'skipped', reason: err.message }; }
   ignoreLocalState(cwd, target);
-  return { ...state, backup };
+  return { ...state, backup, mergeHook };
 }
 
 // `.rsc/` holds local machine state — hook scripts, install markers, the sello's
@@ -287,13 +373,51 @@ export function ignoreLocalState(cwd = process.cwd(), target) {
   // keeps this idempotent against a .gitignore a human wrote in their own spelling.
   const norm = (l) => l.trim().replace(/^\//, '').replace(/\/$/, '');
   const present = new Set(text.split('\n').map(norm));
+  // `.rsc/` is machine state and stays ignored. The two files below are the opposite: they are the
+  // whole reason a clone can help itself, and a project that excluded the assistant's directory
+  // wholesale (rsc's own repo does exactly that, so copying the example is likely) swallows both with
+  // no symptom at all.
+  //
+  // Asked of GIT, not of the pattern. The first attempt at this reasoned about spellings and shipped
+  // a negation that was INERT in every case it fired: git does not descend into an excluded
+  // directory, so `!.claude/rsc-bootstrap.mjs` under `.claude/` rescues nothing. Measured, not
+  // argued — and the lesson is the one this repo keeps relearning, that a rule believed and untrue is
+  // worse than no rule.
+  const RESCUE = ['.claude/rsc-bootstrap.mjs', '.claude/settings.json'];
+  const swallowed = RESCUE.filter((f) => {
+    try {
+      return spawnSync('git', ['check-ignore', '-q', '--', f], { cwd }).status === 0;
+    } catch {
+      return false;
+    }
+  });
+  if (swallowed.length) {
+    // Append-only, and this exact order is what makes it work at all: re-include the directory so git
+    // will descend into it, exclude everything inside it again, then rescue by name. Verified against
+    // git itself — `settings.local.json` and the skill entries stay ignored.
+    const dir = swallowed[0].split('/')[0];
+    for (const line of [`!${dir}/`, `${dir}/*`, ...swallowed.map((f) => `!${f}`)]) wanted.push(line);
+  }
+
   const add = wanted.filter((w) => !present.has(norm(w)));
-  if (!add.length) return null;
+  // Every append used to open a new block with its own header, so a project synced across a dozen
+  // versions carried a dozen copies of it. Adjacent rsc blocks are one block: fold them (only our
+  // header lines and the blank seams between our blocks go; every entry stays, in order).
+  const folded = foldIgnoreBlocks(text);
+  if (!add.length) {
+    if (folded === text) return null;
+    try { writeFileSync(gi, folded); return gi; } catch { return null; }
+  }
 
-  // Append only. Never rewrite, never reorder: the rest of that file is theirs.
-  const prefix = text === '' ? '' : (text.endsWith('\n') ? '' : '\n');
+  // Never reorder, never touch a line of theirs. When the file already ends with our block, the new
+  // entries join it; otherwise they open one.
+  const base = folded === '' || folded.endsWith('\n') ? folded : `${folded}\n`;
+  const next = endsWithIgnoreBlock(base)
+    ? `${base}${add.join('\n')}\n`
+    : `${base}${base === '' ? '' : '\n'}${RSC_IGNORE_HEADER}\n${add.join('\n')}\n`;
   try {
-    appendFileSync(gi, `${prefix}\n# rsc local state (hooks, seals, logs) and managed skill links — machine-local\n${add.join('\n')}\n`);
+    if (folded === text && next.startsWith(text)) appendFileSync(gi, next.slice(text.length));
+    else writeFileSync(gi, next);
     if (target) {
       const statePath = targetPaths(target, undefined, cwd).stateFile;
       const state = readState(statePath);
@@ -310,6 +434,14 @@ export function collisions({ cwd = process.cwd(), target, home, skillIds = [] })
   return skillIds.filter((id) => !managed.has(id) && existsSync(paths.skillDir(id)));
 }
 
+// The same test as `collisions`, across every target of a plan, as the paths the user would recognise.
+// `onboard` puts these in the plan itself, so the id the user accepts is an id that names them.
+export function ownSkillPaths({ cwd = process.cwd(), targets = [], skillIds = [], home }) {
+  const found = targets.flatMap((target) => collisions({ cwd, target, home, skillIds })
+    .map((id) => relative(cwd, targetPaths(target, home, cwd).skillDir(id)).split(sep).join('/')));
+  return [...new Set(found)].sort();
+}
+
 export function listInstalled({ target, home, cwd = process.cwd() }) {
   const paths = targetPaths(target, home, cwd);
   return Object.keys(readState(paths.stateFile).skills);
@@ -482,7 +614,19 @@ export async function syncInstalled({ target, home, cwd = process.cwd(), dryRun
   const ids = Object.keys(state.skills || {});
   const manifest = readManifest(cwd);
   const governedSkills = manifest?.onboarding?.plan?.policy?.skills;
-  const declared = governedSkills || (ids.length ? ids : (manifest?.skills || []));
+  // The accepted plan is a FLOOR, not a ceiling. Reading it as the whole declaration is what deleted
+  // users' skills: `add` recorded the new skill in `manifest.skills` — the living list — and sync
+  // then rebuilt from a governed list that predated it and pruned the difference, recursively.
+  // Reported by a user and reproduced 2026-09-17. The receipt stays untouched, because it is
+  // hash-checked against what the user accepted and is not a log of what happened since.
+  const declaredRaw = governedSkills
+    ? [...new Set([...governedSkills, ...(manifest?.skills || [])])].sort()
+    : (ids.length ? ids : (manifest?.skills || []));
+  // A declaration is frozen at the moment it was written, so a skill the catalog later makes
+  // mandatory never reaches an existing harness: `add` and `install` apply the floor, sync did
+  // not, and sync is the only one an upgrade runs. Applied only to a harness that already declares
+  // something: a directory declaring nothing is not a harness missing its floor.
+  const declared = declaredRaw.length ? withDefaultSkillFloor(declaredRaw) : declaredRaw;
   const declaredAgents = state.explicitAgents?.length ? state.explicitAgents : (manifest?.agents || []);
   if (!declared.length && !declaredAgents.length) return dryRun ? { dryRun: true, synced: [], syncedAgents: [], paths: [] } : { synced: [], syncedAgents: [], backup: null };
   if (dryRun) {
@@ -512,6 +656,43 @@ export async function syncInstalled({ target, home, cwd = process.cwd(), dryRun
 // own knowledge — kept unless `withDocs` is set. Returns the paths touched.
 // Note: backups live under `.rsc/backups/`, which this removes — so purge does not
 // snapshot (a pre-purge backup would delete itself). It is the deliberate escape hatch.
+const RSC_IGNORE_HEADER = '# rsc local state (hooks, seals, logs) and managed skill links — machine-local';
+
+// Merge consecutive rsc blocks into the first: drop a repeated header and the blank seam before it
+// when the block above was ours too. A block of the user's in between ends ours, so nothing of
+// theirs is ever moved or absorbed.
+export function foldIgnoreBlocks(text) {
+  const out = [];
+  let ours = false;
+  let afterBlank = false;
+  for (const line of text.split('\n')) {
+    if (line === RSC_IGNORE_HEADER) {
+      if (ours && afterBlank) {
+        while (out.length && out[out.length - 1].trim() === '') out.pop();
+        afterBlank = false;
+        continue;
+      }
+      ours = true;
+    } else if (line.trim() === '') {
+      afterBlank = true;
+      out.push(line);
+      continue;
+    } else if (afterBlank) {
+      ours = false;
+    }
+    afterBlank = false;
+    out.push(line);
+  }
+  return out.join('\n');
+}
+
+function endsWithIgnoreBlock(text) {
+  const lines = text.replace(/\n+$/, '').split('\n');
+  let i = lines.length - 1;
+  while (i > 0 && lines[i - 1].trim() !== '') i -= 1;
+  return lines[i] === RSC_IGNORE_HEADER;
+}
+
 export async function purge({ home, cwd = process.cwd(), withDocs = false, dryRun = false } = {}) {
   const removed = [];
   const drop = (p, recursive = false) => {

package/scripts/lib/backups.js

@@ -40,6 +40,19 @@ export function createBackup({ cwd = process.cwd(), operation, target, paths, cl
   return manifest;
 }
 
+// Where the newest snapshot kept a path, relative to the project — what to tell someone whose own work
+// was just replaced, so recovering it is a copy they can find rather than a restore they never heard of.
+// A transaction snapshot is the fallback: it is the install's rollback, not the user's copy.
+export function whereKept({ cwd = process.cwd(), relPath }) {
+  const backups = listBackups({ cwd });
+  const ordered = [...backups.filter((b) => !/transaction/.test(b.operation)), ...backups.filter((b) => /transaction/.test(b.operation))];
+  for (const b of ordered) {
+    const kept = join(backupsDir(cwd), b.id, 'files', relPath);
+    if (existsSync(kept)) return relative(cwd, kept).split(sep).join('/');
+  }
+  return null;
+}
+
 export function listBackups({ cwd = process.cwd() } = {}) {
   const dir = backupsDir(cwd);
   if (!existsSync(dir)) return [];

package/scripts/lib/capabilities.js

@@ -44,6 +44,12 @@ function agentSpecFor(target, root) {
   return { dir: dirname(p), ext };
 }
 
+// A real file, or a link that leads to one. `statSync` follows; a dangling link throws and is
+// therefore not a file, which is the answer we want.
+function isFile(path) {
+  try { return statSync(path).isFile(); } catch { return false; }
+}
+
 // Real files only. Directories (a dir named `foo.md` is not an agent), dangling
 // symlinks and dotfiles are not capabilities.
 function entriesWithExt(dir, ext) {
@@ -96,8 +102,19 @@ export function listSkills({ target, home, cwd = process.cwd() } = {}) {
     try {
       for (const e of readdirSync(paths.dir, { withFileTypes: true })) {
         if (e.name.startsWith('.')) continue;
-        if (ext) { if (e.isFile() && e.name.endsWith(ext)) out.push({ id: e.name.slice(0, -ext.length), scope }); }
-        else if (e.isDirectory() && existsSync(join(paths.dir, e.name, 'SKILL.md'))) out.push({ id: e.name, scope });
+        // Ask what a skill IS, never how it was put on disk. A `Dirent` from `withFileTypes`
+        // describes the LINK and not its target, so `isDirectory()`/`isFile()` are both false for
+        // every skill on macOS and Linux — where a symlink per assistant, pointing at one shared
+        // copy, is the layout the installer deliberately writes. Windows gets real files (relative
+        // dir symlinks need Developer Mode there), which is why this read as correct for so long
+        // and why CI never caught it.
+        //
+        // `existsSync` and `statSync` follow links on their own, so one question answers all three
+        // platforms with no branch: is there a SKILL.md behind this name? Following a link is not
+        // the same as believing anything — a dangling link, a directory with no SKILL.md and a
+        // plain file all still fail it.
+        if (ext) { if (e.name.endsWith(ext) && isFile(join(paths.dir, e.name))) out.push({ id: e.name.slice(0, -ext.length), scope }); }
+        else if (existsSync(join(paths.dir, e.name, 'SKILL.md'))) out.push({ id: e.name, scope });
       }
     } catch { /* unreadable scope → contributes nothing */ }
   }

package/scripts/lib/divergence.js

@@ -2,6 +2,7 @@ import { readManifest } from './manifest-file.js';
 import { readState } from './state.js';
 import { targetPaths } from '../../targets/index.js';
 import { existsSync } from 'node:fs';
+import { DEFAULT_SKILL_FLOOR } from './default-skill-floor.js';
 
 // What the team declared versus what is on this machine.
 //
@@ -15,10 +16,13 @@ import { existsSync } from 'node:fs';
 //   ownMissing — declared team skill, absent from the repo. Aligning says so and writes
 //                nothing: it comes from the repo, not from us.
 //   extra      — installed BY RSC, no longer declared.
+//   floorMissing — a skill the catalog makes mandatory that this declaration predates.
+//                Not drift between teammates: drift between the harness and the catalog,
+//                and the only bucket that survives everyone running the same `git pull`.
 // A hand-written skill that nobody declared is in none of them. Not declaring is a valid
 // way to keep things of your own, not an oversight to correct.
 export function divergence({ cwd = process.cwd(), target, home } = {}) {
-  const empty = { missing: [], extra: [], ownMissing: [] };
+  const empty = { missing: [], extra: [], ownMissing: [], floorMissing: [] };
   const manifest = readManifest(cwd);
   if (!manifest) return empty;
 
@@ -29,5 +33,8 @@ export function divergence({ cwd = process.cwd(), target, home } = {}) {
     missing: (manifest.skills || []).filter((id) => !installed.has(id)),
     extra: [...installed].filter((id) => !(manifest.skills || []).includes(id)),
     ownMissing: (manifest.ownSkills || []).filter((name) => !existsSync(paths.skillDir(name))),
+    // Read off the declaration, not off the disk: a skill installed by hand into a harness
+    // that still does not declare it is one sync away from being pruned again.
+    floorMissing: DEFAULT_SKILL_FLOOR.filter((id) => !(manifest.skills || []).includes(id)),
   };
 }

package/scripts/lib/onboarding-apply.js

@@ -4,6 +4,7 @@ import { dirname, join, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { applyInstall, pruneSharedBases, removeTargetInstall } from '../install-apply.js';
 import { targetPaths } from '../../targets/index.js';
+import { targetHasAgents } from '../../targets/agents.js';
 import { readState } from './state.js';
 import { readManifest, writeManifest } from './manifest-file.js';
 import { encodeGoal, identifyPlan } from './onboarding.js';
@@ -11,6 +12,22 @@ import { createBackup, restoreBackup } from './backups.js';
 
 const sameSet = (a = [], b = []) => JSON.stringify([...a].sort()) === JSON.stringify([...b].sort());
 
+/**
+ * What THIS target should be holding, which is not the same question as what the project decided.
+ *
+ * The policy is the PROJECT's: "these are the agents this project wants." Whether an assistant can
+ * hold a subagent at all is the TARGET's business, and nine of the seventeen cannot — amp, jules,
+ * zed, antigravity, windsurf, cline, roo, continue and aider have no such concept. The installer
+ * always knew this and correctly wrote none; the verifier did not, and demanded the project's list
+ * from every target, so onboarding could never complete on any of the nine. Since the failure rolls
+ * back, what the person got was empty directory shells and no harness — with a recovery command
+ * that leads straight back to the same wall.
+ *
+ * Asking amp for a subagent is not a divergence. It is a category error, and this is where the two
+ * categories stop being confused.
+ */
+export const expectedAgentsFor = (target, plan) => (targetHasAgents(target) ? (plan.policy.agents || []) : []);
+
 function inside(root, path) {
   return path === root || path.startsWith(`${root}${sep}`);
 }
@@ -66,18 +83,69 @@ function recoveryCommand(plan, planId) {
 }
 
 export function renderOnboardingDocuments(plan, planId) {
-  const profile = `---\ntechnical_level: ${plan.record.technicalLevel}\naccompaniment: ${plan.record.accompaniment}\nproject_kind: ${plan.record.projectKind}\n---\n\n# User profile\n\nGoal: ${plan.record.goal}\n`;
+  // `accompaniment_level`, never `accompaniment` (#276). It sits beside `technical_level` in the same
+  // block, and it is the name the nine skill files that read the dial — orient first among them —
+  // have always used. This was the only writer of the short form, which left the dial chosen at
+  // onboarding invisible to the compass.
+  const profile = `---\ntechnical_level: ${plan.record.technicalLevel}\naccompaniment_level: ${plan.record.accompaniment}\nproject_kind: ${plan.record.projectKind}\n---\n\n# User profile\n\nGoal: ${plan.record.goal}\n`;
   const rows = plan.decisions.map((d) => `| ${d.kind} | ${d.id} | ${d.state} | ${d.reason} | ${d.reevaluateWhen.join('; ') || '—'} |`).join('\n');
   const installation = `# Accepted harness plan\n\nPlan id: \`${planId}\`\n\n| Kind | Component | Decision | Reason | Reevaluate when |\n| --- | --- | --- | --- | --- |\n${rows}\n`;
   const decisions = `# Harness decisions\n\n- Accepted plan \`${planId}\`.\n- Project kind: ${plan.record.projectKind}.\n- SDD: ${plan.decisions.find((d) => d.id === 'sdd')?.state || 'selected through profile'}.\n`;
   return { profile, installation, decisions };
 }
 
-export function writeOnboardingDocuments(cwd, plan, planId) {
+const PROFILE_DIALS = [['technical_level', 'technicalLevel'], ['accompaniment_level', 'accompaniment']];
+
+/**
+ * The profile is the USER's file; accepting a plan seeds it, it does not own it (#278).
+ *
+ * `init` records there what it learns — the domain, the tools, what must not be touched — and `orient`
+ * rewrites the dial when someone asks for more or less explanation. Regenerating the file on every
+ * accept erased both, and re-accepting is routine: after an update, after a reassess.
+ *
+ * So: everything the plan does not own is kept byte for byte. `project_kind` and the goal are facts of
+ * the plan and are updated. The two dials are the subtle part — the plan carries them, but after first
+ * contact the user adjusts them — so an existing value stands when the plan did not CHANGE it relative
+ * to the previous receipt, and an explicit new value (a receipt that said L3, a plan that says L2) is
+ * applied. A profile written before the rename carries `accompaniment:`; it is migrated, never
+ * duplicated.
+ */
+export function mergeProfile(existing, plan, previousRecord) {
+  const fresh = renderOnboardingDocuments(plan, '').profile;
+  if (!existing || !existing.trim()) return fresh;
+  const text = existing.replace(/\r\n/g, '\n');
+  const block = /^---\n([\s\S]*?)\n---\n?/.exec(text);
+  let front = block ? block[1].split('\n') : [];
+  let body = block ? text.slice(block[0].length) : text;
+  const has = (key) => front.some((line) => line.startsWith(`${key}:`));
+  front = has('accompaniment_level')
+    ? front.filter((line) => !/^accompaniment:\s/.test(line))
+    : front.map((line) => line.replace(/^accompaniment:(\s)/, 'accompaniment_level:$1'));
+  const get = (key) => front.find((line) => line.startsWith(`${key}:`))?.slice(key.length + 1).trim() || null;
+  const set = (key, value) => {
+    const at = front.findIndex((line) => line.startsWith(`${key}:`));
+    if (at >= 0) front[at] = `${key}: ${value}`;
+    else front.push(`${key}: ${value}`);
+  };
+  for (const [key, field] of PROFILE_DIALS) {
+    const planned = plan.record[field];
+    const keptByUser = get(key) && previousRecord && previousRecord[field] === planned;
+    if (!keptByUser) set(key, planned);
+  }
+  set('project_kind', plan.record.projectKind);
+  const goal = `Goal: ${plan.record.goal}`;
+  if (/^Goal: .*$/m.test(body)) body = body.replace(/^Goal: .*$/m, () => goal);
+  else if (/^# User profile[ \t]*$/m.test(body)) body = body.replace(/^# User profile[ \t]*$/m, () => `# User profile\n\n${goal}`);
+  else body = `${body.replace(/\s*$/, '')}\n\n${goal}\n`;
+  return `---\n${front.join('\n')}\n---\n${body.startsWith('\n') ? '' : '\n'}${body}`;
+}
+
+export function writeOnboardingDocuments(cwd, plan, planId, previousRecord = null) {
   const dir = join(cwd, 'docs', 'wiki', 'harness');
   mkdirSync(dir, { recursive: true });
   const docs = renderOnboardingDocuments(plan, planId);
-  writeFileSync(join(dir, 'user-profile.md'), docs.profile);
+  const profilePath = join(dir, 'user-profile.md');
+  writeFileSync(profilePath, mergeProfile(existsSync(profilePath) ? readFileSync(profilePath, 'utf8') : '', plan, previousRecord));
   writeFileSync(join(dir, 'installation-plan.md'), docs.installation);
   const decisionsPath = join(dir, 'decisions.md');
   if (!existsSync(decisionsPath)) writeFileSync(decisionsPath, docs.decisions);
@@ -92,7 +160,7 @@ export function verifyOnboarding(cwd, plan, planId) {
   for (const target of plan.policy.targets) {
     const state = readState(targetPaths(target, undefined, cwd).stateFile);
     if (!sameSet(Object.keys(state.skills || {}), plan.policy.skills)) differences.push(`${target}: installed skills differ from accepted policy`);
-    if (!sameSet(state.agents || [], plan.policy.agents || [])) differences.push(`${target}: installed agents differ from accepted policy`);
+    if (!sameSet(state.agents || [], expectedAgentsFor(target, plan))) differences.push(`${target}: installed agents differ from accepted policy`);
     if (state.policy?.alwaysOn !== plan.policy.alwaysOn) differences.push(`${target}: always-on policy differs`);
     if (state.policy?.codeHooks !== plan.policy.codeHooks) differences.push(`${target}: code-hook policy differs`);
     if (state.policy?.memory !== plan.policy.memory) differences.push(`${target}: memory policy differs`);
@@ -117,12 +185,15 @@ export function verifyOnboarding(cwd, plan, planId) {
   }
   const docsDir = join(cwd, 'docs', 'wiki', 'harness');
   const profile = existsSync(join(docsDir, 'user-profile.md')) ? readFileSync(join(docsDir, 'user-profile.md'), 'utf8') : '';
-  for (const line of [
-    `technical_level: ${plan.record.technicalLevel}`,
-    `accompaniment: ${plan.record.accompaniment}`,
-    `project_kind: ${plan.record.projectKind}`,
-    `Goal: ${plan.record.goal}`,
-  ]) if (!profile.split('\n').includes(line)) differences.push(`profile content differs: ${line.split(':')[0]}`);
+  // The plan's facts must be exactly there. The dials must be there under their one name with a valid
+  // value — not necessarily the plan's, because a dial the user adjusted and the plan did not change
+  // is theirs (see mergeProfile).
+  for (const line of [`project_kind: ${plan.record.projectKind}`, `Goal: ${plan.record.goal}`]) {
+    if (!profile.split('\n').includes(line)) differences.push(`profile content differs: ${line.split(':')[0]}`);
+  }
+  if (!/^technical_level: (non-technical|mixed|technical)$/m.test(profile)) differences.push('profile content differs: technical_level');
+  if (!/^accompaniment_level: L[0-3]$/m.test(profile)) differences.push('profile content differs: accompaniment_level');
+  if (/^accompaniment: /m.test(profile)) differences.push('profile carries the retired accompaniment key');
   const installation = existsSync(join(docsDir, 'installation-plan.md')) ? readFileSync(join(docsDir, 'installation-plan.md'), 'utf8') : '';
   if (!installation.includes(`Plan id: \`${planId}\``)) differences.push('installation plan identity differs');
   for (const decision of plan.decisions || []) {
@@ -131,7 +202,8 @@ export function verifyOnboarding(cwd, plan, planId) {
   }
   const decisions = existsSync(join(docsDir, 'decisions.md')) ? readFileSync(join(docsDir, 'decisions.md'), 'utf8') : '';
   if (!decisions.includes(`Accepted plan \`${planId}\``)) differences.push('decision ledger omits accepted plan');
-  if (!sameSet(manifest?.targets || [], plan.policy.targets)) differences.push('manifest targets differ from accepted policy');
+  // Every planned assistant is declared; an extra one added outside the plan may be too (#278).
+  if (!plan.policy.targets.every((t) => (manifest?.targets || []).includes(t))) differences.push('manifest targets differ from accepted policy');
   if (!sameSet(manifest?.skills || [], plan.policy.skills)) differences.push('manifest skills differ from accepted policy');
   if (!sameSet(manifest?.agents || [], plan.policy.agents || [])) differences.push('manifest agents differ from accepted policy');
   return differences;
@@ -183,7 +255,7 @@ export async function applyAcceptedOnboarding({ cwd = process.cwd(), plan, planI
       });
     }
     pruneSharedBases({ cwd, skillIds: plan.policy.skills });
-    writeOnboardingDocuments(cwd, plan, planId);
+    writeOnboardingDocuments(cwd, plan, planId, previousPlan?.record || null);
     receipt.provenance.paths = Object.fromEntries((plan.governedPaths || []).map((path) => [
       path,
       existed[path] ? (previousReceipt ? 'conserved' : 'preexisting') : 'installed',
@@ -192,7 +264,13 @@ export async function applyAcceptedOnboarding({ cwd = process.cwd(), plan, planI
     const manifest = readManifest(cwd);
     writeManifest(cwd, {
       ...manifest,
-      targets: [...plan.policy.targets],
+      // Union, with the distinction the removal loop above already makes (#278). An assistant that was
+      // in the previous PLAN and is not in this one was removed on purpose. One added OUTSIDE the plan
+      // — `sync --target codex` — is still installed, and dropping it from the declaration meant a
+      // clone would never build it again.
+      targets: [...plan.policy.targets, ...(previousManifest?.targets || []).filter((t) => !plan.policy.targets.includes(t)
+        && !(previousPlan?.policy?.targets || []).includes(t)
+        && existsSync(targetPaths(t, undefined, cwd).stateFile))],
       skills: [...plan.policy.skills],
       agents: [...(plan.policy.agents || [])],
       onboarding: receipt,