agents-handoff 2.0.2 → 2.0.4

package/install/install.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// agents-handoff - npx installer for the agent-handoff skill
+// agents-handoff - npx installer for the agents-handoff skill
 // Commands: install, update, remove, verify, list
 // Zero external dependencies, pure Node.js
 import fs from 'node:fs';
@@ -16,8 +16,19 @@ const INSTALLER_ROOT = path.resolve(__dirname);
 // archive: the parent of install/. A published package has no parent tree, so this path is
 // also the test that decides between copying files and fetching an archive.
 const SOURCE_DIR = path.resolve(INSTALLER_ROOT, '..');
-const SKILL_NAME = 'agent-handoff';
+const SKILL_NAME = 'agents-handoff';
+// The directory name every release before 2.0.3 installed under. An upgraded machine holds these
+// in exactly the places a new install would go, so the search looks for both names: `--update`
+// and `--verify` act on a pre-rename copy in place instead of reporting that nothing is
+// installed while it sits right there. A NEW install always uses SKILL_NAME.
+const LEGACY_SKILL_NAME = 'agent-handoff';
+// The npm package users `npx`. Same name as the product, and the reason the install record can
+// verify an installation against the tarball npm is actually serving.
+const NPM_PACKAGE = 'agents-handoff';
+const REGISTRY = 'https://registry.npmjs.org';
 const REPO_OWNER = 'Alot1z';
+// The PRODUCT is agents-handoff; the REPOSITORY is still Alot1z/agent-handoff. The two names
+// are not the same string, and this constant is the one place the repository's name lives.
 const REPO_NAME = 'agent-handoff';
 const RELEASES_URL = `https://github.com/${REPO_OWNER}/${REPO_NAME}/releases/download`;
 const TARBALL_URL = `https://codeload.github.com/${REPO_OWNER}/${REPO_NAME}/tar.gz`;
@@ -27,7 +38,7 @@ const API_LATEST = `https://api.github.com/repos/${REPO_OWNER}/${REPO_NAME}/rele
 // `list` read back out of an installed copy. The literal below is only the fallback for the
 // run that has no tree beside it — the published package fetching an archive — and the suite
 // asserts it against SKILL.md, so a release that bumps one cannot leave the other behind.
-const FALLBACK_SKILL_VERSION = '2.0.2';
+const FALLBACK_SKILL_VERSION = '2.0.4';
 function skillVersion() {
   try {
     const md = fs.readFileSync(path.join(SOURCE_DIR, 'SKILL.md'), 'utf8');
@@ -53,7 +64,7 @@ const HOME = process.env.USERPROFILE || process.env.HOME || '';
 // Where a GLOBAL install can go. Desktop clients keep account skills in their own store with
 // two opaque id levels between the store and the skill:
 //
-//     <store>/<account-id>/<profile-id>/agent-handoff/
+//     <store>/<account-id>/<profile-id>/agents-handoff/
 //
 // No client is named here. A store is DISCOVERED by looking for `account-skills` directories
 // under the platform's application-data roots, so a client that is absent from this machine
@@ -61,7 +72,16 @@ const HOME = process.env.USERPROFILE || process.env.HOME || '';
 // `resolveGlobalRoot` picks one and says why. `AGENT_HANDOFF_GLOBAL_DIR` overrides the
 // search; `--path` bypasses it.
 const DATA_ROOTS = (process.platform === 'win32'
-  ? [process.env.APPDATA, process.env.LOCALAPPDATA, path.join(HOME, 'AppData', 'Roaming')]
+  ? [
+    process.env.APPDATA,
+    process.env.LOCALAPPDATA,
+    path.join(HOME, 'AppData', 'Roaming'),
+    // A desktop client keeps its account-skill store under ~/.config even on Windows, where
+    // that directory is not an application-data root at all. Leaving it out is not a cosmetic
+    // gap: the machine's real installation is then invisible to every command that resolves a
+    // global root or searches for installations, while the store it lives in keeps working.
+    path.join(HOME, '.config'),
+  ]
   : [path.join(HOME, '.config'), path.join(HOME, '.local', 'share')]
 ).filter(Boolean);
 const AGENTS_SKILLS = path.join(HOME, '.agents', 'skills');
@@ -92,7 +112,7 @@ function accountSkillStores() {
   return [...new Set(out)];
 }
 
-// Every directory that could be the PARENT of a global agent-handoff/, from every account
+// Every directory that could be the PARENT of a global agents-handoff/, from every account
 // store this machine has.
 function accountSkillRoots() {
   const stores = accountSkillStores();
@@ -108,7 +128,7 @@ function accountSkillRoots() {
 
 // Resolution order, first hit wins:
 //   1. AGENT_HANDOFF_GLOBAL_DIR                 — explicit operator override
-//   2. an account-skill root that ALREADY holds agent-handoff (newest install first)
+//   2. an account-skill root that ALREADY holds agents-handoff (newest install first)
 //   3. ~/.agents/skills                         — the harness-wide skills home
 //   4. any account-skill root discovered above  — keeps the install where a client reads
 //   5. ~/.agents/skills                         — created on install when nothing exists
@@ -163,13 +183,38 @@ const hasFlag = (name) => args.includes(name);
 // had to be a bare verb, so every documented flag form exited 1 with "Unknown command".
 const FLAG_COMMANDS = {
   '--install': 'install', '--update': 'update', '--remove': 'remove',
-  '--verify': 'verify', '--list': 'list', '--help': 'help', '-h': 'help'
+  '--verify': 'verify', '--list': 'list', '--doctor': 'doctor',
+  '--verify-package': 'verify-package',
+  '--help': 'help', '-h': 'help'
 };
 const COMMAND = FLAG_COMMANDS[args[0]] || (args[0] && !args[0].startsWith('-') ? args[0] : 'install');
 const LOCATION = getArg('--location', 'global');
 const CUSTOM_PATH = getArg('--path');
 const VERSION = getArg('--version', 'latest');
 const FORCE = hasFlag('--force') || hasFlag('-f');
+const PROJECT_TARGET = hasFlag('--project');
+const PROVENANCE = hasFlag('--provenance');
+// `--record` writes what `verify-package` fetched (tarball sha256/sha512, the registry's
+// integrity string) into the install record, so a later run compares against a stored value
+// instead of re-deriving one.
+const RECORD = hasFlag('--record');
+
+// Which harnesses to install into. `--claude`, `--codex`, `--agents`, `--harness claude,codex`
+// (repeatable) and `--all` (every harness whose home directory exists here). `--skills-dir
+// <path>` (repeatable) targets any other stack exactly. NO harness flag keeps the historical
+// single target: the resolved global root, ./local/skills, ./skills, or --path.
+const HARNESS_FLAGS = { '--claude': 'claude', '--codex': 'codex', '--agents': 'agents' };
+const HARNESSES_CHOSEN = [];
+const SKILLS_DIRS = [];
+for (let i = 0; i < args.length; i += 1) {
+  const a = args[i];
+  if (HARNESS_FLAGS[a]) HARNESSES_CHOSEN.push(HARNESS_FLAGS[a]);
+  else if (a === '--harness') {
+    HARNESSES_CHOSEN.push(...String(args[i + 1] || '').split(',').map(s => s.trim()).filter(Boolean));
+  } else if (a === '--all') HARNESSES_CHOSEN.push('all');
+  else if (a === '--skills-dir') SKILLS_DIRS.push(String(args[i + 1] || ''));
+}
+const MULTI_TARGET = HARNESSES_CHOSEN.length > 0 || SKILLS_DIRS.length > 0;
 
 // THE INSTALL MANIFEST. One list, used to copy AND to verify, so an installed copy
 // cannot silently lose a file the runtime needs (the engine now imports
@@ -188,6 +233,8 @@ const SKILL_FILES = [
   { from: 'handoff.config.schema.json', to: 'handoff.config.schema.json' },
   { from: 'handoff.config.example.json', to: 'handoff.config.example.json' },
   { from: 'tools/handoff.mjs', to: 'tools/handoff.mjs' },
+  { from: 'tools/agents-handoff.mjs', to: 'tools/agents-handoff.mjs' },
+  // The pre-rename runtime path, installed as a forwarder so old notes keep working.
   { from: 'tools/agent-handoff.mjs', to: 'tools/agent-handoff.mjs' },
   { from: 'tools/handoff.test.mjs', to: 'tools/handoff.test.mjs' },
   { from: 'tools/capability-registry.mjs', to: 'tools/capability-registry.mjs' },
@@ -253,7 +300,7 @@ function copyManifest(root, installPath) {
     copied++;
   }
   if (unresolved.length) warn('source file(s) not found: ' + unresolved.join(', '));
-  return copied;
+  return { copied, unresolved };
 }
 
 // The newest published release tag, or null when the repository has none (or the API cannot
@@ -273,7 +320,7 @@ async function latestTag() {
 // Fetch and unpack the archive for the requested version, into a throwaway directory the
 // caller removes. Returns the unpacked root, so the same manifest copies from it.
 async function fetchAndUnpack(version) {
-  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-handoff-fetch-'));
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'agents-handoff-fetch-'));
   let ref, label;
   if (version === 'latest') {
     const tag = await latestTag();
@@ -285,7 +332,7 @@ async function fetchAndUnpack(version) {
     label = 'v' + version;
   }
   const url = `${TARBALL_URL}/${ref}`;
-  const tarball = path.join(tmp, 'agent-handoff.tar.gz');
+  const tarball = path.join(tmp, 'agents-handoff.tar.gz');
   log(`Fetching the ${label} archive...`);
   log(`  ${url}`);
   await downloadFile(url, tarball);
@@ -298,17 +345,24 @@ async function fetchAndUnpack(version) {
   // (`C:\Users\…`) is read by tar as a remote host — `tar (child): Cannot connect to C:
   // resolve failed` — so `-xzf C:\…` fails on the very platform this installer targets first.
   // Relative operands, with cwd doing the locating, work the same in GNU tar and bsdtar.
-  const tar = spawnSync('tar', ['-xzf', 'agent-handoff.tar.gz', '-C', 'unpack', '--strip-components=1'],
+  const tar = spawnSync('tar', ['-xzf', 'agents-handoff.tar.gz', '-C', 'unpack', '--strip-components=1'],
     { cwd: tmp, encoding: 'utf8' });
   if (tar.status !== 0) {
     const why = String(tar.stderr || '').trim().split('\n')[0];
     error(`Cannot extract the archive (tar exited ${tar.status}${why ? ': ' + why : ''}).\n` +
       `  Extract it yourself, then install from the unpacked tree:\n\n` +
-      `    curl -L -o agent-handoff.tar.gz ${url}\n` +
-      `    mkdir -p agent-handoff && tar -xzf agent-handoff.tar.gz -C agent-handoff --strip-components=1\n` +
-      `    node agent-handoff/install/install.mjs`);
+      `    curl -L -o agents-handoff.tar.gz ${url}\n` +
+      `    mkdir -p agents-handoff && tar -xzf agents-handoff.tar.gz -C agents-handoff --strip-components=1\n` +
+      `    node agents-handoff/install/install.mjs`);
   }
-  return { root: unpack, cleanup: () => fs.rmSync(tmp, { recursive: true, force: true }) };
+  return {
+    root: unpack,
+    cleanup: () => fs.rmSync(tmp, { recursive: true, force: true }),
+    ref,
+    label,
+    url,
+    sha256: hash,
+  };
 }
 
 // Resolve install path
@@ -329,6 +383,173 @@ function resolveInstallPath(location, customPath) {
   }
 }
 
+// ---------------------------------------------------------------- harness targets
+// The directories each harness actually reads for personal skills, so an install here needs no
+// configuration afterwards. `--project` switches to the per-repository form, which is what a
+// harness reads when it is run inside that repository.
+//   claude  ~/.claude/skills     Claude Code personal skills     project: ./.claude/skills
+//   codex   ~/.codex/skills      Codex CLI personal skills       project: ./.codex/skills
+//   agents  ~/.agents/skills     harness-neutral store           project: ./.agents/skills
+const HARNESSES = {
+  claude: { user: path.join(HOME, '.claude', 'skills'), project: path.join(process.cwd(), '.claude', 'skills') },
+  codex: { user: path.join(HOME, '.codex', 'skills'), project: path.join(process.cwd(), '.codex', 'skills') },
+  agents: { user: AGENTS_SKILLS, project: path.join(process.cwd(), '.agents', 'skills') },
+};
+
+// A harness is DETECTED when its configuration directory exists. Detection is a suggestion,
+// never a decision: `--all` installs into the detected ones and says which were skipped, and an
+// explicit `--claude` installs there whether or not the directory exists yet.
+function harnessDetected(name) {
+  const home = { claude: '.claude', codex: '.codex', agents: '.agents' }[name];
+  return Boolean(home && fs.existsSync(path.join(HOME, home)));
+}
+
+function dirForHarness(name, projectForm) {
+  const h = HARNESSES[name];
+  if (!h) error(`Unknown harness: ${name}. Known harnesses: ${Object.keys(HARNESSES).join(', ')} (or use --skills-dir <path>)`);
+  return projectForm ? h.project : h.user;
+}
+
+// Every installation target this run will write to, in the order it will write them.
+function resolveTargets() {
+  if (!MULTI_TARGET) {
+    return [{ label: 'resolved target', dir: null, path: resolveInstallPath(LOCATION, CUSTOM_PATH) }];
+  }
+  const targets = [];
+  const names = HARNESSES_CHOSEN.includes('all')
+    ? [...new Set([...HARNESSES_CHOSEN.filter(n => n !== 'all'), ...Object.keys(HARNESSES).filter(harnessDetected)])]
+    : [...new Set(HARNESSES_CHOSEN)];
+  for (const name of names) {
+    if (name === 'all') continue;
+    const dir = dirForHarness(name, PROJECT_TARGET);
+    targets.push({ label: name + (PROJECT_TARGET ? ' (project)' : ''), harness: name, dir, path: path.join(dir, SKILL_NAME) });
+  }
+  for (const d of SKILLS_DIRS) {
+    if (!d) continue;
+    const dir = path.resolve(d);
+    targets.push({ label: 'custom dir ' + dir, dir, path: path.join(dir, SKILL_NAME) });
+  }
+  if (!targets.length) error('no installation targets: pass a harness (--claude, --codex, --agents), --all, or --skills-dir <path>');
+  return targets;
+}
+
+// EVERY installation this machine has, not just the resolved one. `update` and `verify` with no
+// harness flag act on this list, because "keep my install current" is about the copies that
+// exist, not about the one target the resolver happens to pick: a machine can hold the same
+// skill in ~/.claude/skills and ~/.agents/skills, and updating only the resolved one is how a
+// second harness silently keeps an old engine.
+function discoverInstalls() {
+  const out = [];
+  const seen = new Set();
+  const push = (label, dir) => {
+    if (!dir) return;
+    for (const [name, suffix] of [[SKILL_NAME, ''], [LEGACY_SKILL_NAME, ' — pre-2.0.3 name, updated in place']]) {
+      const p = path.join(dir, name);
+      if (seen.has(p)) continue;
+      seen.add(p);
+      if (isInstalled(p)) out.push({ label: label + suffix, dir, path: p });
+    }
+  };
+  const g = resolveGlobalRoot();
+  push('global (resolved: ' + g.why + ')', g.root);
+  push('local', PATHS.local);
+  push('project', PATHS.project);
+  for (const name of Object.keys(HARNESSES)) push('harness ' + name, HARNESSES[name].user);
+  for (const name of Object.keys(HARNESSES)) push('harness ' + name + ' (project)', HARNESSES[name].project);
+  for (const d of accountSkillRoots()) push('account-skill candidate', d);
+  push('harness skills home', AGENTS_SKILLS);
+  for (const d of SKILLS_DIRS) if (d) push('skills-dir ' + d, path.resolve(d));
+  return out;
+}
+
+// ---------------------------------------------------------------- install provenance
+// What landed, and what it was made from. `verify` re-computes the file-set hash and compares
+// it against this record, so an installation can be checked against the tree it was installed
+// from instead of against the manifest alone — and an install that came from a tagged archive
+// can say WHICH archive, by hash.
+const PROVENANCE_FILE = '.agents-handoff-install.json';
+const fileSha256 = (p) => crypto.createHash('sha256').update(fs.readFileSync(p)).digest('hex');
+
+// The file-set hash: every manifest path with its own sha256, sorted, folded into one value.
+// Paths are part of the hash, so a file moved to another name changes it.
+function fileSetHash(installPath) {
+  const parts = [];
+  for (const f of SKILL_FILES.map(x => x.to).sort()) {
+    const abs = path.join(installPath, f);
+    parts.push(f + '\u0000' + (fs.existsSync(abs) ? fileSha256(abs) : 'missing'));
+  }
+  return crypto.createHash('sha256').update(parts.join('\n')).digest('hex');
+}
+
+// The npm identity this install came from. `verify-package` fills in the hashes on first run
+// (they cannot be known while installing from a tree — that is a different artifact from the
+// published tarball), and compares against them afterwards, so an install carries its own
+// record of the package it should match.
+function packageRecord(installPath) {
+  const version = getInstalledVersion(installPath) || null;
+  return {
+    name: NPM_PACKAGE,
+    version,
+    registry: REGISTRY,
+    tarball: version ? `${REGISTRY}/${NPM_PACKAGE}/-/${NPM_PACKAGE}-${version}.tgz` : null,
+    sha256: null,
+    sha512: null,
+    integrity: null,
+    shasum: null,
+    verified_at: null,
+  };
+}
+
+function writeProvenance(installPath, info) {
+  const record = {
+    schema_version: '1.0-install-provenance',
+    product: SKILL_NAME,
+    version: getInstalledVersion(installPath) || info.version || null,
+    installer_version: INSTALLER_VERSION,
+    installed_at: new Date().toISOString(),
+    harness: info.harness || null,
+    target: installPath,
+    source: info.source,
+    package: packageRecord(installPath),
+    file_count: SKILL_FILES.filter(f => fs.existsSync(path.join(installPath, f.to))).length,
+    manifest_entries: SKILL_FILES.length,
+    files_sha256: fileSetHash(installPath),
+    files: Object.fromEntries(SKILL_FILES.map(entry => entry.to).sort().map(rel => [
+      rel,
+      fs.existsSync(path.join(installPath, rel)) ? fileSha256(path.join(installPath, rel)) : 'missing',
+    ])),
+  };
+  fs.writeFileSync(path.join(installPath, PROVENANCE_FILE), JSON.stringify(record, null, 2) + '\n');
+  return record;
+}
+
+function readProvenance(installPath) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(installPath, PROVENANCE_FILE), 'utf8'));
+  } catch { return null; }
+}
+
+// Compare an installation with its own record. Returns the verdict; the caller decides whether
+// a missing record is a failure (it is not: installations predating this feature have none).
+function checkProvenance(installPath) {
+  const record = readProvenance(installPath);
+  if (!record) return { present: false };
+  const actual = fileSetHash(installPath);
+  const changed = [];
+  for (const [rel, want] of Object.entries(record.files || {})) {
+    const abs = path.join(installPath, rel);
+    const have = fs.existsSync(abs) ? fileSha256(abs) : 'missing';
+    if (have !== want) changed.push(rel + ' (' + (have === 'missing' ? 'missing' : 'changed') + ')');
+  }
+  return { present: true, record, match: actual === record.files_sha256, actual, changed };
+}
+
+function describeSource(source) {
+  if (!source) return 'unrecorded';
+  if (source.kind === 'tree') return 'the tree beside the installer (' + (source.path || 'checkout') + ')';
+  return (source.ref || 'archive') + (source.archive_sha256 ? ' archive sha256 ' + source.archive_sha256.slice(0, 16) + '…' : '');
+}
+
 // Check if installed
 function isInstalled(installPath) {
   return fs.existsSync(path.join(installPath, 'SKILL.md'));
@@ -375,57 +596,37 @@ async function downloadFile(url, destPath) {
   throw new Error(`Failed to download from ${url}. Neither fetch, curl, nor wget available.`);
 }
 
-// Download and verify package
-async function downloadAndVerify(installPath, version) {
-  const isLatest = version === 'latest';
-  const zipName = isLatest ? `${SKILL_NAME}-latest.zip` : `${SKILL_NAME}-v${version}.zip`;
-  const zipUrl = isLatest 
-    ? `${RELEASES_URL}/latest/${zipName}`
-    : `${RELEASES_URL}/v${version}/${zipName}`;
-  const zipPath = path.join(installPath, zipName);
-  
-  log(`Downloading ${SKILL_NAME} v${version}...`);
-  
-  try {
-    const data = await downloadFile(zipUrl, zipPath);
-    const hash = crypto.createHash('sha256').update(data).digest('hex');
-    log(`Downloaded: ${hash.slice(0, 16)}...`);
-    return { zipPath, hash, zipUrl };
-  } catch (e) {
-    if (e.message.includes('HTTP 404') || e.message.includes('404')) {
-      error(`Version ${version} not found. Available versions: Check ${RELEASES_URL}`);
-    }
-    throw e;
-  }
-}
+// The zip path a release used to ship (agent-handoff-<tag>.zip, named after the repository) is
+// gone: releases attach that zip for humans, and every automated path uses the tag tarball,
+// which is what an install records when it fetches instead of copying.
 
-// Extract zip (using unzip or native)
-function extractZip(zipPath, destDir) {
-  // Try unzip first
-  const unzip = spawnSync('unzip', ['-o', zipPath, '-d', destDir], { encoding: 'utf8' });
-  if (unzip.status === 0) {
-    return true;
+// Install into every target this run selected: one harness, several at once, or the historical
+// single target. Each target gets its own copy and its own provenance record, so one run can
+// cover Claude Code and Codex without installing twice.
+async function install(location, customPath, version, force) {
+  const targets = resolveTargets();
+  const results = [];
+  for (const [i, target] of targets.entries()) {
+    if (targets.length > 1) log(`\n${C('bold', '── target ' + (i + 1) + ' of ' + targets.length + ': ' + target.label + ' ──')}`);
+    results.push(await installTarget(target, version, force));
   }
-  
-  // Fallback: Node.js doesn't have native unzip, suggest installing unzip
-  error(`Cannot extract zip. Please install 'unzip' or use a different method:
-  
-  # Download manually
-  curl -L -o ${SKILL_NAME}.zip ${zipPath.replace(/\\/g, '\\\\')}
-  unzip ${SKILL_NAME}.zip -d ${destDir}
-  
-  Or download from: ${RELEASES_URL}`);
+  if (targets.length > 1) {
+    log(`\n${C('bold', 'Summary')}`);
+    for (const r of results) {
+      log(`  ${r.skipped ? C('yellow', '–') + ' kept' : C('green', '✓') + ' installed'} ${r.path} — v${r.version}`);
+    }
+  }
+  return results;
 }
 
-// Install skill to path
-async function install(location, customPath, version, force) {
-  const installPath = resolveInstallPath(location, customPath);
+async function installTarget(target, version, force) {
+  const installPath = target.path;
   const alreadyInstalled = isInstalled(installPath);
   const currentVersion = alreadyInstalled ? getInstalledVersion(installPath) : null;
   
-  log(`\n${C('bold', 'agent-handoff installer v' + INSTALLER_VERSION)}`);
-  log(`Target: ${installPath}`);
-  if (!customPath && location === 'global') {
+  log(`\n${C('bold', 'agents-handoff installer v' + INSTALLER_VERSION)}`);
+  log(`Target: ${installPath}` + (target.label && target.label !== 'resolved target' ? `  (${target.label})` : ''));
+  if (!MULTI_TARGET && !CUSTOM_PATH && LOCATION === 'global') {
     const g = resolveGlobalRoot();
     log(`Global root: ${g.root} — ${g.why}`);
     // The search is a decision, so the candidates it rejected are shown rather than hidden:
@@ -463,12 +664,29 @@ async function install(location, customPath, version, force) {
   // unpacked into a throwaway directory, and the same manifest copies out of it.
   let sourceRoot = SOURCE_DIR;
   let cleanup = null;
-  if (haveSourceTree()) {
+  // What this install is made from, recorded so `verify` can say more than "the files are here".
+  let sourceInfo = { kind: 'tree', path: path.relative(process.cwd(), SOURCE_DIR) || '.' };
+  // `--version` has to mean something. The tree beside the installer wins only when it IS the
+  // requested version (or when nothing was requested); asking for another version fetches that
+  // version's archive instead of quietly installing the tree in front of it.
+  const treeVersion = haveSourceTree() ? getInstalledVersion(SOURCE_DIR) : null;
+  const wantsOtherVersion = version !== 'latest' && treeVersion && treeVersion !== version;
+  if (haveSourceTree() && !wantsOtherVersion) {
     log(`\nInstalling from the tree beside the installer...`);
   } else {
+    if (wantsOtherVersion) {
+      log(`\nRequested v${version}; the tree beside the installer is v${treeVersion}, so the v${version} archive is fetched.`);
+    }
     const fetched = await fetchAndUnpack(version);
     sourceRoot = fetched.root;
     cleanup = fetched.cleanup;   // removed after the manifest has read out of it
+    sourceInfo = {
+      kind: 'archive',
+      ref: fetched.ref,
+      label: fetched.label,
+      archive_url: fetched.url,
+      archive_sha256: fetched.sha256,
+    };
   }
 
   // Create directories
@@ -477,26 +695,44 @@ async function install(location, customPath, version, force) {
     fs.mkdirSync(path.join(installPath, subdir), { recursive: true });
   }
 
-  const copied = copyManifest(sourceRoot, installPath);
-  if (cleanup) cleanup();
+  const { copied } = copyManifest(sourceRoot, installPath);
 
-  // The manifest is the completion criterion, so a short install fails here instead of
-  // reporting success. This is the check that was missing when the installer looked for its
-  // guides under a path that only exists in the development tree: it warned fourteen times
-  // and installed a copy with no README, no LICENSE and no docs/ at all.
+  // The manifest is the completion criterion, so a short install fails here instead of reporting
+  // success. This is the check that was missing when the installer looked for its guides under a
+  // path that only exists in the development tree: it warned fourteen times and installed a copy
+  // with no README, no LICENSE and no docs/ at all.
+  //
+  // Two different things look the same here, and conflating them was a bug: a file the SOURCE
+  // does not have (pinning an older version legitimately has fewer files) and a file the source
+  // HAS but that did not land (a broken copy). The first is reported, the second fails.
   const missing = SKILL_FILES.filter(f => !fs.existsSync(path.join(installPath, f.to)));
   if (missing.length) {
-    error(`Incomplete install: ${missing.length} of ${SKILL_FILES.length} file(s) missing — ` +
-      missing.map(f => f.to).join(', '));
+    const absentFromSource = missing.filter(f => !resolveSource(sourceRoot, f.from));
+    const notCopied = missing.filter(f => resolveSource(sourceRoot, f.from));
+    if (absentFromSource.length) {
+      warn(`${absentFromSource.length} file(s) are not part of this version: ` +
+        absentFromSource.map(f => f.to).join(', '));
+    }
+    if (notCopied.length) {
+      error(`Incomplete install: ${notCopied.length} of ${SKILL_FILES.length} file(s) missing — ` +
+        notCopied.map(f => f.to).join(', '));
+    }
   }
+  if (cleanup) cleanup();
   
-  // Create package.json if not exists
+  // Create package.json if not exists. An installed copy is a skill, not a package: it carries
+  // no `files` allowlist and no bin, so `npm publish` run inside one would ship whatever happens
+  // to be in the directory — including a handoff store. `private` makes npm refuse there with
+  // EPRIVATE before it authenticates (verified); `npm pack` still packs the directory, so the
+  // flag is a guard against publishing, not a sandbox. The publishable manifest is the
+  // repository root's, which is the package users npx.
   const pkgPath = path.join(installPath, 'package.json');
   if (!fs.existsSync(pkgPath)) {
     fs.writeFileSync(pkgPath, JSON.stringify({
       name: SKILL_NAME,
       version: version === 'latest' ? SKILL_VERSION : version,
-      description: 'Cross-harness session handoff engine',
+      description: 'Cross-harness session handoff engine (installed copy — not a publishable package; the npm package is agents-handoff)',
+      private: true,
       type: 'module'
     }, null, 2));
   }
@@ -504,8 +740,13 @@ async function install(location, customPath, version, force) {
   // The version reported is the one that landed, read back out of the installed SKILL.md —
   // not the requested string, and not a constant that a release has to remember to bump.
   const installedVersion = getInstalledVersion(installPath) || (version === 'latest' ? SKILL_VERSION : version);
+
+  // Record what was installed and what it was made from. `verify` re-hashes the same file set
+  // and compares, which is what makes an installation checkable rather than merely present.
+  const record = writeProvenance(installPath, { version: installedVersion, harness: target.harness, source: sourceInfo });
   success(`Installed ${SKILL_NAME} v${installedVersion} to ${installPath}`);
   log(`Copied ${copied} files`);
+  log(`Provenance: ${describeSource(sourceInfo)} · file-set sha256 ${record.files_sha256.slice(0, 16)}…  (${PROVENANCE_FILE})`);
   // `config` is a real verb that exits 0 and prints the resolved root. `--help` is not a verb
   // (it exits 2), so the old hint told every user to run a failing command.
   log(`\nRun with: node ${path.join(installPath, 'tools', 'handoff.mjs')} config`);
@@ -513,20 +754,49 @@ async function install(location, customPath, version, force) {
   return { installed: true, path: installPath, version: installedVersion };
 }
 
-// Update skill
+// Update skill.
+//
+// With a harness flag (`--update --claude`) the update is scoped to that target. With NO target
+// flag it updates EVERY installation this machine has, which is the question the bare verb is
+// actually asking: a machine that holds agents-handoff in ~/.claude/skills and in ~/.agents/skills
+// has two copies, and updating only the resolved one leaves the other silently stale.
+//
+// An update copies the manifest and nothing else, so a store (projects/, handoffs/,
+// .agent-handoff/) and handoff.config.json are never touched.
 async function update(location, customPath, version) {
-  const installPath = resolveInstallPath(location, customPath);
-  
-  if (!isInstalled(installPath)) {
-    error(`Not installed at ${installPath}. Run 'install' first.`);
+  if (MULTI_TARGET) return install(location, customPath, version, true);
+
+  const found = discoverInstalls();
+  if (!found.length) {
+    error('Nothing to update: no agents-handoff installation found.\n' +
+      '  Install one with: npx agents-handoff --all\n' +
+      '  Or name a target: --claude, --codex, --agents, --all, --skills-dir <dir>, --path <dir>');
   }
-  
-  const currentVersion = getInstalledVersion(installPath);
-  log(`\nCurrent version: ${currentVersion}`);
-  log(`Updating to: ${version}`);
-  
-  // For now, just reinstall
-  return install(location, customPath, version, true);
+
+  log(`\n${C('bold', 'agents-handoff updater v' + INSTALLER_VERSION)}`);
+  log(`Updating ${found.length} installation(s) to ${version === 'latest' ? 'the latest version' : 'v' + version}`);
+  for (const f of found) log(`  · ${f.label}: ${f.path}`);
+
+  const results = [];
+  for (const target of found) {
+    const before = getInstalledVersion(target.path);
+    const r = await installTarget(
+      { label: target.label, dir: target.dir, path: target.path },
+      version,
+      true,
+    );
+    results.push({ ...r, before });
+  }
+
+  log(`\n${C('bold', 'Update summary')}`);
+  for (const r of results) {
+    log(`  ${r.skipped ? C('yellow', '–') + ' unchanged' : C('green', '✓') + ' updated'} ${r.path} — ${r.before} → v${r.version}`);
+  }
+  const changed = results.filter((r) => !r.skipped).length;
+  success(changed
+    ? `${changed} of ${results.length} installation(s) updated`
+    : `already current — ${results.length} installation(s) at v${results[0] && results[0].version}`);
+  return results;
 }
 
 // Remove skill
@@ -541,8 +811,9 @@ function remove(location, customPath, force) {
   if (!force) {
     log(`\nThis will remove ${SKILL_NAME} from:`);
     log(`  ${installPath}`);
-    log(`\nYour handoffs (projects/, handoffs/, links/) will NOT be deleted.`);
+    log(`\nYour handoffs and anything else you put in this directory will NOT be deleted.`);
     log(`Configuration (handoff.config.json) will NOT be deleted.`);
+    log(`Only what the install manifest owns is removed, and what is kept is listed at the end.`);
     log(`\nContinue? (y/N)`);
     
     // In non-interactive mode, default to no
@@ -574,45 +845,31 @@ function remove(location, customPath, force) {
   return doRemove(installPath, force);
 }
 
-function doRemove(installPath, force) {
-  log(`\nRemoving from ${installPath}...`);
-  
-  // Keep handoffs, projects, links directories (user data)
-  const keepDirs = ['handoffs', 'projects', 'links'];
-  const keepFiles = ['handoff.config.json', '.env.example'];
-  
-  // Read directory contents
+function doRemove(installPath, force) {  log(`\nRemoving from ${installPath}...`);
+
+  // WHAT AN INSTALL OWNS IS THE MANIFEST. Everything else in the directory belongs to the user,
+  // so the rule below is a removal set, not a keep list: a keep list removes whatever nobody
+  // remembered to name, which is how a store called anything other than the three expected
+  // directories would have been deleted by `remove --force`. Store directories, notes, config
+  // and anything a future version writes as user data therefore survive by default.
+  const owned = new Set(SKILL_FILES.map((f) => f.to.split('/')[0]));
+  const KEPT_FILES = new Set(['handoff.config.json', '.env.example']);
+
   let entries;
   try {
     entries = fs.readdirSync(installPath, { withFileTypes: true });
   } catch {
     entries = [];
   }
-  
+
+  const kept = [];
   for (const entry of entries) {
     const entryPath = path.join(installPath, entry.name);
-    
-    // Skip user data directories
-    if (entry.isDirectory() && keepDirs.includes(entry.name)) {
-      if (force) {
-        // Check if empty
-        try {
-          const contents = fs.readdirSync(entryPath);
-          if (contents.length === 0) {
-            fs.rmdirSync(entryPath);
-            log(`Removed empty directory: ${entry.name}/`);
-          }
-        } catch {}
-      }
-      continue;
-    }
-    
-    // Skip kept files
-    if (!entry.isDirectory() && keepFiles.includes(entry.name)) {
+    const isOwned = owned.has(entry.name) && !KEPT_FILES.has(entry.name);
+    if (!isOwned) {
+      kept.push(entry.name + (entry.isDirectory() ? '/' : ''));
       continue;
     }
-    
-    // Remove everything else
     if (entry.isDirectory()) {
       fs.rmSync(entryPath, { recursive: true, force: true });
       log(`Removed directory: ${entry.name}/`);
@@ -621,6 +878,33 @@ function doRemove(installPath, force) {
       log(`Removed file: ${entry.name}`);
     }
   }
+
+  // The installer's own record, and the private package.json stub it writes. The stub is only
+  // removed when it is still the stub — a package.json a user has edited is theirs.
+  try {
+    fs.unlinkSync(path.join(installPath, PROVENANCE_FILE));
+    log(`Removed file: ${PROVENANCE_FILE}`);
+  } catch { /* none written */ }
+  let stubRemoved = false;
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(installPath, 'package.json'), 'utf8'));
+    if (pkg.private === true && pkg.name === SKILL_NAME) {
+      fs.unlinkSync(path.join(installPath, 'package.json'));
+      stubRemoved = true;
+      log('Removed file: package.json (installer stub)');
+    } else {
+      kept.push('package.json (yours — kept)');
+    }
+  } catch { /* no package.json, or not JSON: leave it */ }
+
+  const survivors = kept
+    .filter((k) => k !== PROVENANCE_FILE && !(k === 'package.json' && stubRemoved))
+    .sort();
+  if (survivors.length) {
+    log(`\nKept — not the installer's to delete:`);
+    for (const k of survivors) log(`  ${k}`);
+  }
+  
   
   // Try to remove install directory if empty
   try {
@@ -634,13 +918,206 @@ function doRemove(installPath, force) {
   return { removed: true, path: installPath };
 }
 
-// Verify installation
+// Verify every target this run selected. One harness behaves exactly as before; several are
+// verified in turn, and the run fails if any of them fails. With no target flag, every
+// installation found on the machine is verified — the same list `update` acts on, so
+// "update everything" and "verify everything" cannot disagree about what exists.
 function verify(location, customPath) {
-  const installPath = resolveInstallPath(location, customPath);
+  const targets = MULTI_TARGET
+    ? resolveTargets()
+    : discoverInstalls().map((t) => ({ label: t.label, dir: t.dir, path: t.path }));
+  if (!targets.length) {
+    error('Nothing to verify: no agents-handoff installation found.\n' +
+      '  Install one with: npx agents-handoff --all');
+  }
+  if (targets.length > 1) log(`\n${C('bold', 'Verifying ' + targets.length + ' installation(s)')}`);
+  let ok = true;
+  for (const target of targets) {
+    const r = verifyOne(target, PROVENANCE);
+    if (!r.valid) ok = false;
+  }
+  if (!ok) error('Verification failed. Try reinstalling.');
+  return { valid: true };
+}
+
+// ----------------------------------------------------------- verify against the package
+// The strongest check this installer can make: does the copy on disk match the tarball npm is
+// actually serving for its version? Everything else compares an installation with itself, or
+// with the tree it came from. This compares it with the published artifact, and it works
+// whichever way the install happened — tree, GitHub archive, or `npx`.
+//
+// Three things are checked, in this order, because each one makes the next meaningful:
+//   1. the tarball we downloaded matches the hashes the REGISTRY declares for that version
+//      (otherwise "the published package" is whatever this network handed us)
+//   2. the tarball's manifest file set hashes to the same value as the installed file set
+//      (per-file differences are named)
+//   3. if the install record already holds a package sha256, it matches too
+async function registryMeta(version) {
+  if (typeof fetch === 'undefined') return null;
+  try {
+    const res = await fetch(`${REGISTRY}/${NPM_PACKAGE}/${encodeURIComponent(version)}`, {
+      headers: { accept: 'application/json', 'user-agent': NPM_PACKAGE },
+    });
+    if (!res.ok) return null;
+    const j = await res.json();
+    return {
+      tarball: (j.dist && j.dist.tarball) || null,
+      integrity: (j.dist && j.dist.integrity) || null,
+      shasum: (j.dist && j.dist.shasum) || null,
+    };
+  } catch { return null; }
+}
+
+function recordPackageVerification(installPath, actual, meta) {
+  const prov = readProvenance(installPath);
+  if (!prov) {
+    warn('no install record to update — reinstall to create one');
+    return false;
+  }
+  prov.package = {
+    ...packageRecord(installPath),
+    ...(prov.package || {}),
+    tarball: meta.tarball,
+    integrity: meta.integrity || null,
+    shasum: meta.shasum || null,
+    sha256: actual.sha256,
+    sha512: actual.sha512,
+    verified_at: new Date().toISOString(),
+  };
+  fs.writeFileSync(path.join(installPath, PROVENANCE_FILE), JSON.stringify(prov, null, 2) + '\n');
+  return true;
+}
+
+async function verifyPackageOne(target) {
+  const installPath = target.path;
+  const version = getInstalledVersion(installPath);
+  console.log(`\n${C('bold', 'Verifying ' + NPM_PACKAGE + '@' + (version || '?') + ' against the published tarball')}`);
+  console.log(`Install: ${installPath}`);
+  if (!isInstalled(installPath)) {
+    console.error(`  ${C('red', '✗')} not installed at ${installPath}`);
+    return false;
+  }
+  if (!version) {
+    console.error(`  ${C('red', '✗')} SKILL.md carries no version — nothing to look up`);
+    return false;
+  }
+
+  const meta = await registryMeta(version);
+  if (!meta || !meta.tarball) {
+    console.error(`  ${C('red', '✗')} ${NPM_PACKAGE}@${version} is not on the npm registry, or the registry is unreachable`);
+    console.error('    the installation itself is untouched by this result — this check needs the network');
+    return false;
+  }
+
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'agents-handoff-npm-'));
+  try {
+    const tgz = path.join(tmp, 'package.tgz');
+    await downloadFile(meta.tarball, tgz);
+    const bytes = fs.readFileSync(tgz);
+    const actual = {
+      sha256: crypto.createHash('sha256').update(bytes).digest('hex'),
+      sha512: crypto.createHash('sha512').update(bytes).digest('hex'),
+      sha1: crypto.createHash('sha1').update(bytes).digest('hex'),
+    };
+
+    const checks = [];
+    if (meta.integrity) {
+      checks.push({
+        name: 'tarball matches the registry integrity (' + meta.integrity.slice(0, 20) + '…)',
+        passed: meta.integrity === 'sha512-' + Buffer.from(actual.sha512, 'hex').toString('base64'),
+      });
+    }
+    if (meta.shasum) {
+      checks.push({
+        name: 'tarball matches the registry shasum (' + meta.shasum.slice(0, 12) + '…)',
+        passed: meta.shasum === actual.sha1,
+      });
+    }
+
+    const unpack = path.join(tmp, 'unpack');
+    fs.mkdirSync(unpack, { recursive: true });
+    const tar = spawnSync('tar', ['-xzf', 'package.tgz', '-C', 'unpack', '--strip-components=1'],
+      { cwd: tmp, encoding: 'utf8' });
+    if (tar.status !== 0) {
+      console.error(`  ${C('red', '✗')} cannot extract the published tarball (tar exited ${tar.status})`);
+      return false;
+    }
+
+    const differing = [];
+    for (const rel of SKILL_FILES.map((f) => f.to).sort()) {
+      const inPackage = path.join(unpack, ...rel.split('/'));
+      const installed = path.join(installPath, ...rel.split('/'));
+      const hPackage = fs.existsSync(inPackage) ? fileSha256(inPackage) : 'missing';
+      const hInstalled = fs.existsSync(installed) ? fileSha256(installed) : 'missing';
+      if (hPackage !== hInstalled) {
+        differing.push(rel + ' (' + (hInstalled === 'missing' ? 'not installed'
+          : hPackage === 'missing' ? 'not in the published package' : 'content differs') + ')');
+      }
+    }
+    checks.push({
+      name: `all ${SKILL_FILES.length} manifest file(s) are identical to the published tarball`,
+      passed: differing.length === 0,
+    });
+    for (const d of differing.slice(0, 12)) console.error(`      ${d}`);
+    if (differing.length > 12) console.error(`      … ${differing.length - 12} more`);
+
+    const prov = readProvenance(installPath);
+    const recorded = prov && prov.package ? prov.package : null;
+    if (recorded && recorded.sha256) {
+      checks.push({
+        name: 'tarball sha256 matches the hash recorded for this install',
+        passed: recorded.sha256 === actual.sha256,
+      });
+    } else {
+      log(`  ${C('yellow', '·')} no package sha256 recorded for this install${RECORD ? '' : ' — pass --record to store it'}`);
+    }
+
+    for (const c of checks) log(`  ${c.passed ? C('green', '✓') : C('red', '✗')} ${c.name}`);
+    log(`  package: ${NPM_PACKAGE}@${version}`);
+    log(`  tarball: ${meta.tarball}`);
+    log(`  sha256:  ${actual.sha256}`);
+
+    if (RECORD) {
+      if (recordPackageVerification(installPath, actual, meta)) {
+        log(`  recorded in ${PROVENANCE_FILE} (package.sha256 / sha512 / integrity)`);
+      }
+    }
+
+    const ok = checks.every((c) => c.passed);
+    console.log();
+    if (ok) {
+      success(`Installation matches the published package`);
+      return true;
+    }
+    console.error(`The installation does NOT match agents-handoff@${version} as published`);
+    return false;
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+}
+
+async function verifyPackage() {
+  const targets = MULTI_TARGET
+    ? resolveTargets()
+    : discoverInstalls().map((t) => ({ label: t.label, dir: t.dir, path: t.path }));
+  if (!targets.length) {
+    error('Nothing to verify: no agents-handoff installation found.\n' +
+      '  Install one with: npx agents-handoff --all');
+  }
+  let ok = true;
+  for (const target of targets) {
+    if (!(await verifyPackageOne(target))) ok = false;
+  }
+  if (!ok) error('Package verification failed.');
+  return { valid: true };
+}
+
+function verifyOne(target, showProvenance) {
+  const installPath = target.path;
   
-  console.log(`\n${C('bold', 'Verifying agent-handoff installation...')}`);
+  console.log(`\n${C('bold', 'Verifying agents-handoff installation...')}`);
   console.log(`Location: ${installPath}`);
-  if (!customPath && location === 'global') console.log(`Global root: ${resolveGlobalRoot().root}`);
+  if (!MULTI_TARGET && !CUSTOM_PATH && LOCATION === 'global') console.log(`Global root: ${resolveGlobalRoot().root}`);
   console.log();
   
   if (!isInstalled(installPath)) {
@@ -649,13 +1126,22 @@ function verify(location, customPath) {
   
   const checks = [];
   let allPassed = true;
-  
-  // Check required files
-  const requiredFiles = SKILL_FILES.map(f => f.to);
-  
-  for (const file of requiredFiles) {
-    const filePath = path.join(installPath, file);
-    const exists = fs.existsSync(filePath);
+
+  // What this installation is supposed to contain: the manifest, minus the entries its own
+  // install record marks absent because that version never had them. Pinning an older version
+  // is legitimate, so an expected absence is reported as such rather than failed — the same
+  // distinction the install path makes.
+  const prov = checkProvenance(installPath);
+  const expectedAbsent = new Set(prov.present
+    ? Object.entries(prov.record.files || {}).filter(([, v]) => v === 'missing').map(([k]) => k)
+    : []);
+
+  for (const file of SKILL_FILES.map(f => f.to)) {
+    if (expectedAbsent.has(file)) {
+      checks.push({ name: `File: ${file} (not part of v${prov.record.version})`, passed: true });
+      continue;
+    }
+    const exists = fs.existsSync(path.join(installPath, file));
     checks.push({ name: `File: ${file}`, passed: exists });
     if (!exists) allPassed = false;
   }
@@ -696,20 +1182,40 @@ function verify(location, customPath) {
     log(`  ${check.passed ? C('green', '✓') : C('red', '✗')} ${check.name}`);
   }
   
+  // Provenance: compare the installation with the record written when it was installed. An
+  // installation without a record is NOT a failure — it predates this feature — so that case is
+  // reported and skipped, never silently passed.
+  if (prov.present) {
+    checks.push({ name: 'provenance: file-set sha256 matches the install record', passed: prov.match });
+    if (!prov.match) {
+      allPassed = false;
+      for (const c of prov.changed) console.error(`      ${c}`);
+    }
+    if (showProvenance) {
+      log(`  provenance record`);
+      log(`    installed_at: ${prov.record.installed_at}`);
+      log(`    source: ${describeSource(prov.record.source)}`);
+      log(`    harness: ${prov.record.harness || '(resolved target)'}`);
+      log(`    files: ${prov.record.file_count} · file-set sha256 ${prov.record.files_sha256}`);
+    }
+  } else {
+    log(`  ${C('yellow', '·')} no provenance record — installed before 2.0.3; reinstall to record one`);
+  }
+
   console.log();
   if (allPassed) {
     success(`Installation verified ✓`);
     log(`Location: ${installPath}`);
     log(`Version: ${getInstalledVersion(installPath) || 'unknown'}`);
-    return { valid: true };
-  } else {
-    error(`Verification failed. Try reinstalling.`);
+    return { valid: true, path: installPath };
   }
+  console.error(`Verification failed for ${installPath}`);
+  return { valid: false, path: installPath };
 }
 
 // List installations
 function listInstallations() {
-  console.log(`\n${C('bold', 'Installed agent-handoff locations')}\n`);
+  console.log(`\n${C('bold', 'Installed agents-handoff locations')}\n`);
   
   const g = resolveGlobalRoot();
   const locations = [
@@ -717,6 +1223,12 @@ function listInstallations() {
     { name: 'Global (resolved — ' + g.why + ')', root: g.root },
     { name: 'Local (cwd/local/skills)', root: PATHS.local },
   ];
+  // Every harness this installer knows about, present on this machine or not, so a missing
+  // install is visible as "not there" instead of invisible.
+  for (const name of Object.keys(HARNESSES)) {
+    locations.push({ name: `Harness ${name}${harnessDetected(name) ? '' : ' (not detected)'}`, root: HARNESSES[name].user });
+    locations.push({ name: `Harness ${name} (project form)`, root: HARNESSES[name].project });
+  }
   // Every other candidate root is listed too, so a second account or a stale
   // ~/.agents/skills copy is VISIBLE rather than silently ignored.
   for (const d of accountSkillRoots()) locations.push({ name: 'account-skill candidate', root: d });
@@ -728,17 +1240,30 @@ function listInstallations() {
   let foundAny = false;
   const seen = new Set();
   
+  const candidates = [];
   for (const loc of locations) {
-    const skillPath = path.join(loc.root, SKILL_NAME);
+    candidates.push({ name: loc.name, skillPath: path.join(loc.root, SKILL_NAME) });
+    // A copy installed before the rename is listed too — under the name it actually has, so a
+    // stale `agent-handoff/` is visible rather than silently absent from `list`.
+    candidates.push({ name: loc.name + ' (pre-2.0.3 name)', skillPath: path.join(loc.root, LEGACY_SKILL_NAME) });
+  }
+
+  for (const cand of candidates) {
+    const skillPath = cand.skillPath;
     if (seen.has(skillPath)) continue;
     seen.add(skillPath);
     if (isInstalled(skillPath)) {
+      const loc = { name: cand.name };
       foundAny = true;
       const version = getInstalledVersion(skillPath) || 'unknown';
       log(`${C('green', '✓')} ${loc.name}`);
       log(`  Path: ${skillPath}`);
       log(`  Version: ${version}`);
       log(`  Files from the manifest: ${SKILL_FILES.filter(f => fs.existsSync(path.join(skillPath, f.to))).length}/${SKILL_FILES.length}`);
+      const prov = checkProvenance(skillPath);
+      log(`  Provenance: ${prov.present
+        ? (prov.match ? 'matches the install record' : 'MISMATCH — ' + prov.changed.join(', '))
+        : 'none recorded'}`);
       log();
     }
   }
@@ -761,6 +1286,48 @@ function printGlobalResolution() {
   return g;
 }
 
+// `doctor` answers the whole question in one shot: which harnesses exist here, what is
+// installed where, whether each installation still matches the record written when it was
+// installed, and where the engine will keep handoffs. It reads and reports; it never installs.
+function doctor() {
+  console.log(`\n${C('bold', 'agents-handoff doctor')}`);
+  console.log(`  product v${SKILL_VERSION} · installer v${INSTALLER_VERSION} · node ${process.version}`);
+  console.log(`\n${C('bold', 'Harnesses')}`);
+  let installed = 0;
+  for (const name of Object.keys(HARNESSES)) {
+    const dir = HARNESSES[name].user;
+    const target = path.join(dir, SKILL_NAME);
+    const present = harnessDetected(name);
+    const here = isInstalled(target);
+    if (here) installed += 1;
+    console.log(`  ${present ? C('green', '✓') : C('yellow', '·')} ${name.padEnd(7)} ${present ? 'present' : 'not found'}  ${dir}`);
+    if (!here) continue;
+    const prov = checkProvenance(target);
+    const files = SKILL_FILES.filter(f => fs.existsSync(path.join(target, f.to))).length;
+    console.log(`      v${getInstalledVersion(target) || '?'} · ${files}/${SKILL_FILES.length} files · ` +
+      (prov.present
+        ? (prov.match ? 'provenance OK' : C('red', 'PROVENANCE MISMATCH') + ' (' + prov.changed.length + ' file(s))')
+        : 'no provenance record'));
+  }
+  const g = resolveGlobalRoot();
+  console.log(`\n${C('bold', 'Global resolution')}`);
+  console.log(`  ${g.root} — ${g.why}`);
+  for (const other of g.others || []) console.log(`  also holds an install: ${other}`);
+  console.log(`\n${C('bold', 'Store (where handoffs are written)')}`);
+  if (haveSourceTree()) {
+    const r = spawnSync(process.execPath, [path.join(SOURCE_DIR, 'tools', 'handoff.mjs'), 'config'], { encoding: 'utf8' });
+    for (const line of String(r.stdout || '').trim().split('\n')) console.log('  ' + line);
+  } else {
+    console.log(`  ask an installed engine: node <install>${path.sep}tools${path.sep}handoff.mjs config`);
+  }
+  console.log(`\n${C('bold', 'Verdict')}`);
+  console.log(installed
+    ? `  ${installed} harness installation(s) found.`
+    : '  nothing installed yet — run: npx agents-handoff --all');
+  log('');
+  return installed;
+}
+
 // Main
 async function main() {
   try {
@@ -784,7 +1351,12 @@ async function main() {
       case 'v':
         await verify(LOCATION, CUSTOM_PATH);
         break;
-        
+
+      case 'verify-package':
+      case 'vp':
+        await verifyPackage();
+        break;
+
       case 'list':
       case 'ls':
         listInstallations();
@@ -793,6 +1365,11 @@ async function main() {
       case 'where':
         printGlobalResolution();
         break;
+
+      case 'doctor':
+      case 'doc':
+        doctor();
+        break;
         
       case '--help':
       case '-h':
@@ -804,49 +1381,71 @@ async function main() {
         error(`Unknown command: ${COMMAND}. Use install, update, remove, verify, or list.`);
     }
   } catch (e) {
+    // An unexpected failure prints its stack when AGENTS_HANDOFF_DEBUG is set, because a bare
+    // message is not enough to repair one; the message alone stays the default so the normal
+    // output stays readable.
+    if (process.env.AGENTS_HANDOFF_DEBUG) console.error(e.stack || e);
     error(`Error: ${e.message}`);
   }
 }
 
 function showHelp() {
   console.log(`
-${C('bold', 'agents-handoff')} - Install assistant for agent-handoff skill
+${C('bold', 'agents-handoff')} - Install assistant for agents-handoff skill
 
 ${C('bold', 'Usage:')}
   npx agents-handoff <command> [options]
 
 ${C('bold', 'Commands:')}
-  install, i      Install the skill (default)
-  update, u       Update to latest or specified version
-  remove, rm      Remove the installation
-  verify, v       Verify installation integrity
-  list, ls        List all installed locations
-  where           Show the resolved global root and why it was chosen
+  install, i          Install the skill (default)
+  update, u           Update to the latest (or a named) version. With no harness flag it
+                      updates EVERY installation found on this machine
+  remove, rm          Remove the installation; your store and config are never deleted
+  verify, v           Verify integrity against the install record. With no harness flag it
+                      verifies every installation found
+  verify-package, vp  Verify the installation against the tarball npm actually serves,
+                      including the registry's own hashes
+  list, ls            List all installed locations
+  where               Show the resolved global root and why it was chosen
+  doctor              Which harnesses exist here, what is installed, and whether it still matches
+
+${C('bold', 'Harness targets (install into the one you use, or several at once):')}
+  --claude        Claude Code      ~/.claude/skills
+  --codex         Codex CLI        ~/.codex/skills
+  --agents        neutral store    ~/.agents/skills
+  --harness H     named harness(es), comma separated; repeatable
+  --all           every harness whose directory exists on this machine
+  --skills-dir D  any other stack, exactly; repeatable
+  --project       use the per-repository form (./.claude/skills, ./.codex/skills)
 
 ${C('bold', 'Options:')}
   --location L    Install location: global (default), local, project
   --path P        Custom installation path
   --version V     Version to install: latest (default) or specific version
   --force, -f     Skip confirmations, overwrite existing
+  --provenance    With verify: print the install record it was checked against
+  --record        With verify-package: store the tarball hashes in the install record
 
 ${C('bold', 'Examples:')}
-  npx agents-handoff                      # Install to global
-  npx agents-handoff --location project   # Install to project
-  npx agents-handoff --update             # Update to latest
-  npx agents-handoff --remove --force     # Remove without asking
-  npx agents-handoff --verify              # Check installation
-  npx agents-handoff --list                # Show all installations
+  npx agents-handoff --all               # every harness found here, one run
+  npx agents-handoff --claude --codex    # exactly these two
+  npx agents-handoff --project --claude  # this repository, for Claude Code
+  npx agents-handoff --skills-dir ~/.config/mytool/skills
+  npx agents-handoff --doctor            # what is here, and is it intact
+  npx agents-handoff --verify --provenance
+  npx agents-handoff --verify-package --record   # prove the install matches the npm tarball
+  npx agents-handoff --update            # every installation on this machine, one run
 
 ${C('bold', 'Locations:')}
   global   resolved, not hard-coded: an account-skill root that already holds
-           agent-handoff, else ~/.agents/skills, else any account-skill store found on this
+           agents-handoff, else ~/.agents/skills, else any account-skill store found on this
            machine, else ~/.agents/skills (created on install). A store holds the skill two
-           id levels below it — <store>/<account-id>/<profile-id>/agent-handoff/ — so the
+           id levels below it — <store>/<account-id>/<profile-id>/agents-handoff/ — so the
            store itself is not an install target.
            Override with AGENT_HANDOFF_GLOBAL_DIR, or target an exact path with --path.
            See it resolved: npx agents-handoff where
-  local    ./local/skills/agent-handoff
-  project  ./skills/agent-handoff (only if in a git repo)
+  local    ./local/skills/agents-handoff
+  project  ./skills/agents-handoff (only if in a git repo)
 
 ${C('bold', 'Repository:')}
   https://github.com/${REPO_OWNER}/${REPO_NAME}