@khoavu882/doflow 0.0.0-stage → 2.0.0-beta.4

package/src/runtime/worktree.js

@@ -0,0 +1,340 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+/**
+ * Ephemeral git worktrees for isolated task execution — the JavaScript port of
+ * `core/shared/scripts/doflow/sandbox/worktree_manager.py` (plan task B.3, pulled forward because
+ * A.3's baseline capture cannot run safely without it).
+ *
+ * Why this exists: bench cases invoke skills that write files, create branches, or
+ * commit. Running them in the repo that is executing the plan would mutate the very tree under
+ * test. Each run gets its own worktree so the blast radius of a misbehaving skill is one
+ * throwaway directory.
+ *
+ * Three defects in the Python original are fixed here rather than reproduced. Plan decision D3
+ * says port from observed behaviour rather than from the specification — that was about not losing
+ * capability (recovery's eleven failure classes), not about preserving bugs:
+ *   1. `create_worktree` returned early when the directory existed without checking the branch
+ *      existed too, so a half-removed worktree resolved to an unusable path.
+ *   2. `collect_diff` ran `git diff HEAD~1`, which fails on a worktree with fewer than two commits
+ *      and returned null — conflating "no changes" with "could not tell".
+ *   3. `remove_worktree` deleted the directory but left the `task/<id>` branch behind, so repeated
+ *      runs accumulated branches indefinitely.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { execFileSync } = require('node:child_process');
+
+/** Worktree ids become branch names and directory names, so anything outside this set is a
+ * potential argument-injection or path-traversal vector. Rejecting loudly beats sanitising
+ * silently: a caller passing a bad id has a bug worth seeing. */
+const SAFE_ID = /^[A-Za-z0-9._-]+$/;
+
+/** Records the base commit a sandbox was cut from. Lives inside the worktree so it survives a
+ * process boundary; excluded from collected diffs since it is harness bookkeeping, not task work. */
+const BASE_FILE = '.doflow-worktree-base';
+
+/**
+ * Records which skill source a sandbox carries (plan task A.5). Written inside the worktree for the
+ * same reason as BASE_FILE: grading may run in a different process from execution, and a run that
+ * cannot say which skills it measured is not evidence of anything.
+ */
+const SKILL_SOURCE_FILE = '.doflow-skill-source.json';
+
+/** Where the claude adapter lands skills inside an installed project. Not invented here — this is
+ * the adapter's own layout, which is the point: the sandbox holds a real projection, not a copy
+ * that can drift from one. */
+const SANDBOX_SKILLS_DIR = path.join('.claude', 'skills');
+
+/** Source of truth for skill content, relative to the repo root. */
+const SOURCE_SKILLS_DIR = path.join('core', 'shared', 'skills');
+
+function sha256File(file        )         {
+  return crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+}
+
+function git(args          , cwd        , { allowFailure = false }                             = {})                                                   {
+  try {
+    return {
+      ok: true,
+      stdout: execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }),
+    };
+  } catch (err     ) {
+    if (!allowFailure) throw err;
+    return { ok: false, stdout: '', stderr: err.stderr ? String(err.stderr) : String(err.message) };
+  }
+}
+
+class WorktreeManager {
+  repoRoot        ;
+  worktreesDir        ;
+
+  /**
+   * @param {string} repoRoot repository whose worktrees are managed
+   * @param {string} [worktreesDir] override the sandbox root; defaults to `<repo>/.doflow/worktrees`,
+   *   which is gitignored so sandboxes never appear as untracked noise in the parent tree.
+   */
+  constructor(repoRoot        , worktreesDir         ) {
+    this.repoRoot = repoRoot;
+    this.worktreesDir = worktreesDir || path.join(repoRoot, '.doflow', 'worktrees');
+  }
+
+  static assertSafeId(taskId     )       {
+    if (!taskId || !SAFE_ID.test(taskId)) {
+      throw new Error(`unsafe worktree id ${JSON.stringify(taskId)} — allowed: letters, digits, dot, dash, underscore`);
+    }
+  }
+
+  pathFor(taskId        )         {
+    WorktreeManager.assertSafeId(taskId);
+    return path.join(this.worktreesDir, taskId);
+  }
+
+  branchFor(taskId        )         {
+    WorktreeManager.assertSafeId(taskId);
+    return `task/${taskId}`;
+  }
+
+  /** Whether git itself considers this path a registered worktree — the directory existing on disk
+   * is not the same question, which is the bug fixed here. */
+  isRegistered(wtPath        )          {
+    const res = git(['worktree', 'list', '--porcelain'], this.repoRoot, { allowFailure: true });
+    if (!res.ok) return false;
+    const resolved = path.resolve(wtPath);
+    return res.stdout
+      .split('\n')
+      .filter((l        ) => l.startsWith('worktree '))
+      .some((l        ) => path.resolve(l.slice('worktree '.length).trim()) === resolved);
+  }
+
+  /**
+   * Create an isolated worktree, reusing it only when git agrees it is registered. Returns the
+   * absolute path.
+   */
+  create(taskId        , baseRef         = 'HEAD')         {
+    const wtPath = this.pathFor(taskId);
+    const branch = this.branchFor(taskId);
+
+    if (this.isRegistered(wtPath)) return wtPath;
+
+    // A leftover directory that git does not know about blocks `worktree add`. Clear it, and
+    // prune git's stale administrative records, before trying.
+    if (fs.existsSync(wtPath)) fs.rmSync(wtPath, { recursive: true, force: true });
+    git(['worktree', 'prune'], this.repoRoot, { allowFailure: true });
+
+    fs.mkdirSync(this.worktreesDir, { recursive: true });
+
+    const branchExists = git(['rev-parse', '--verify', '--quiet', branch], this.repoRoot, { allowFailure: true }).ok;
+    const args = branchExists
+      ? ['worktree', 'add', wtPath, branch]
+      : ['worktree', 'add', '-b', branch, wtPath, baseRef];
+    git(args, this.repoRoot);
+
+    // Persist the base as a resolved SHA. A symbolic ref is useless later: inside the worktree
+    // `HEAD` moves with every commit the task makes, so diffing against it reports nothing. The
+    // file also survives a process boundary, since grading may run separately from execution.
+    const baseSha = git(['rev-parse', baseRef], this.repoRoot).stdout.trim();
+    fs.writeFileSync(path.join(wtPath, BASE_FILE), `${baseSha}\n`);
+    return wtPath;
+  }
+
+  /** The resolved base SHA recorded at creation, or null when unavailable. */
+  baseOf(taskId        )                {
+    const file = path.join(this.pathFor(taskId), BASE_FILE);
+    return fs.existsSync(file) ? fs.readFileSync(file, 'utf8').trim() : null;
+  }
+
+  /**
+   * Materialise **this repo's** skills inside the sandbox and record exactly what landed there.
+   *
+   * Why this is not optional for an evaluation sandbox: Claude Code resolves a bare skill name from
+   * user scope (`~/.claude/skills/`) before project scope, and first match wins — so a run that
+   * invokes `/do-code-review` measures whatever is globally installed, not the tree under test.
+   * Verified against 2.1.226 (`lE()` is a first-match lookup over a list ordered policy → user →
+   * project) and observed live: a project-scope `do-git` shadow was ignored in favour of the
+   * installed copy. Twelve of the thirteen installed skills currently differ from this repo's
+   * source, so the difference is not hypothetical.
+   *
+   * Projecting here therefore does *not* win the name lookup — nothing can, in-process. What it
+   * buys is a known-good copy at a known path with recorded hashes, which is what makes the
+   * by-path dispatch contract (see `bench/README.md`) checkable rather than trusted.
+   *
+   * The real installer is used rather than a hand-copy so the sandbox exercises the actual
+   * projection, including the guidance, scripts and templates the skills reference — a SKILL.md
+   * copied alone would leave every `references/` path dangling and change the behaviour being
+   * measured. It costs ~0.15s per sandbox.
+   *
+   * Writes the manifest before validating, so a failed projection is still diagnosable, then throws
+   * if any skill is missing or does not match source.
+   *
+   * @returns {object} the manifest also written to `<worktree>/.doflow-skill-source.json`
+   */
+  projectSkills(taskId        , { harness = 'claude', cli = path.join('bin', 'doflow.js'), skillsRoot = SOURCE_SKILLS_DIR }                                                          = {})      {
+    const wtPath = this.pathFor(taskId);
+    if (!fs.existsSync(wtPath)) {
+      throw new Error(`no worktree at ${wtPath} — create it before projecting skills`);
+    }
+    const sourceRoot = path.join(this.repoRoot, skillsRoot);
+    if (!fs.existsSync(sourceRoot)) {
+      throw new Error(`no skill source at ${sourceRoot}`);
+    }
+
+    let installOutput        ;
+    try {
+      installOutput = execFileSync(
+        process.execPath,
+        [path.join(this.repoRoot, cli), 'install', wtPath, '--force', '-t', harness],
+        { cwd: this.repoRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] },
+      );
+    } catch (err     ) {
+      throw new Error(`projecting skills into ${wtPath} failed: ${err.stderr || err.message}`);
+    }
+
+    const names = fs
+      .readdirSync(sourceRoot, { withFileTypes: true })
+      .filter((e     ) => e.isDirectory() && fs.existsSync(path.join(sourceRoot, e.name, 'SKILL.md')))
+      .map((e     ) => e.name)
+      .sort();
+
+    const skills                      = {};
+    const mismatches           = [];
+    for (const name of names) {
+      const rel = path.join(SANDBOX_SKILLS_DIR, name, 'SKILL.md');
+      const dst = path.join(wtPath, rel);
+      const sourceSha256 = sha256File(path.join(sourceRoot, name, 'SKILL.md'));
+      const sha256 = fs.existsSync(dst) ? sha256File(dst) : null;
+      skills[name] = { path: rel, sha256, sourceSha256, matchesSource: sha256 === sourceSha256 };
+      if (sha256 !== sourceSha256) mismatches.push(name);
+    }
+
+    const manifest = {
+      generatedAt: new Date().toISOString(),
+      taskId,
+      repoRoot: this.repoRoot,
+      sourceRoot: skillsRoot,
+      sourceCommit: this.headCommit(),
+      harness,
+      projectedBy: `${cli} install <sandbox> --force -t ${harness}`,
+      skillsDir: path.join(wtPath, SANDBOX_SKILLS_DIR),
+      skillsDirRelative: SANDBOX_SKILLS_DIR,
+      skillCount: names.length,
+      mismatches,
+      skills,
+      installLog: (installOutput || '').trim().split('\n').slice(-3),
+    };
+    fs.writeFileSync(path.join(wtPath, SKILL_SOURCE_FILE), `${JSON.stringify(manifest, null, 2)}\n`);
+
+    if (mismatches.length) {
+      throw new Error(
+        `sandbox ${taskId} does not carry this repo's skills (${mismatches.join(', ')}) — ` +
+          `a run against it would measure something else. See ${path.join(wtPath, SKILL_SOURCE_FILE)}`,
+      );
+    }
+    return manifest;
+  }
+
+  /** The skill-source manifest a sandbox recorded, or null when it was never projected. */
+  skillSourceOf(taskId        )      {
+    const file = path.join(this.pathFor(taskId), SKILL_SOURCE_FILE);
+    if (!fs.existsSync(file)) return null;
+    try {
+      return JSON.parse(fs.readFileSync(file, 'utf8'));
+    } catch {
+      return null;
+    }
+  }
+
+  /** Repo HEAD, or null outside a repository. Recorded for readability; the per-skill hashes are
+   * the actual provenance, and they stay correct on a dirty tree where a commit id does not. */
+  headCommit()                {
+    const res = git(['rev-parse', 'HEAD'], this.repoRoot, { allowFailure: true });
+    return res.ok ? res.stdout.trim() : null;
+  }
+
+  /**
+   * One call for the shape an evaluation run needs: an isolated worktree that carries this repo's
+   * skills. Split from `create()` because non-evaluation callers want a bare worktree and should
+   * not pay for a projection they will not read.
+   */
+  createSandbox(taskId        , { baseRef = 'HEAD', ...opts }                                           = {})                                  {
+    const wtPath = this.create(taskId, baseRef);
+    return { path: wtPath, manifest: this.projectSkills(taskId, opts) };
+  }
+
+  /** Remove the worktree and its branch. Idempotent: removing something absent is success. */
+  remove(taskId        )       {
+    const wtPath = this.pathFor(taskId);
+    const branch = this.branchFor(taskId);
+
+    git(['worktree', 'remove', '--force', wtPath], this.repoRoot, { allowFailure: true });
+    if (fs.existsSync(wtPath)) fs.rmSync(wtPath, { recursive: true, force: true });
+    git(['worktree', 'prune'], this.repoRoot, { allowFailure: true });
+    // Deleting the branch is what keeps repeated bench runs from accumulating one branch per case.
+    git(['branch', '-D', branch], this.repoRoot, { allowFailure: true });
+  }
+
+  /**
+   * What the task actually changed inside its sandbox: committed diff against the base ref plus
+   * anything still uncommitted. Returns `{ diff, untracked, error }` — `error` is set rather than
+   * collapsing a failure into an empty diff, so a caller can tell "nothing changed" from
+   * "could not tell", which the Python version could not.
+   */
+  collectDiff(taskId        , baseRef         )                                                                                 {
+    const wtPath = this.pathFor(taskId);
+    if (!fs.existsSync(wtPath)) {
+      return { diff: null, untracked: [], error: `no worktree at ${wtPath}` };
+    }
+    // Default to the SHA recorded at creation, never to `HEAD` — see create().
+    const base = baseRef || this.baseOf(taskId);
+    if (!base) {
+      return { diff: null, untracked: [], error: `no recorded base for ${taskId}; pass baseRef explicitly` };
+    }
+    const committed = git(['diff', `${base}...HEAD`], wtPath, { allowFailure: true });
+    const working = git(['diff', 'HEAD'], wtPath, { allowFailure: true });
+    const untracked = git(['ls-files', '--others', '--exclude-standard'], wtPath, { allowFailure: true });
+
+    if (!committed.ok && !working.ok) {
+      return { diff: null, untracked: [], error: committed.stderr || working.stderr };
+    }
+    return {
+      diff: `${committed.ok ? committed.stdout : ''}${working.ok ? working.stdout : ''}`,
+      // Harness bookkeeping is not task work: the base pointer and the skill-source manifest are
+      // written by this module, not by the skill under test.
+      untracked: untracked.ok
+        ? untracked.stdout.split('\n').filter((f        ) => f && f !== BASE_FILE && f !== SKILL_SOURCE_FILE)
+        : [],
+      error: null,
+    };
+  }
+
+  /** Every sandbox this manager knows about — used to clean up after an interrupted run. */
+  list()           {
+    if (!fs.existsSync(this.worktreesDir)) return [];
+    return fs
+      .readdirSync(this.worktreesDir, { withFileTypes: true })
+      .filter((e     ) => e.isDirectory())
+      .map((e     ) => e.name);
+  }
+
+  /** Run `fn(worktreePath)` in a fresh sandbox and always tear it down, even when `fn` throws. */
+  withWorktree(taskId        , fn                         , baseRef         = 'HEAD')      {
+    const wtPath = this.create(taskId, baseRef);
+    try {
+      return fn(wtPath);
+    } finally {
+      this.remove(taskId);
+    }
+  }
+}
+
+module.exports = {
+  WorktreeManager,
+  BASE_FILE,
+  SKILL_SOURCE_FILE,
+  SANDBOX_SKILLS_DIR,
+  SOURCE_SKILLS_DIR,
+  sha256File,
+};

package/src/state/index.js

@@ -0,0 +1,193 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+// Neutral DoFlow lifecycle state.  This module intentionally has no knowledge of a harness's
+// native directory: callers provide a project root or user home, and adapter-owned paths stay in
+// adapter records.  Legacy manifests are an import source only; they are never changed here.
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { manifestPath, readManifest } = require('../install/manifest.js');
+
+const STATE_VERSION = 1;
+// Ledger document version. v1 ledgers (no tombstones) remain readable forever; writers produce
+// v2, which adds the append-only tombstone log used by the reconciler to remember moved targets.
+const LEDGER_VERSION = 2;
+const LEDGER_FILE = 'ledger.json';
+const RECOVERY_DIR = 'recovery';
+
+function assertScope(scope     )       {
+  if (scope !== 'project' && scope !== 'global') throw new Error(`Invalid state scope: '${scope}'`);
+}
+
+/** Resolve DoFlow-owned state without deriving it from a harness directory. */
+function stateRoot({ scope, projectRoot = '.', homeDir = os.homedir() }                                                        )         {
+  assertScope(scope);
+  return scope === 'project'
+    ? path.join(path.resolve(projectRoot), '.doflow', 'state')
+    : path.join(path.resolve(homeDir), '.doflow', 'state');
+}
+
+function ledgerPath(root        )         { return path.join(root, LEDGER_FILE); }
+function recoveryRoot(root        )         { return path.join(root, RECOVERY_DIR); }
+
+function stable(value     )      {
+  if (Array.isArray(value)) return value.map(stable);
+  if (!value || typeof value !== 'object') return value;
+  return Object.fromEntries(Object.keys(value).sort().map((key) => [key, stable(value[key])]));
+}
+
+function fingerprint(value     )         {
+  return crypto.createHash('sha256').update(JSON.stringify(stable(value))).digest('hex');
+}
+
+function atomicJsonWrite(file        , value     , { fsImpl = fs }                   = {})         {
+  fsImpl.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = path.join(path.dirname(file), `.${path.basename(file)}.${process.pid}.${Date.now()}.tmp`);
+  try {
+    fsImpl.writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, { encoding: 'utf8', flag: 'wx' });
+    fsImpl.renameSync(tmp, file);
+  } finally {
+    if (fsImpl.existsSync(tmp)) fsImpl.rmSync(tmp, { force: true });
+  }
+  return file;
+}
+
+function defaultLedger({ scope, scopeRoot }                                   )      {
+  assertScope(scope);
+  return {
+    version: LEDGER_VERSION,
+    scope,
+    scopeRoot: path.resolve(scopeRoot),
+    targets: {},
+    mcpSelections: {},
+    resources: [],
+    legacyImports: [],
+    lastRecoveryId: null,
+    guidanceVersion: null,
+    tombstones: [],
+  };
+}
+
+/** Upgrade a v1 ledger in memory to the current shape without touching disk. Idempotent. */
+function upgradeLedger(ledger     )      {
+  if (!ledger || typeof ledger !== 'object') throw new Error('Invalid neutral ledger: expected object');
+  if (ledger.version === LEDGER_VERSION) return ledger;
+  return { ...ledger, version: LEDGER_VERSION, tombstones: Array.isArray(ledger.tombstones) ? ledger.tombstones : [] };
+}
+
+function validateLedger(value     )      {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('Invalid neutral ledger: expected object');
+  if (![STATE_VERSION, LEDGER_VERSION].includes(value.version)) throw new Error(`Unsupported neutral ledger version: '${value.version}'`);
+  if (value.version >= LEDGER_VERSION && value.tombstones !== undefined && !Array.isArray(value.tombstones)) {
+    throw new Error('Invalid neutral ledger: tombstones must be an array');
+  }
+  assertScope(value.scope);
+  if (typeof value.scopeRoot !== 'string' || !path.isAbsolute(value.scopeRoot)) throw new Error('Invalid neutral ledger: scopeRoot must be absolute');
+  for (const field of ['targets', 'mcpSelections']) if (!value[field] || typeof value[field] !== 'object' || Array.isArray(value[field])) throw new Error(`Invalid neutral ledger: ${field} must be an object`);
+  for (const field of ['resources', 'legacyImports']) if (!Array.isArray(value[field])) throw new Error(`Invalid neutral ledger: ${field} must be an array`);
+  return value;
+}
+
+function readLedger(root        , { fsImpl = fs }                   = {})      {
+  const file = ledgerPath(root);
+  if (!fsImpl.existsSync(file)) return null;
+  try { return validateLedger(JSON.parse(fsImpl.readFileSync(file, 'utf8'))); }
+  catch (error     ) { throw new Error(`Cannot read neutral ledger '${file}': ${error.message}`); }
+}
+
+function writeLedger(root        , ledger     , options                   = {})         {
+  return atomicJsonWrite(ledgerPath(root), validateLedger(ledger), options);
+}
+
+function recoveryId(now       = new Date())         {
+  return `recovery_${now.toISOString().replace(/[:.]/g, '-').replace(/Z$/, 'Z')}_${crypto.randomBytes(4).toString('hex')}`;
+}
+
+function assertSafeRecoveryId(id     )       {
+  if (typeof id !== 'string' || !/^recovery_[A-Za-z0-9_-]+$/.test(id)) throw new Error(`Invalid recovery id: '${id}'`);
+}
+
+/** Persist a journal record before native mutation; append-only records make interrupted runs observable. */
+function writeRecoveryRecord(root        , record     , { now = new Date(), fsImpl = fs }                               = {})                                            {
+  const id = record?.id ?? recoveryId(now);
+  assertSafeRecoveryId(id);
+  const value      = {
+    id,
+    version: STATE_VERSION,
+    status: record?.status ?? 'pending',
+    createdAt: record?.createdAt ?? now.toISOString(),
+    ...record,
+  };
+  value.id = id; // re-asserted after the spread (a record carrying its own `id` key, even undefined, must not win)
+  if (!Array.isArray(value.changes)) value.changes = [];
+  return { id, file: atomicJsonWrite(path.join(recoveryRoot(root), `${id}.json`), value, { fsImpl }), record: value };
+}
+
+function readRecoveryRecord(root        , id     , { fsImpl = fs }                   = {})      {
+  assertSafeRecoveryId(id);
+  const file = path.join(recoveryRoot(root), `${id}.json`);
+  if (!fsImpl.existsSync(file)) return null;
+  try { return JSON.parse(fsImpl.readFileSync(file, 'utf8')); }
+  catch (error     ) { throw new Error(`Cannot read recovery record '${file}': ${error.message}`); }
+}
+
+function ownershipKey(record     )         {
+  return [record.harness, record.scope, record.assetId, record.target, record.ownershipIdentity].join('\u0000');
+}
+
+function importLegacyResource(resource     , scope     )      {
+  if (!resource || typeof resource !== 'object') return null;
+  if (typeof resource.target !== 'string' || typeof resource.kind !== 'string' || typeof resource.identity !== 'string') return null;
+  return {
+    harness: resource.target,
+    scope: resource.scope === 'project' || resource.scope === 'global' ? resource.scope : scope,
+    assetId: `legacy.${resource.kind}`,
+    target: resource.target,
+    ownershipIdentity: resource.identity,
+    sourceVersion: resource.sourceVersion ?? 'legacy',
+    fingerprint: resource.fingerprint ?? null,
+    projection: { legacyKind: resource.kind },
+    recoveryRef: resource.recoveryPoint ?? null,
+    selection: resource.selection ?? null,
+  };
+}
+
+/**
+ * Read-compatible, conservative legacy import.  Only explicit `managed_resources` records are
+ * converted to ownership claims; a legacy tool entry alone never authorizes adoption of files.
+ */
+function migrateLegacyManifest({ root, scope, scopeRoot, claudeDir, now = new Date(), fsImpl = fs }                                                                                              )      {
+  assertScope(scope);
+  const legacyFile = manifestPath(claudeDir);
+  const current = readLedger(root, { fsImpl }) ?? defaultLedger({ scope, scopeRoot });
+  if (current.scope !== scope || current.scopeRoot !== path.resolve(scopeRoot)) throw new Error('Neutral ledger scope does not match requested migration scope');
+  if (current.legacyImports.some((item     ) => item.path === legacyFile)) return { migrated: false, reason: 'already-imported', ledger: current, legacyFile };
+  if (!fsImpl.existsSync(legacyFile)) return { migrated: false, reason: 'legacy-missing', ledger: current, legacyFile };
+
+  const legacy = readManifest(claudeDir);
+  if (!legacy || legacy.operation === 'error') return { migrated: false, reason: 'legacy-invalid', ledger: current, legacyFile };
+  const resources = legacy.managedResources.map((resource     ) => importLegacyResource(resource, scope)).filter(Boolean);
+  const existing = new Set(current.resources.map(ownershipKey));
+  for (const resource of resources) if (!existing.has(ownershipKey(resource))) current.resources.push(resource);
+
+  // The legacy manifest's MCP selection was owned by Claude's config flow.  Do not infer an
+  // equivalent selection for Codex or Gemini merely because they happened to share the old file.
+  if (Array.isArray(legacy.mcpServers) && !Object.hasOwn(current.mcpSelections, 'claude')) current.mcpSelections.claude = [...legacy.mcpServers];
+  for (const [harness, status] of Object.entries(legacy.tools)                   ) {
+    if (status?.installed && !current.targets[harness]) current.targets[harness] = { installed: true, lastUpdated: status.last_updated ?? null, imported: true };
+  }
+  current.legacyImports.push({ path: legacyFile, importedAt: now.toISOString(), sourceFingerprint: fingerprint({ operation: legacy.operation, lastRun: legacy.lastRun, backupId: legacy.backupId, resources: legacy.managedResources }), lastBackupId: legacy.backupId });
+  writeLedger(root, current, { fsImpl });
+  return { migrated: true, reason: 'imported', ledger: current, legacyFile };
+}
+
+module.exports = {
+  STATE_VERSION, LEDGER_VERSION, LEDGER_FILE, RECOVERY_DIR,
+  stateRoot, ledgerPath, recoveryRoot, atomicJsonWrite,
+  defaultLedger, upgradeLedger, validateLedger, readLedger, writeLedger,
+  recoveryId, writeRecoveryRecord, readRecoveryRecord,
+  ownershipKey, importLegacyResource, migrateLegacyManifest,
+};

package/src/state/lockfile.js

@@ -0,0 +1,136 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+// doflow.lock — the resolved-projection lockfile. A ledger records what DoFlow OWNS;
+// a lock records what DoFlow CHOSE. It pins, per scope: targeted harnesses, selected assets with
+// their projection summaries, MCP selections, and the source version they were resolved from, so
+// that installs become reproducible and drift becomes a reviewable diff instead of a surprise.
+// Deliberately metadata-only: no file contents, no secrets — same posture as the neutral ledger.
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { atomicJsonWrite } = require('./index.js');
+
+const LOCK_VERSION = 1;
+const LOCK_FILE = 'doflow.lock';
+
+function lockRoot({ scope, projectRoot = '.', homeDir = os.homedir() }                                                        )         {
+  if (scope !== 'project' && scope !== 'global') throw new Error(`Invalid lock scope: '${scope}'`);
+  return scope === 'project' ? path.resolve(projectRoot) : path.resolve(homeDir);
+}
+
+function lockPath(options     )         { return path.join(lockRoot(options), '.doflow', LOCK_FILE); }
+
+function stable(value     )      {
+  if (Array.isArray(value)) return [...value].map(stable).sort((a     , b     ) => JSON.stringify(a) < JSON.stringify(b) ? -1 : 1);
+  if (!value || typeof value !== 'object') return value;
+  return Object.fromEntries(Object.keys(value).sort().map((key) => [key, stable(value[key])]));
+}
+
+function defaultLock({ scope, scopeRoot }                                   )      {
+  if (scope !== 'project' && scope !== 'global') throw new Error(`Invalid lock scope: '${scope}'`);
+  return {
+    version: LOCK_VERSION,
+    scope,
+    scopeRoot: path.resolve(scopeRoot),
+    generatedAt: null,
+    sourceVersion: null,
+    targets: [],
+    assets: [],
+    mcpSelections: {},
+  };
+}
+
+function validateLock(value     )      {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('Invalid doflow.lock: expected object');
+  if (value.version !== LOCK_VERSION) throw new Error(`Unsupported doflow.lock version: '${value.version}'`);
+  if (value.scope !== 'project' && value.scope !== 'global') throw new Error(`Invalid doflow.lock scope: '${value.scope}'`);
+  if (typeof value.scopeRoot !== 'string' || !path.isAbsolute(value.scopeRoot)) throw new Error('Invalid doflow.lock: scopeRoot must be absolute');
+  for (const field of ['targets', 'assets']) {
+    if (!Array.isArray(value[field])) throw new Error(`Invalid doflow.lock: ${field} must be an array`);
+  }
+  if (!value.mcpSelections || typeof value.mcpSelections !== 'object' || Array.isArray(value.mcpSelections)) {
+    throw new Error('Invalid doflow.lock: mcpSelections must be an object');
+  }
+  for (const [harness, ids] of Object.entries(value.mcpSelections)) {
+    if (!Array.isArray(ids) || !ids.every((id     ) => typeof id === 'string')) {
+      throw new Error(`Invalid doflow.lock: mcpSelections.${harness} must be an array of server ids`);
+    }
+  }
+  return value;
+}
+
+function readLock(options     , { fsImpl = fs }                   = {})      {
+  const file = lockPath(options);
+  if (!fsImpl.existsSync(file)) return null;
+  try { return validateLock(JSON.parse(fsImpl.readFileSync(file, 'utf8'))); }
+  catch (error     ) { throw new Error(`Cannot read doflow.lock '${file}': ${error.message}`); }
+}
+
+function writeLock(options     , lock     , { fsImpl = fs }                   = {})      {
+  // Validate the caller's document first so a foreign version fails loudly here rather than
+  // being silently normalized into something no future reader can distinguish.
+  validateLock(lock);
+  return atomicJsonWrite(lockPath(options), stable({ ...lock, version: LOCK_VERSION }), { fsImpl });
+}
+
+/** The lock's MCP rows for the harnesses it targets. A row naming a harness outside `targets` is
+ * ignored by every reader; the next write drops it. */
+function pinnedSelections(lock     )                      {
+  const targets = new Set((lock?.targets ?? []).map((entry     ) => entry.harness));
+  return Object.fromEntries(Object.entries(lock?.mcpSelections ?? {}).filter(([harness]) => targets.has(harness)));
+}
+
+/** Compare two lock documents. Arrays are keyed by identity (assets by id, targets by harness,
+ * fallback to full JSON), mcpSelections by harness, where an absent row (`null`) and a recorded
+ * empty selection (`[]`) differ. Returns {added, removed, changed} per section plus a clean flag. */
+function diffLocks(previousLock     , nextLock     )      {
+  // Compare in the order writeLock stores, so a document built in memory never differs from the
+  // file it was written to.
+  const previous = previousLock && stable(previousLock);
+  const next = nextLock && stable(nextLock);
+  const key = (entry     ) => entry?.id ?? entry?.harness ?? JSON.stringify(entry);
+  const sectionDiff = (before     , after     ) => {
+    const beforeKeys = new Map             ((before || []).map((entry     )                => [key(entry), entry]));
+    const afterKeys = new Map             ((after || []).map((entry     )                => [key(entry), entry]));
+    const added = [...afterKeys].filter(([k]) => !beforeKeys.has(k)).map(([, v]) => v);
+    const removed = [...beforeKeys].filter(([k]) => !afterKeys.has(k)).map(([, v]) => v);
+    const changed = [...afterKeys]
+      .filter(([k, v]) => beforeKeys.has(k) && JSON.stringify(beforeKeys.get(k)) !== JSON.stringify(v))
+      .map(([, v]) => v);
+    return { added, removed, changed };
+  };
+  const selectionsBefore = pinnedSelections(previous);
+  const selectionsAfter = pinnedSelections(next);
+  const harnesses = new Set([...Object.keys(selectionsBefore), ...Object.keys(selectionsAfter)]);
+  const mcpChanged = [...harnesses]
+    .filter((harness) => JSON.stringify(selectionsBefore[harness] ?? null) !== JSON.stringify(selectionsAfter[harness] ?? null))
+    .map((harness) => ({ harness, before: selectionsBefore[harness] ?? null, after: selectionsAfter[harness] ?? null }));
+  const result      = {
+    targets: sectionDiff(previous?.targets, next?.targets),
+    assets: sectionDiff(previous?.assets, next?.assets),
+    mcpSelections: { changed: mcpChanged },
+    meta: {
+      sourceVersion: (previous?.sourceVersion ?? null) !== (next?.sourceVersion ?? null)
+        ? { before: previous?.sourceVersion ?? null, after: next?.sourceVersion ?? null } : null,
+    },
+  };
+  result.clean = ['targets', 'assets'].every((name) => {
+    const section = result[name];
+    return section.added.length === 0 && section.removed.length === 0 && section.changed.length === 0;
+  }) && result.mcpSelections.changed.length === 0 && result.meta.sourceVersion === null;
+  return result;
+}
+
+/** Delete the lock when nothing remains pinned. Returns true when a file actually went away. */
+function removeLock(options     , { fsImpl = fs }                   = {})          {
+  const file = lockPath(options);
+  if (!fsImpl.existsSync(file)) return false;
+  fsImpl.rmSync(file);
+  return true;
+}
+
+module.exports = {
+  LOCK_VERSION, LOCK_FILE, lockRoot, lockPath, defaultLock, validateLock, readLock, writeLock, pinnedSelections, diffLocks, removeLock,
+};