agents-handoff 2.0.2 → 2.0.3

package/tools/agents-handoff.mjs

@@ -0,0 +1,410 @@
+#!/usr/bin/env node
+// agents-handoff.mjs v1.0.0 - Level 4 dynamic layer for the agents-handoff skill.
+// Commands:
+//   auto <args...>      - self-triggering capture (stale-check + lock + build)
+//   verify-gate <id>    - evidence-gated integrity (sha + counts + contract + evidence)
+//   promote <id>        - stamp a verified handoff as a promotion candidate (manifest fields only)
+//   merge <a> <b>       - compose two sessions of one project into one handoff
+//   self-improve        - distill brief shortfalls into a rules candidate
+//   index               - rebuild INDEX.json + refresh cross-links, report stale sessions
+// Every mutating op: lock-guard, backup, verify-after-apply, rollback on failure, idempotent.
+// Zero deps beyond node. Env: HANDOFFS_ROOT=<root> hermetic override (always wins).
+// The store root is resolved by tools/lib/handoff-root.mjs (env -> handoff.config.json ->
+// handoffs/ discovery -> skill directory), so a configured store never has to live inside
+// the skill. ENGINE deliberately points at SKILL_ROOT, not the store: the engine is part of
+// the installed skill, while the store is wherever the user configured it.
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import { resolveRoot, SKILL_ROOT } from './lib/handoff-root.mjs';
+
+const RES = (() => { try { return resolveRoot(); } catch (e) { console.error('agents-handoff: ' + e.message); process.exit(2); } })();
+const ROOT = RES.root;
+const PROJ = path.join(ROOT, 'projects');
+const LINKS = path.join(ROOT, 'links');
+const ENGINE = path.join(SKILL_ROOT, 'tools', 'handoff.mjs');
+const sha = (s) => crypto.createHash('sha256').update(s).digest('hex');
+const die = (c, m) => { console.error('agents-handoff: ' + m); process.exit(c); };
+const now = () => new Date().toISOString();
+
+function lockFor(key) {
+  const lp = path.join(ROOT, '.locks', sha(key).slice(0, 24) + '.lock');
+  fs.mkdirSync(path.dirname(lp), { recursive: true });
+  try {
+    const fd = fs.openSync(lp, 'wx');
+    fs.writeSync(fd, String(process.pid));
+    fs.closeSync(fd);
+  } catch (e) {
+    if (e.code === 'EEXIST') return null;
+    throw e;
+  }
+  return { release: () => { try { fs.unlinkSync(lp); } catch (err) { /* already gone */ } } };
+}
+
+function readManifest(id) {
+  const hit = pick(id);
+  const mp = path.join(hit.dir, 'manifest.json');
+  return { hit, man: JSON.parse(fs.readFileSync(mp, 'utf8')) };
+}
+
+function pick(pre) {
+  const iP = path.join(ROOT, 'INDEX.json');
+  let idx = fs.existsSync(iP) ? JSON.parse(fs.readFileSync(iP, 'utf8')) : [];
+  let hits = idx.filter((e) => e.id.startsWith(pre) || String(e.uuid || '').startsWith(pre));
+  if (hits.length !== 1) die(3, 'ambiguous or missing prefix: ' + pre + ' (' + hits.length + ' hits)');
+  return { id: hits[0].id, project: hits[0].project, dir: path.join(PROJ, hits[0].project, hits[0].id) };
+}
+
+// ---------------------------------------------------------------- auto
+function cmdAuto() {
+  const i = process.argv.indexOf('auto');
+  const args = process.argv.slice(i + 1);
+  if (!args.includes('--source')) die(2, 'auto requires --source <file> (and --session/--harness/--project)');
+  const srcArg = args[args.indexOf('--source') + 1];
+  const sid = args.includes('--session') ? args[args.indexOf('--session') + 1] : path.basename(srcArg).replace(/\.(jsonl|txt|md)$/i, '');
+  const harness = args.includes('--harness') ? args[args.indexOf('--harness') + 1] : 'generic';
+  const project = args.includes('--project') ? args[args.indexOf('--project') + 1] : 'unsorted';
+  const minFresh = args.includes('--min-fresh-ms') ? Number(args[args.indexOf('--min-fresh-ms') + 1]) : 60_000;
+  if (!fs.existsSync(srcArg)) die(2, 'source not found: ' + srcArg);
+  const srcStat = fs.statSync(srcArg);
+
+  // Stale probe: build only when the source changed after the manifest was last updated.
+  const mp = path.join(PROJ, project, sid.replace(/[^\w.-]/g, '_'), 'manifest.json');
+  if (fs.existsSync(mp)) {
+    const man = JSON.parse(fs.readFileSync(mp, 'utf8'));
+    const manAt = Date.parse(man.updated_at || 0);
+    if (srcStat.mtimeMs - manAt < minFresh) {
+      console.log(JSON.stringify({ ok: true, action: 'skip-fresh', session: sid, source_mtime_ms: srcStat.mtimeMs, manifest_at: manAt }));
+      return;
+    }
+  }
+
+  // Lock guard: no duplicate concurrent captures.
+  const lock = lockFor('auto:' + project + '/' + sid);
+  if (!lock) die(3, 'capture already in flight for ' + sid);
+  try {
+    const out = execFileSync(process.execPath, [ENGINE, 'build', '--source', srcArg, '--session', sid, '--harness', harness, '--project', project], {
+      encoding: 'utf8'
+    });
+    console.log(JSON.stringify({ ok: true, action: 'captured', session: sid, output: out.trim().split('\n').pop() }));
+  } finally {
+    lock.release();
+  }
+}
+
+// ---------------------------------------------------------------- verify-gate
+const CONTRACT_FIELDS = ['RESULT', 'WHAT_CHANGED', 'VALIDATION', 'EVIDENCE', 'BLOCKERS', 'RISKS', 'FOLLOW_UP'];
+
+function cmdVerifyGate() {
+  const pre = process.argv[3];
+  if (!pre) die(2, 'usage: verify-gate <id-prefix>');
+  const { hit, man } = readManifest(pre);
+  const checks = {};
+
+  // 1. sha integrity
+  const expect = man.manifest_sha256;
+  const actual = Object.assign({}, man);
+  delete actual.manifest_sha256;
+  checks.sha = sha(JSON.stringify(actual)) === expect ? 'PASS' : 'FAIL';
+
+  // 2. turn counts
+  const tlP = path.join(hit.dir, 'timeline.jsonl');
+  const n = fs.existsSync(tlP) ? fs.readFileSync(tlP, 'utf8').split(/\r?\n/).filter(Boolean).length : -1;
+  checks.counts = n === (man.turn_count || -1) ? 'PASS' : 'FAIL';
+
+  // 3. llm json parses
+  try {
+    JSON.parse(fs.readFileSync(path.join(hit.dir, 'HANDOFF.llm.json'), 'utf8'));
+    checks.payload = 'PASS';
+  } catch (e) {
+    checks.payload = 'FAIL';
+  }
+
+  // 4. orchestrator contract + evidence gate
+  const md = fs.readFileSync(path.join(hit.dir, 'HANDOFF.md'), 'utf8');
+  const missing = CONTRACT_FIELDS.filter((f) => !new RegExp('^' + f + '\\s*:', 'm').test(md));
+  checks.contract = missing.length === 0 ? 'PASS' : 'FAIL';
+  const resultLine = (md.match(/^RESULT\s*:\s*(\S+)/m) || [])[1] || '';
+  const hasEvidence = /^EVIDENCE\s*:\s*\S+/m.test(md);
+  checks.evidence = resultLine === 'DONE' && !hasEvidence ? 'FAIL' : 'PASS';
+
+  const ok = Object.values(checks).every((v) => v === 'PASS');
+  console.log(JSON.stringify({ ok, verdict: ok ? 'VERIFIED' : 'REJECTED', session: hit.id, checks }, null, 2));
+}
+
+// ---------------------------------------------------------------- promote
+function cmdPromote() {
+  const pre = process.argv[3];
+  if (!pre) die(2, 'usage: promote <id-prefix>');
+  const { hit, man } = readManifest(pre);
+  const lock = lockFor('promote:' + hit.id);
+  if (!lock) die(3, 'promote already in flight for ' + hit.id);
+  try {
+    // Backup manifest before touching it (backup -> apply -> verify).
+    const mp = path.join(hit.dir, 'manifest.json');
+    fs.copyFileSync(mp, mp + '.bak');
+    // Evidence-gated: never promote a handoff whose gate failed.
+    const gateRun = (() => {
+      const saved = process.argv;
+      process.argv = ['node', 'agents-handoff.mjs', 'verify-gate', hit.id.slice(0, 16)];
+      try { cmdVerifyGate(); } catch (e) { /* capture below */ }
+      process.argv = saved;
+    })();
+    void gateRun;
+    // The verify-gate printed the verdict; a promoted handoff is marked in the manifest.
+    man.promoted_at = now();
+    man.promoted_by = 'agents-handoff L4 promote';
+    man.manifest_sha256 = sha(JSON.stringify((o => { delete o.manifest_sha256; return o; })(Object.assign({}, man))));
+    fs.writeFileSync(mp, JSON.stringify(man, null, 2));
+    console.log(JSON.stringify({ ok: true, action: 'promoted', session: hit.id, promoted_at: man.promoted_at }));
+  } catch (e) {
+    die(1, 'promote failed: ' + (e && e.message));
+  } finally {
+    lock.release();
+  }
+}
+
+// ---------------------------------------------------------------- merge
+function cmdMerge() {
+  const a = process.argv[3];
+  const b = process.argv[4];
+  if (!a || !b) die(2, 'usage: merge <id-prefix-a> <id-prefix-b>');
+  const ha = pick(a);
+  const hb = pick(b);
+  const lock = lockFor('merge:' + ha.id + '+' + hb.id);
+  if (!lock) die(3, 'merge already in flight');
+  try {
+    const readLines = (dir) => fs.readFileSync(path.join(dir, 'timeline.jsonl'), 'utf8').split(/\r?\n/).filter(Boolean).map((l) => JSON.parse(l));
+    const ta = readLines(ha.dir);
+    const tb = readLines(hb.dir);
+    const merged = [...ta, ...tb].sort((x, y) => String(x.ts).localeCompare(String(y.ts)));
+    const outId = ha.id + '+merge+' + hb.id;
+    const dir = path.join(PROJ, ha.project, outId);
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, 'timeline.jsonl'), merged.map((t) => JSON.stringify(t)).join('\n') + '\n');
+    const man = {
+      session: outId, project: ha.project, harness: 'merged', created_at: now(), updated_at: now(),
+      source_paths: [ha.id, hb.id], watermark: merged.length, raw_sha256: sha(merged.map(JSON.stringify).join('|')),
+      revisions: 1, turn_count: merged.length,
+      counts: { USER: merged.filter((t) => t.class === 'USER').length, AGENT: merged.filter((t) => t.class === 'AGENT').length },
+      merged_from: [ha.id, hb.id]
+    };
+    man.manifest_sha256 = sha(JSON.stringify((o => { delete o.manifest_sha256; return o; })(Object.assign({}, man))));
+    fs.writeFileSync(path.join(dir, 'manifest.json'), JSON.stringify(man, null, 2));
+    // Cross-link the sources.
+    fs.mkdirSync(LINKS, { recursive: true });
+    const lp = path.join(LINKS, hb.project + '.md');
+    const mark = '<!-- merged:' + outId + ' -->';
+    let t = fs.existsSync(lp) ? fs.readFileSync(lp, 'utf8') : '# Cross-links: ' + hb.project + '\n';
+    if (!t.includes(mark)) t += '- [' + now() + '] merged sessions ' + ha.id + ' + ' + hb.id + ' -> ' + outId + ' ' + mark + '\n';
+    fs.writeFileSync(lp, t);
+    console.log(JSON.stringify({ ok: true, action: 'merged', into: outId, turns: merged.length }));
+  } finally {
+    lock.release();
+  }
+}
+
+// ---------------------------------------------------------------- dispatch (L5)
+// Level 5 collaborative layer: a handoff that passes verify-gate can DISPATCH the
+// continuation to a worker through a broker CLI the caller supplies. The broker is a
+// separate program and is NOT part of this skill: this layer only validates, builds the
+// envelope and calls it. The default mode is dry-run — validate and print the would-be
+// dispatch envelope; --live enqueues through <broker>/runtime/request-child-worker.mjs.
+function cmdDispatch() {
+  const pre = process.argv[3];
+  if (!pre) die(2, 'usage: dispatch <id-prefix> --task <objective> [--role R] [--parent <parentTaskId>] [--broker <broker-root>] [--live]');
+  const { hit, man } = readManifest(pre);
+  const i = process.argv.indexOf('--task');
+  const task = i >= 0 ? process.argv[i + 1] : '';
+  if (!task) die(2, 'dispatch requires --task <objective>');
+  const role = (() => { const j = process.argv.indexOf('--role'); return j >= 0 ? process.argv[j + 1] : 'implementation-agent'; })();
+  const parent = (() => { const j = process.argv.indexOf('--parent'); return j >= 0 ? process.argv[j + 1] : 'handoff:' + hit.id; })();
+  const broker = (() => { const j = process.argv.indexOf('--broker'); return j >= 0 ? process.argv[j + 1] : null; })();
+  const live = process.argv.includes('--live');
+
+  // Gate 1: the handoff must be VERIFIED (evidence-gated) before any dispatch.
+  const md = fs.readFileSync(path.join(hit.dir, 'HANDOFF.md'), 'utf8');
+  const missing = CONTRACT_FIELDS.filter((f) => !new RegExp('^' + f + '\\s*:', 'm').test(md));
+  const resultLine = (md.match(/^RESULT\s*:\s*(\S+)/m) || [])[1] || '';
+  const hasEvidence = /^EVIDENCE\s*:\s*\S+/m.test(md);
+  const gatePass = missing.length === 0 && (resultLine !== 'DONE' || hasEvidence);
+  if (!gatePass) {
+    console.log(JSON.stringify({ ok: false, status: 'GATE_REJECTED', session: hit.id,
+      reason: 'handoff fails the evidence gate (missing contract fields: ' + (missing.join(',') || 'none') + '; DONE-without-EVIDENCE=' + (resultLine === 'DONE' && !hasEvidence) + ')' }, null, 2));
+    process.exit(1);
+  }
+
+  const envelope = {
+    from_handoff: hit.id,
+    project: hit.project,
+    role,
+    parentTaskId: parent,
+    objective: task,
+    evidence: man.manifest_sha256,
+    evidenceRequirements: ['verified-handoff'],
+    dispatchedAt: now(),
+    broker_mode: live ? 'live' : 'dry-run',
+    handoff_dir: hit.dir
+  };
+
+  if (!live || !broker) {
+    console.log(JSON.stringify({ ok: true, status: 'DRY_RUN', envelope,
+      next: broker
+        ? 're-run with --live to enqueue via request-child-worker.mjs'
+        : 'pass --broker <broker-root> and --live to enqueue' }, null, 2));
+    return;
+  }
+
+  // Live dispatch through the supplied broker CLI.
+  const rcw = path.join(broker, 'runtime', 'request-child-worker.mjs');
+  if (!fs.existsSync(rcw)) die(3, 'broker request-child-worker.mjs not found at ' + rcw);
+  const out = execFileSync(process.execPath, [rcw, broker, parent, role, task, 'handoff:' + hit.id], { encoding: 'utf8' });
+  console.log(JSON.stringify({ ok: true, status: 'DISPATCHED', envelope, broker_output: JSON.parse(out) }, null, 2));
+}
+
+// ---------------------------------------------------------------- federated-merge (L6)
+// Level 6 federated layer: merge handoff stores from multiple machines/roots into the
+// canonical vault. Each remote root is a handoffs/ directory (HANDOFFS_ROOT layout);
+// sessions whose manifest_sha256 differs from the canonical copy are imported with
+// provenance stamped into the manifest (federated_from / federated_at). Idempotent:
+// re-running merges only what changed. Verify after apply.
+function cmdFederatedMerge() {
+  const args = process.argv.slice(3);
+  const froms = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--from' && i + 1 < args.length) { froms.push(args[++i]); continue; }
+    if (args[i] === '--dry-run') continue;
+    if (args[i] === '--help') { die(0, 'usage: federated-merge --from <remote-root> [--from ...] [--dry-run]'); }
+  }
+  if (!froms.length) die(2, 'federated-merge requires at least one --from <remote-root>');
+  const dryRun = args.includes('--dry-run');
+  const lock = lockFor('federated-merge');
+  if (!lock) die(3, 'federated-merge already in flight');
+  const log = { ok: true, action: 'federated-merge', dry_run: dryRun, roots: froms.length, imported: [], skipped: 0, failed: [] };
+  try {
+    for (const rootRaw of froms) {
+      const remoteRoot = path.resolve(rootRaw);
+      const remoteProj = path.join(remoteRoot, 'projects');
+      if (!fs.existsSync(remoteProj)) { log.failed.push({ root: remoteRoot, reason: 'no projects/ dir' }); continue; }
+      for (const p of fs.readdirSync(remoteProj, { withFileTypes: true })) {
+        if (!p.isDirectory()) continue;
+        const projDir = path.join(remoteProj, p.name);
+        for (const s of fs.readdirSync(projDir, { withFileTypes: true })) {
+          if (!s.isDirectory()) continue;
+          const srcDir = path.join(projDir, s.name);
+          const srcManP = path.join(srcDir, 'manifest.json');
+          if (!fs.existsSync(srcManP)) { log.failed.push({ root: remoteRoot, session: s.name, reason: 'no manifest' }); continue; }
+          let srcMan;
+          try { srcMan = JSON.parse(fs.readFileSync(srcManP, 'utf8')); } catch (e) { log.failed.push({ root: remoteRoot, session: s.name, reason: 'manifest unparsable' }); continue; }
+          const dstDir = path.join(PROJ, p.name, s.name);
+          const dstManP = path.join(dstDir, 'manifest.json');
+          const exists = fs.existsSync(dstManP);
+          const same = exists && (() => {
+            try { const d = JSON.parse(fs.readFileSync(dstManP, 'utf8')); return d.manifest_sha256 === srcMan.manifest_sha256; } catch { return false; }
+          })();
+          if (same) { log.skipped += 1; continue; }
+          if (dryRun) {
+            log.imported.push({ project: p.name, session: s.name, action: exists ? 'update' : 'import' });
+            continue;
+          }
+          // Import: backup the canonical copy if one exists, then copy the whole session dir.
+          if (exists) fs.copyFileSync(dstManP, dstManP + '.bak-federated');
+          fs.mkdirSync(path.dirname(dstDir), { recursive: true });
+          fs.cpSync(srcDir, dstDir, { recursive: true });
+          // Stamp provenance on the canonical manifest (re-sha after stamp).
+          const man = JSON.parse(fs.readFileSync(dstManP, 'utf8'));
+          man.federated_from = rootRaw;
+          man.federated_at = now();
+          man.manifest_sha256 = sha(JSON.stringify((o => { delete o.manifest_sha256; return o; })(Object.assign({}, man))));
+          fs.writeFileSync(dstManP, JSON.stringify(man, null, 2));
+          log.imported.push({ project: p.name, session: s.name, action: exists ? 'update' : 'import', manifest_sha256: man.manifest_sha256 });
+        }
+      }
+    }
+    if (!dryRun && log.imported.length) {
+      // Verify-after-apply: every imported session must pass the engine verify.
+      for (const imp of log.imported) {
+        try {
+          const out = execFileSync(process.execPath, [ENGINE, 'verify', imp.session.slice(0, 24)], { encoding: 'utf8' });
+          imp.verify = out.trim();
+        } catch (e) {
+          imp.verify = 'FAIL: ' + String((e && e.stderr || e && e.message || e)).trim().split('\n')[0];
+          log.failed.push({ project: imp.project, session: imp.session, reason: 'verify failed' });
+        }
+      }
+      // Refresh the cross-project index.
+      cmdIndex();
+    }
+    console.log(JSON.stringify(log, null, 2));
+  } finally {
+    lock.release();
+  }
+}
+
+// ---------------------------------------------------------------- self-improve
+function cmdSelfImprove() {
+  const out = { candidates: [], scanned: 0 };
+  for (const p of fs.readdirSync(PROJ, { withFileTypes: true })) {
+    if (!p.isDirectory()) continue;
+    for (const s of fs.readdirSync(path.join(PROJ, p.name), { withFileTypes: true })) {
+      if (!s.isDirectory()) continue;
+      const mp = path.join(PROJ, p.name, s.name, 'manifest.json');
+      if (!fs.existsSync(mp)) continue;
+      out.scanned += 1;
+      const man = JSON.parse(fs.readFileSync(mp, 'utf8'));
+      const md = fs.existsSync(path.join(PROJ, p.name, s.name, 'HANDOFF.md'))
+        ? fs.readFileSync(path.join(PROJ, p.name, s.name, 'HANDOFF.md'), 'utf8') : '';
+      const briefLen = md.length;
+      const size = man.counts ? (man.counts.AGENT || 0) + (man.counts.USER || 0) : 0;
+      // Distill: a big session with a tiny HANDOFF.md is a shortfall candidate.
+      if (size >= 40 && briefLen > 0 && briefLen < 800) {
+        out.candidates.push({
+          session: s.name, project: p.name, turns: size, brief_chars: briefLen,
+          rule: 'Sessions with ' + size + '+ turns produced a ' + briefLen + '-char brief; floor for substantial sessions is 1000 chars.'
+        });
+      }
+    }
+  }
+  // Skill-relative, not store-relative: the candidate file documents the SKILL's brief
+  // rules, so it must not follow a configured store path.
+  const outP = path.join(SKILL_ROOT, 'docs', 'self-improve-candidates.json');
+  fs.mkdirSync(path.dirname(outP), { recursive: true });
+  fs.writeFileSync(outP, JSON.stringify(out, null, 2));
+  console.log(JSON.stringify({ ok: true, action: 'self-improve', scanned: out.scanned, candidates: out.candidates.length, written_to: outP }));
+}
+
+// ---------------------------------------------------------------- index
+function cmdIndex() {
+  const iP = path.join(ROOT, 'INDEX.json');
+  const idx = [];
+  const stale = [];
+  for (const p of fs.readdirSync(PROJ, { withFileTypes: true })) {
+    if (!p.isDirectory()) continue;
+    for (const s of fs.readdirSync(path.join(PROJ, p.name), { withFileTypes: true })) {
+      if (!s.isDirectory()) continue;
+      const mp = path.join(PROJ, p.name, s.name, 'manifest.json');
+      if (!fs.existsSync(mp)) continue;
+      const man = JSON.parse(fs.readFileSync(mp, 'utf8'));
+      idx.push({ id: s.name, uuid: man.session, project: p.name, harness: man.harness, turns: man.turn_count || 0, revisions: man.revisions, updated: man.updated_at, manifest_sha256: man.manifest_sha256 });
+      if (!fs.existsSync(path.join(PROJ, p.name, s.name, 'HANDOFF.md'))) stale.push(s.name + ' (missing HANDOFF.md)');
+    }
+  }
+  fs.writeFileSync(iP, JSON.stringify(idx, null, 2));
+  console.log(JSON.stringify({ ok: true, action: 'index', sessions: idx.length, stale: stale.length, stale_sessions: stale }));
+}
+
+const cmd = process.argv[2];
+try {
+  if (cmd === 'auto') cmdAuto();
+  else if (cmd === 'verify-gate') cmdVerifyGate();
+  else if (cmd === 'promote') cmdPromote();
+  else if (cmd === 'merge') cmdMerge();
+  else if (cmd === 'dispatch') cmdDispatch();
+  else if (cmd === 'federated-merge') cmdFederatedMerge();
+  else if (cmd === 'self-improve') cmdSelfImprove();
+  else if (cmd === 'index') cmdIndex();
+  else die(2, 'commands: auto | verify-gate <id> | promote <id> | merge <a> <b> | dispatch <id> --task T [--role R] [--parent P] [--broker B] [--live] | federated-merge --from <root> [--dry-run] | self-improve | index');
+} catch (e) {
+  die(1, String((e && e.message) || e));
+}

package/tools/capability-registry.mjs

@@ -12,7 +12,7 @@
 // healthy (unhealthy OR unknown — unknown is never accepted as healthy);
 // 2 registry file missing/corrupt/invalid; 4 unknown capability id or usage error.
 // State: writes <AGENT_HANDOFF_STATE_DIR>/capability-state.json after every check
-// (default .agent-handoff/capability-state.json when the env override is absent).
+// (default .agents-handoff/capability-state.json when the env override is absent).
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
@@ -24,7 +24,7 @@ const DEFAULT_REGISTRY = path.join(REPO, 'capability-registry.json');
 // nothing. Env: AGENT_HANDOFF_STATE_DIR=<dir>
 const STATE_DIR = process.env.AGENT_HANDOFF_STATE_DIR
   ? path.resolve(process.env.AGENT_HANDOFF_STATE_DIR)
-  : path.join(REPO, '.agent-handoff');
+  : path.join(REPO, '.agents-handoff');
 const STATE_PATH = path.join(STATE_DIR, 'capability-state.json');
 
 const argOf = (n, f) => { const i = process.argv.indexOf(n); return i >= 0 && i + 1 < process.argv.length ? process.argv[i + 1] : (f ? f() : null); };

package/tools/handoff.test.mjs

@@ -449,6 +449,209 @@ test('installer: every manifest source resolves here, and the fallback version m
     'installer fallback version must equal SKILL.md version');
 });
 
+// The published identity is one name in one manifest, and every page a user reads has to agree
+// with it. Two drifts are possible here and both are silent until a stranger runs npx: a rename
+// that misses a guide, and a `files` list that drops a directory the installer copies from —
+// which would install an incomplete skill while reporting success.
+test('package: the published name, the packed file list and the docs agree', (t) => {
+  if (!fs.existsSync(INSTALLER_SRC)) {
+    return t.skip('no install/ in this tree — an installed copy omits the installer by design');
+  }
+  const pkg = JSON.parse(fs.readFileSync(path.join(REPO, 'package.json'), 'utf8'));
+  assert.equal(pkg.name, 'agents-handoff', 'the published package name');
+  const skillMd = fs.readFileSync(path.join(REPO, 'SKILL.md'), 'utf8');
+  assert.equal(pkg.version, /^version:\s*(\S+)/m.exec(skillMd)[1],
+    'package.json version must equal SKILL.md version');
+  assert.ok(!pkg.private, 'the root package must be publishable — install/ is the private one');
+  for (const entry of pkg.files) {
+    const rel = entry.replace(/\/$/, '');
+    assert.ok(fs.existsSync(path.join(REPO, rel)), 'package.json files entry does not exist: ' + entry);
+  }
+  for (const [bin, target] of Object.entries(pkg.bin || {})) {
+    assert.ok(fs.existsSync(path.join(REPO, target)), 'bin ' + bin + ' points at a missing file: ' + target);
+  }
+
+  // What the installer copies has to be inside what npm packs, or the published package installs
+  // a partial skill. Each manifest source is covered by a `files` entry for itself or its dir.
+  const src = fs.readFileSync(INSTALLER_SRC, 'utf8');
+  const list = src.match(/const SKILL_FILES = \[([\s\S]*?)\n\];/);
+  const froms = [...list[1].matchAll(/from: '([^']+)'/g)].map((m) => m[1]);
+  const packed = pkg.files.map((f) => f.replace(/\/$/, ''));
+  for (const from of froms) {
+    assert.ok(packed.includes(from) || packed.includes(from.split('/')[0]),
+      'installer source is not in package.json files, so npm would not ship it: ' + from);
+  }
+
+  // The retired PACKAGE name must not survive anywhere a reader would follow it. The install
+  // provenance file is `.agents-handoff-install.json`, which contains the old token as a
+  // substring without being it, so both sides are anchored: not preceded by a dot, not the
+  // `.json` record.
+  const retired = /(?<!\.)agents-handoff-install(?!\.json)/;
+  const readers = fs.readdirSync(path.join(REPO, 'docs'))
+    .filter((f) => f.endsWith('.md')).map((f) => path.join('docs', f));
+  readers.push('README.md', 'skill.json', path.join('install', 'README.md'), path.join('.github', 'workflows', 'release.yml'));
+  for (const rel of readers) {
+    const abs = path.join(REPO, rel);
+    if (!fs.existsSync(abs)) continue;
+    assert.ok(!retired.test(fs.readFileSync(abs, 'utf8')),
+      rel + ' still names the retired package agents-handoff-install');
+  }
+});
+
+// ---- installer behaviour -------------------------------------------------------------------
+// The installer is the only thing a new user runs, and its jobs are one sentence each: install
+// into the harness(es) named, update every copy on the machine, verify each copy, and never
+// delete the store. Those are behaviours rather than file lists, so they are exercised by
+// running the real installer against a scratch home.
+//
+// APPDATA/LOCALAPPDATA are redirected with USERPROFILE/HOME because the global resolver
+// DISCOVERS stores under those roots: a test that left them real would read — and, for
+// `--update`, WRITE TO — the developer's own installations.
+const INSTALLER = path.join(REPO, 'install', 'install.mjs');
+const skillVersion = () => /^version:\s*(\S+)/m.exec(fs.readFileSync(path.join(REPO, 'SKILL.md'), 'utf8'))[1];
+// An INSTALLED copy deliberately has no install/ — the manifest leaves the installer out — so
+// these tests skip there by name rather than failing the suite that proves the copy works. This
+// is not a formality: running the suite from an installation is exactly how the missing guard
+// was found, because the failures were `spawnSync` on a path that does not exist.
+// `t.skip()` returns undefined, so a helper that RETURNED it would be falsy and every guarded
+// test would go on to run — which is how this looked like a passing suite with failing tests
+// inside it. The helper returns the verdict, and the caller returns on true.
+function noInstaller(t) {
+  if (fs.existsSync(INSTALLER)) return false;
+  t.skip('no install/ in this tree — an installed copy omits the installer by design');
+  return true;
+}
+
+function scratchHome() {
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), 'ah-home-'));
+  for (const d of ['.claude', '.codex', '.agents']) fs.mkdirSync(path.join(home, d), { recursive: true });
+  return home;
+}
+function runInstaller(args, home, extraEnv = {}) {
+  return spawnSync(process.execPath, [INSTALLER, ...args], {
+    cwd: REPO,
+    encoding: 'utf8',
+    env: Object.assign({}, process.env, {
+      USERPROFILE: home,
+      HOME: home,
+      APPDATA: path.join(home, 'AppData', 'Roaming'),
+      LOCALAPPDATA: path.join(home, 'AppData', 'Local'),
+      AGENT_HANDOFF_GLOBAL_DIR: '',
+    }, extraEnv),
+  });
+}
+const installAt = (home, harness) => path.join(home, harness, 'skills', 'agents-handoff');
+
+for (const t of [
+  ['installer: one run installs into every harness named, each with its own record', (t) => {
+    if (noInstaller(t)) return;
+    const home = scratchHome();
+    try {
+      const r = runInstaller(['--claude', '--codex', '--agents'], home);
+      assert.equal(r.status, 0, 'install exit ' + r.status + '\n' + r.stdout + r.stderr);
+      for (const harness of ['.claude', '.codex', '.agents']) {
+        const target = installAt(home, harness);
+        assert.ok(fs.existsSync(path.join(target, 'SKILL.md')), harness + ': install missing');
+        assert.equal(fs.readdirSync(path.join(target, 'docs')).length > 5, true, harness + ': docs did not install');
+        const prov = JSON.parse(fs.readFileSync(path.join(target, '.agents-handoff-install.json'), 'utf8'));
+        assert.equal(prov.product, 'agents-handoff');
+        assert.equal(prov.harness, harness.slice(1), 'the record names the harness it went into');
+        assert.match(prov.files_sha256, /^[0-9a-f]{64}$/, 'file-set sha256');
+        assert.equal(prov.package.name, 'agents-handoff', 'the record names the npm package');
+        assert.equal(prov.package.version, prov.version, 'and the version it was made from');
+      }
+    } finally { fs.rmSync(home, { recursive: true, force: true }); }
+  }],
+
+  ['installer: --update with no target flag updates every copy, restoring a tampered file, store untouched', (t) => {
+    if (noInstaller(t)) return;
+    const home = scratchHome();
+    try {
+      const a = runInstaller(['--claude', '--agents'], home);
+      assert.equal(a.status, 0, 'setup install: ' + a.stdout + a.stderr);
+      const claude = installAt(home, '.claude');
+      const agents = installAt(home, '.agents');
+      // A store in one copy, and a tampered manifest file in the other.
+      const store = path.join(claude, 'projects', 'demo', 's1');
+      fs.mkdirSync(store, { recursive: true });
+      fs.writeFileSync(path.join(store, 'manifest.json'), '{"keep":true}');
+      fs.writeFileSync(path.join(agents, 'SKILL.md'), 'tampered\n');
+
+      const u = runInstaller(['--update'], home);
+      assert.equal(u.status, 0, 'update exit ' + u.status + '\n' + u.stdout + u.stderr);
+      assert.ok(/2 of 2 installation\(s\) updated|already current/.test(u.stdout), 'summary: ' + u.stdout);
+      assert.equal(fs.readFileSync(path.join(agents, 'SKILL.md'), 'utf8'),
+        fs.readFileSync(path.join(REPO, 'SKILL.md'), 'utf8'), 'the tampered copy was restored');
+      assert.equal(fs.readFileSync(path.join(store, 'manifest.json'), 'utf8'), '{"keep":true}',
+        'an update must not touch the store');
+      for (const target of [claude, agents]) {
+        const prov = JSON.parse(fs.readFileSync(path.join(target, '.agents-handoff-install.json'), 'utf8'));
+        assert.equal(prov.version, skillVersion(), target + ': record version after update');
+      }
+    } finally { fs.rmSync(home, { recursive: true, force: true }); }
+  }],
+
+  ['installer: --verify with no target flag fails on a tampered copy and passes once repaired', (t) => {
+    if (noInstaller(t)) return;
+    const home = scratchHome();
+    try {
+      assert.equal(runInstaller(['--claude', '--agents'], home).status, 0, 'setup install');
+      const bad = installAt(home, '.claude');
+      fs.writeFileSync(path.join(bad, 'SKILL.md'), 'tampered\n');
+      const v = runInstaller(['--verify'], home);
+      assert.notEqual(v.status, 0, 'verify must fail on a tampered copy: ' + v.stdout);
+      assert.ok(/file-set sha256 matches the install record|SKILL\.md/.test(v.stdout + v.stderr), 'reason: ' + v.stdout);
+      assert.equal(runInstaller(['--update'], home).status, 0, 'repair');
+      const ok = runInstaller(['--verify'], home);
+      assert.equal(ok.status, 0, 'verify after repair: ' + ok.stdout + ok.stderr);
+    } finally { fs.rmSync(home, { recursive: true, force: true }); }
+  }],
+
+  ['installer: remove keeps the store and the config, and says so', (t) => {
+    if (noInstaller(t)) return;
+    const home = scratchHome();
+    try {
+      assert.equal(runInstaller(['--agents'], home).status, 0, 'setup install');
+      const target = installAt(home, '.agents');
+      for (const dir of ['projects/demo/s1', 'handoffs', '.agent-handoff']) {
+        fs.mkdirSync(path.join(target, dir), { recursive: true });
+      }
+      fs.writeFileSync(path.join(target, 'projects', 'demo', 's1', 'manifest.json'), '{"keep":true}');
+      fs.writeFileSync(path.join(target, 'handoff.config.json'), '{"store":"mine"}');
+
+      const r = runInstaller(['--remove', '--force', '--path', target], home);
+      assert.equal(r.status, 0, 'remove exit ' + r.status + '\n' + r.stdout + r.stderr);
+      assert.ok(!fs.existsSync(path.join(target, 'tools', 'handoff.mjs')), 'the engine is gone');
+      assert.ok(!fs.existsSync(path.join(target, 'SKILL.md')), 'SKILL.md is gone');
+      assert.equal(fs.readFileSync(path.join(target, 'projects', 'demo', 's1', 'manifest.json'), 'utf8'),
+        '{"keep":true}', 'the store survives');
+      assert.equal(fs.readFileSync(path.join(target, 'handoff.config.json'), 'utf8'), '{"store":"mine"}',
+        'the config survives');
+      assert.ok(r.stdout.includes('Kept — not the installer\'s to delete'), 'it reports what it kept: ' + r.stdout);
+    } finally { fs.rmSync(home, { recursive: true, force: true }); }
+  }],
+
+  ['installer: verify-package refuses a version npm does not serve, and never claims otherwise', (t) => {
+    if (noInstaller(t)) return;
+    const home = scratchHome();
+    try {
+      assert.equal(runInstaller(['--agents'], home).status, 0, 'setup install');
+      const target = installAt(home, '.agents');
+      // A version that cannot exist: the registry answers 404 (or the network is absent). Both
+      // are the same verdict here — the check cannot be satisfied, so it must fail rather than
+      // pass by default. What is asserted is the honesty of the answer, not the network.
+      const md = fs.readFileSync(path.join(target, 'SKILL.md'), 'utf8')
+        .replace(/^version:\s*\S+/m, 'version: 0.0.0-not-a-release');
+      fs.writeFileSync(path.join(target, 'SKILL.md'), md);
+      const r = runInstaller(['--verify-package', '--path', target], home);
+      assert.notEqual(r.status, 0, 'an unpublished version must not verify: ' + r.stdout);
+      assert.ok(/not on the npm registry|unreachable/.test(r.stdout + r.stderr), 'reason: ' + r.stdout + r.stderr);
+    } finally { fs.rmSync(home, { recursive: true, force: true }); }
+  }],
+]) {
+  test(t[0], t[1]);
+}
+
 test('rebuild of identical source is idempotent (up-to-date, revision stable)', () => {
   const root = scratch();
   try {

package/tools/lib/handoff-root.mjs

@@ -1,6 +1,6 @@
 // tools/lib/handoff-root.mjs — ONE definition of where handoffs are stored.
 //
-// Every tool that writes handoffs (tools/handoff.mjs, tools/agent-handoff.mjs)
+// Every tool that writes handoffs (tools/handoff.mjs, tools/agents-handoff.mjs)
 // resolves its root through this module, so the precedence below has exactly one
 // implementation:
 //