@sabaiway/agent-workflow-kit 3.7.0 → 3.9.0

package/CHANGELOG.md

@@ -4,6 +4,66 @@ Semantically versioned ([semver](https://semver.org)), newest first. The `versio
 is the current release. `upgrade` mode reads a project's `docs/ai/.workflow-version` and applies
 every `migrations/<version>-<slug>.md` newer than it, in semver order.
 
+## 3.9.0 — the --include copy door proves what it copies (AD-070)
+
+Nothing bound the node the provision copy walk read to the node `--include` preflight approved:
+a source swapped after preflight was copied as approved, and the path-based queue guard could not
+see a node that had become the shared series index by identity (a hardlink, a swap) rather than
+by path. The gap is closed at the existing descriptor door:
+
+- **Preflight identity, captured before any git mutation.** The `--include` loop records each
+  root's {device, inode, kind} from the canonical node. A root that is neither a regular file
+  nor a directory — or an erroring identity probe — refuses BEFORE `git worktree add`: no
+  worktree is left behind.
+- **Three tiers at the walk.** A file root is verified at the door — the open descriptor must
+  match the preflight identity, and a node that is no longer a plain regular file stops before
+  any destination exists. A directory root gets a walk-start recheck (a recheck, not a binding).
+  Child files keep the existing same-call lstat↔open identity; the child walk stays path-based
+  (a stated residual).
+- **The door-time queue refusal, every copied include file.** With the source descriptor open,
+  the door opens the lexical queue path (following links, non-blocking — a FIFO-shaped queue
+  classifies non-regular and stops), fstats the open descriptor, and compares identities with
+  both descriptors open: never copy the node that IS the door-time queue. Queue identity is
+  established at descriptor-open time and never cached across crossings — absence is not cached
+  either. A truly absent queue keeps the lexical guard alone; a dangling, unreadable, or
+  non-regular queue is unprovable and stops the copy. The queue descriptor closes exactly once;
+  a close error surfaces without destination residue.
+- **The contract ships as an exported constant** (`INCLUDE_IDENTITY_RULE`), emitted on every
+  include-identity STOP and doc-parity-pinned into the worktrees mode doc.
+
+## 3.8.0 — cleanup never deletes a node_modules it cannot prove ephemeral (AD-069)
+
+Routine non-abandon `worktrees cleanup` used to delete an ignored user-built `node_modules`
+silently: `node_modules` sat unconditionally in the provision-owned root lists, so real user data
+was treated as removable provision footprint. The ownership call is now made LIVE, at cleanup
+time, from what deleting the node would destroy — never from who created it, and never from the
+handoff record:
+
+- **The gate** classifies the worktree's `node_modules` with one no-follow lstat and (for a
+  symlink) one buffer-form readlink: EPHEMERAL exactly when the raw target bytes equal MAIN's
+  `node_modules` path — a relative or re-encoded target that merely resolves to main stays
+  foreign, and the target's kind is irrelevant. Everything else — directory, file, special node —
+  is FOREIGN. The lane is tracked-first: a tracked path or tracked descendant wins over any
+  ignore rule, and an absent node with a live index entry is never clean-absent.
+- **The one exemption** is the ignored-lane matching symlink (exactly what provision creates):
+  the ignored inventory skips it and plain `git worktree remove` unlinks it — after the gate's
+  verdict is RE-PROVEN, same class same lane, immediately before the irreversible remove. Any
+  change in between, or any probe error at any point, is a fail-closed STOP with no remove call.
+- **Every other state stops surgically**, and the recovery matches the lane and kind: ignored/
+  untracked symlink, file, or special node → the exact single-node `rm`; directory → the
+  recursive form; then re-run cleanup (`--abandon` always named second). A TRACKED
+  `node_modules` never gets an `rm` — land its removal from MAIN instead. Probe errors offer no
+  removal command at all. A clean-absent verdict follows the legacy path unchanged, so landing a
+  tracked `node_modules` removal still converges. `--abandon` behavior is unchanged.
+- The contract sentence ships as the exported `CLEANUP_OWNERSHIP_RULE`, emitted on every
+  ownership STOP and pinned into `references/modes/worktrees.md` by a new doc-parity binding.
+
+Honest residuals, stated in the mode doc: the revalidation→remove window stays open (git performs
+the removal; no door there, deliberately); content that git cannot see — or that appears after
+the inventories inside a reset-restored tracked directory — remains a pre-existing generic
+worktree-removal residual, no longer masked by a false ownership claim; on Windows a strict-bytes
+mismatch degrades to the surgical STOP, never a deletion.
+
 ## 3.7.0 — the worktrees-dir advisor item can finally converge (AD-068)
 
 The `recommendations` advisor's `worktrees-dir` item used to fire forever: its only convergence

package/SKILL.md

@@ -3,7 +3,7 @@ name: agent-workflow-kit
 description: Deploy or upgrade a portable AI-agent memory-and-workflow system in any project. Use when the user wants to bootstrap `docs/ai/` + an entry-point `AGENTS.md` (+ `CLAUDE.md` alias) + cap/archive/index enforcement in a new or existing repo, set up the Memory Map and session protocols, install the docs-rotation pre-commit hook, or run `/agent-workflow-kit` / `/agent-workflow-kit upgrade`. Triggers on phrases like "set up the memory system", "deploy the AI workflow here", "bootstrap docs/ai", "upgrade the workflow".
 disable-model-invocation: true
 metadata:
-  version: '3.7.0'
+  version: '3.9.0'
 ---
 
 # agent-workflow-kit

package/capability.json

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "agent-workflow-kit",
   "kind": "composition-root",
-  "version": "3.7.0",
+  "version": "3.9.0",
   "provides": [],
   "roles": {},
   "detect": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "3.7.0",
+  "version": "3.9.0",
   "description": "Portable, cross-agent memory & workflow for AI coding agents — Claude Code, Codex, Cursor, Devin Desktop. One command deploys an AGENTS.md entry point + docs/ai context with cap/archive/index enforcement into any repo.",
   "keywords": [
     "ai-agents",

package/references/modes/worktrees.md

@@ -33,6 +33,25 @@ own verbatim error through the existing Git-error surface.
   is read from exactly one REQUIRED `## Provision record` section (a decoy field elsewhere cannot
   hijack identity); a missing or repeated section, or a duplicated single-valued field, is a typed
   STOP, never last-wins.
+  `--include` sources are identity-bound: preflight records each include root's identity (device,
+  inode, and kind of the canonical node) BEFORE `git worktree add`, and a root that is neither a
+  regular file nor a directory — or whose identity probe fails — is refused before any mutation.
+  An include that overlaps a path provision itself populates (the frozen registry footprint, the
+  seeded plan, the handoff) or another include root is refused pre-mutation too — an overlapped
+  destination would meet the copy-if-missing kept-exit and skip the identity door. On a FRESH
+  (non-resume) provision an include destination that already exists at walk time is a fail-closed
+  STOP (nothing legitimate pre-populates it — filesystem aliasing the overlap compare missed is
+  caught at the door). On `--resume`
+  an include destination already present from the prior run is KEPT (copy-if-missing by design):
+  the door proves what THIS run copies, never re-proves prior content.
+  An --include source is copied only through the identity door: a file include must still match the identity preflight recorded (device, inode, kind), a directory include root is re-checked at walk start, and every copied file is proven, with both descriptors open, not to be the node that IS the door-time queue — an absent queue keeps the lexical guard alone, and anything unprovable stops the copy.
+  The queue identity is read at descriptor-open time (following links, non-blocking — a
+  FIFO-shaped queue classifies non-regular and stops) and is never cached across door crossings;
+  a dangling, unreadable, or non-regular queue stops the copy. Honest residuals: the child
+  path-walk under a directory include stays path-based, the walk-start root recheck leaves a
+  recheck→walk window, and the identity/queue compares are point-in-time inode proofs, not
+  pathname bindings — a node recreated at the same device and inode within the window passes,
+  inherent to an inode proof — a self-discipline door, not a security boundary.
 - `list` — read-only: every worktree of this repo with slug (from the handoff file; none →
   "unknown (foreign)"), path, branch, base OID (the worktree HEAD — under the v1 no-commit bar
   that IS the provision base; a manual satellite commit moves it, and land derives its own base
@@ -54,8 +73,23 @@ own verbatim error through the existing Git-error surface.
 - `cleanup <slug> [--branch <name>] [--abandon]` — take the same transient lock and remove a LANDED
   worktree fail-closed after live landed-verification against main HEAD. Verification uses exactly
   the land exclusions (`docs/ai`, `docs/plans`), then checks untracked and ignored content before a
-  plain worktree remove, branch `-d`, and prune. Provision-derived ignored containers are ephemeral;
-  `node_modules` of any kind is provision-derivable because provision explicitly advises installs.
+  plain worktree remove, branch `-d`, and prune. Provision-derived ignored containers are ephemeral —
+  except `node_modules`, which is never assumed provision-owned:
+  node_modules ownership is decided live: only a symlink whose raw target bytes equal MAIN's node_modules path, in the ignored lane, is provision-ephemeral; an absent node with no index entry is clean; every other state stops cleanup to protect user data or because inspection failed.
+  The verdict is
+  computed once, after landed verification and before the untracked/ignored inventories (it also
+  catches tracked `node_modules` and empty untracked directories git never lists); the lane is
+  tracked-first (a tracked path or tracked descendant wins over any ignore rule; an absent node with
+  a live index entry is never clean-absent); the single exempt state is re-proven — same class, same
+  lane — immediately before `git worktree remove`, and any deviation or probe error is a fail-closed
+  STOP with no removal performed. STOP recovery is surgical and lane-specific: untracked/ignored
+  symlink, file, or special node → a single-node `rm`; directory → the recursive form; then re-run
+  cleanup — `--abandon` is always named second; a tracked `node_modules` never gets an `rm` (land the
+  removal from MAIN instead); a probe error gets no removal command at all. A clean-absent verdict
+  follows the legacy cleanup path and carries no post-reset ownership proof: git-invisible or ignored
+  content appearing after the inventories, or surviving inside a reset-restored tracked directory,
+  remains a pre-existing generic worktree-removal residual (not `node_modules`-specific). On Windows
+  a strict-bytes mismatch degrades to the surgical STOP — fail-closed friction, never deletion.
   Foreign content stops cleanup. `--abandon` is the ONE destructive arm: it DESTROYS unlanded work,
   requires the handoff identity, and is the only path where `--force` may appear.
 

package/tools/doc-parity.mjs

@@ -34,7 +34,7 @@ import {
 } from './recommendations.mjs';
 import { SKIPPED_READONLY } from './setup-backends.mjs';
 import { LATENT_ARM_NOTICE } from './review-state.mjs';
-import { QUEUE_SHARED_RULE, LANDING_FROM_MAIN, NO_DEPENDENCIES_POSTURE } from './worktrees.mjs';
+import { QUEUE_SHARED_RULE, LANDING_FROM_MAIN, NO_DEPENDENCIES_POSTURE, CLEANUP_OWNERSHIP_RULE, INCLUDE_IDENTITY_RULE } from './worktrees.mjs';
 
 const KIT_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -105,6 +105,13 @@ export const BINDINGS = Object.freeze([
   valueBinding('queue-shared-rule', QUEUE_SHARED_RULE, QUEUE_SHARED_RULE, [WORKTREES_DOC]),
   valueBinding('landing-from-main', LANDING_FROM_MAIN, LANDING_FROM_MAIN, [WORKTREES_DOC]),
   valueBinding('no-dependencies-posture', NO_DEPENDENCIES_POSTURE, NO_DEPENDENCIES_POSTURE, [WORKTREES_DOC]),
+  // The cleanup-ownership contract (AD-069): the exact live sentence every ownership STOP emits —
+  // a reworded mode doc dropping the class × lane contract fails this pin plus the gate.
+  valueBinding('cleanup-ownership-rule', CLEANUP_OWNERSHIP_RULE, CLEANUP_OWNERSHIP_RULE, [WORKTREES_DOC]),
+  // The include-identity contract (F3): the exact live sentence every include-identity STOP emits —
+  // a reworded mode doc dropping the preflight-binding × door-time-queue contract fails this pin
+  // plus the gate.
+  valueBinding('include-identity-rule', INCLUDE_IDENTITY_RULE, INCLUDE_IDENTITY_RULE, [WORKTREES_DOC]),
 ].map((b) => Object.freeze(b)));
 
 // ── the pure checker (readText is injectable for hermetic tests) ────────────────────────
@@ -151,8 +158,9 @@ Usage:
 A CLOSED, exported registry binds each live code constant — the autonomy-doctor contract (the EXIT
 table, the status tokens, the trusted-dir allowlist), the recommendations/upgrade presentation
 contract (section header, empty line, verdict templates), the acks-store path, the setup refresh
-degrade token, the review-state clean-tree latent-arm notice, and the worktrees provision-record
-orientation contract (shared-queue rule, landing-from-main, no-dependencies install posture) — to
+degrade token, the review-state clean-tree latent-arm notice, the worktrees provision-record
+orientation contract (shared-queue rule, landing-from-main, no-dependencies install posture), the
+worktrees cleanup-ownership rule, and the worktrees include-identity rule — to
 the exact token its references/modes/*.md contract must carry, and
 asserts the CURRENT value renders into every bound file. A drifted doc, an unreadable bound file,
 or an absent token FAILS CLOSED.

package/tools/worktrees.mjs

@@ -200,23 +200,126 @@ const readFileNoFollow = (fs, abs) => {
 
 const NOFOLLOW_WRITE = fsC.O_WRONLY | fsC.O_CREAT | fsC.O_EXCL | (fsC.O_NOFOLLOW ?? 0);
 const COPY_BUFFER_BYTES = 64 * 1024;
-const copyFileNoFollow = ({ srcAbs, dstAbs, sourceStat, rel, fs }) => {
+
+// The include-identity door (F3). `door` rides ONLY the --include copy lane: { queuePath } on
+// every crossing, plus { identity } for a FILE include root (a directory root is re-checked at
+// walk start instead; its children keep the same-call lstat↔open identity — path-based walk is
+// a stated residual). Every STOP here emits INCLUDE_IDENTITY_RULE.
+const includeIdentityStop = (rel, cause) => stop(`--include: ${cause}: ${rel}\n${INCLUDE_IDENTITY_RULE}`);
+
+// The fresh-preexist STOPs carry their own surgical recovery so the generic worktree-kept NOTE
+// never steers the operator into a blind --resume over the very node the door refused.
+const INCLUDE_PREEXIST_CAUSE = 'the include destination already exists at walk time — inspect the unexpected destination and remove it (single node: rm; directory: rm -rf), then finish with --resume';
+
+// Equal / ancestor / descendant, canonized PER PLATFORM: on a backslash-separator platform
+// `relative()` returns backslashes and path comparison is case-insensitive, so separators
+// normalize and case folds (fail-closed for a refusal guard — more refusals, never fewer); on
+// POSIX the compare stays LITERAL — a backslash is a valid filename character and case is
+// significant, so normalizing would conflate distinct names into false refusals. The separator
+// is injectable so both platforms' semantics are test-pinned from one host.
+export const includeRelsOverlap = (a, b, { separator = sep } = {}) => {
+  const canon = (p) => (separator === '\\' ? normalizeSlashes(p).toLowerCase() : p);
+  const left = canon(a);
+  const right = canon(b);
+  return left === right || left.startsWith(`${right}/`) || right.startsWith(`${left}/`);
+};
+
+// Follows links deliberately (the door must land on the THEN-CURRENT canonical queue node);
+// O_NONBLOCK keeps a FIFO-shaped queue from blocking the door — its fstat classifies it.
+const QUEUE_DOOR_READ = fsC.O_RDONLY | (fsC.O_NONBLOCK ?? 0);
+
+// Runs while the SOURCE descriptor is open: open the LEXICAL queue path, fstat the OPEN
+// descriptor, compare identities with both descriptors open. lstat-ENOENT (truly absent) keeps
+// the lexical guard alone; a dangling link, unreadable, non-regular, or erroring queue is
+// unprovable → fail-closed STOP. Queue identity is never cached across crossings.
+const assertSourceIsNotDoorTimeQueue = ({ sourceStat, queuePath, rel, fs }) => {
+  // Absence is proven at the OPEN, never at the lstat alone — a queue born between the two
+  // still meets the descriptor compare. lstat's job is to tell truly-absent (both ENOENT)
+  // from a dangling link (lstat succeeds, open ENOENT), which stays a fail-closed STOP.
+  const lstatAbsent = (() => {
+    try {
+      fs.lstat(queuePath);
+      return false;
+    } catch (err) {
+      if (err?.code === 'ENOENT') return true;
+      throw includeIdentityStop(rel, `cannot probe the shared series index (${err?.code ?? 'fs error'})`);
+    }
+  })();
+  const handle = { fd: null };
+  const outcome = { error: null };
+  try {
+    try {
+      handle.fd = fs.open(queuePath, QUEUE_DOOR_READ);
+    } catch (err) {
+      if (err?.code === 'ENOENT' && lstatAbsent) return;
+      if (err?.code === 'ENOENT') throw includeIdentityStop(rel, 'the shared series index is a dangling link at copy time');
+      throw includeIdentityStop(rel, `cannot open the shared series index (${err?.code ?? 'fs error'})`);
+    }
+    const queueStat = (() => {
+      try {
+        return fs.fstat(handle.fd);
+      } catch (err) {
+        throw includeIdentityStop(rel, `cannot inspect the shared series index (${err?.code ?? 'fs error'})`);
+      }
+    })();
+    if (!queueStat.isFile()) throw includeIdentityStop(rel, 'the shared series index is not a regular file at copy time');
+    if (queueStat.dev === sourceStat.dev && queueStat.ino === sourceStat.ino) {
+      throw includeIdentityStop(rel, 'the source IS the door-time queue');
+    }
+  } catch (error) {
+    outcome.error = error;
+  }
+  if (handle.fd !== null) {
+    try {
+      fs.close(handle.fd);
+    } catch (closeError) {
+      if (!outcome.error) {
+        outcome.error = includeIdentityStop(rel, `cannot close the shared series index descriptor (${closeError?.code ?? 'fs error'})`);
+      } else {
+        outcome.error.message += ` (additionally: the shared series index descriptor failed to close: ${closeError?.code ?? 'fs error'})`;
+      }
+    }
+  }
+  if (outcome.error) throw outcome.error;
+};
+
+const copyFileNoFollow = ({ srcAbs, dstAbs, sourceStat, rel, fs, door = null, wtRoot }) => {
   const handles = { source: null, destination: null };
   const closeErrors = [];
   const outcome = { error: null };
   try {
+    const sourceWindowStop = () => (door
+      ? includeIdentityStop(rel, 'the source changed between lstat and open')
+      : stop(`copy source changed between lstat and open: ${rel}`));
     try {
       handles.source = fs.open(srcAbs, NOFOLLOW_READ);
     } catch (error) {
       if (error?.code === 'ENOENT' || error?.code === 'ELOOP') {
-        throw stop(`copy source changed between lstat and open: ${rel}`);
+        throw sourceWindowStop();
       }
+      if (door) throw includeIdentityStop(rel, `cannot prove the source identity (${error?.code ?? 'fs error'})`);
       throw error;
     }
-    const descriptorStat = fs.fstat(handles.source);
+    const descriptorStat = (() => {
+      try {
+        return fs.fstat(handles.source);
+      } catch (error) {
+        if (door) throw includeIdentityStop(rel, `cannot prove the source identity (${error?.code ?? 'fs error'})`);
+        throw error;
+      }
+    })();
     if (!descriptorStat.isFile() || descriptorStat.dev !== sourceStat.dev || descriptorStat.ino !== sourceStat.ino) {
-      throw stop(`copy source changed between lstat and open: ${rel}`);
+      throw sourceWindowStop();
     }
+    if (door?.identity && (descriptorStat.dev !== door.identity.dev || descriptorStat.ino !== door.identity.ino)) {
+      throw includeIdentityStop(rel, 'the source is not the node preflight approved');
+    }
+    if (door) assertSourceIsNotDoorTimeQueue({ sourceStat: descriptorStat, queuePath: door.queuePath, rel, fs });
+    // Destination preparation runs only AFTER every source-side proof — a refusal must leave no
+    // fresh parent-directory residue, in either lane.
+    guardDst(fs, wtRoot, dirname(dstAbs));
+    fs.mkdir(dirname(dstAbs));
+    guardDst(fs, wtRoot, dstAbs);
     try {
       // O_EXCL closes the create race; O_NOFOLLOW is defense-in-depth for nonstandard link handling.
       handles.destination = fs.open(dstAbs, NOFOLLOW_WRITE, sourceStat.mode & 0o666);
@@ -246,14 +349,32 @@ const copyFileNoFollow = ({ srcAbs, dstAbs, sourceStat, rel, fs }) => {
     try {
       fs.close(handles[key]);
     } catch (error) {
-      closeErrors.push(error);
+      closeErrors.push({ key, error });
     }
   }
   const withDestinationState = (error) => Object.assign(error, {
     copyDoorDestinationCreated: handles.destination !== null,
   });
-  if (outcome.error) throw withDestinationState(outcome.error);
-  if (closeErrors.length > 0) throw withDestinationState(closeErrors[0]);
+  // Every close failure surfaces with its OWN descriptor name, in close order — a latched
+  // primary error carries them all appended; without one, the first failure leads and the rest
+  // still ride along. The suffix ALSO travels as a field because the copy walk re-wraps
+  // non-STOP primaries into its own message (which would otherwise drop the close names).
+  const closeSuffix = (failures) => failures
+    .map(({ key, error }) => ` (additionally: the ${key} descriptor failed to close: ${error?.code ?? 'fs error'})`)
+    .join('');
+  if (outcome.error) {
+    const suffix = closeSuffix(closeErrors);
+    outcome.error.message += suffix;
+    if (suffix) outcome.error.closeFailureSuffix = suffix;
+    throw withDestinationState(outcome.error);
+  }
+  if (closeErrors.length > 0) {
+    const [first, ...rest] = closeErrors;
+    const suffix = ` (the ${first.key} descriptor failed to close)${closeSuffix(rest)}`;
+    first.error.message = `${first.error.message ?? ''}${suffix}`;
+    first.error.closeFailureSuffix = suffix;
+    throw withDestinationState(first.error);
+  }
 };
 
 const isInside = (root, path) => {
@@ -664,7 +785,7 @@ const failAfterCopy = ({ cause, dstAbs, wtRoot, fs }) => {
   throw stop(`${primary} — partial destination removed; re-run provision`);
 };
 
-const copyNode = ({ srcAbs, dstAbs, wtRoot, rel, fs, report, copied }) => {
+const copyNode = ({ srcAbs, dstAbs, wtRoot, rel, fs, report, copied, door = null }) => {
   if (EXCLUDED_BASENAMES.has(basename(srcAbs))) {
     report.push(`  skip (session sidecar): ${rel}`);
     return;
@@ -673,11 +794,21 @@ const copyNode = ({ srcAbs, dstAbs, wtRoot, rel, fs, report, copied }) => {
   try {
     st = fs.lstat(srcAbs);
   } catch (err) {
+    if (door) throw includeIdentityStop(rel, `cannot prove the source identity (${err?.code ?? 'fs error'})`);
     throw stop(`copy failed (${err?.code ?? 'fs error'}) reading ${rel}`);
   }
+  // A preflight-approved FILE include routes ONLY to the regular-file door — a node that is no
+  // longer a plain regular file (kind is part of the preflight identity) stops before any branch
+  // could create a destination.
+  if (door?.identity && (st.isSymbolicLink() || !st.isFile())) {
+    throw includeIdentityStop(rel, 'the source is not the node preflight approved');
+  }
   try {
     if (st.isSymbolicLink()) {
       if (lstatNoFollow(fs.lstat, dstAbs) !== null) {
+        // Fresh-provision include lane: an existing destination is aliasing the overlap
+        // comparator missed (nothing legitimate pre-populates it) — fail closed, never "kept".
+        if (door?.fresh) throw includeIdentityStop(rel, INCLUDE_PREEXIST_CAUSE);
         report.push(`  kept (already present): ${rel}`);
         return;
       }
@@ -716,22 +847,25 @@ const copyNode = ({ srcAbs, dstAbs, wtRoot, rel, fs, report, copied }) => {
       if (lstatNoFollow(fs.lstat, dstAbs) === null) {
         guardDst(fs, wtRoot, dstAbs);
         fs.mkdir(dstAbs);
+      } else if (door?.fresh) {
+        // Mirrors the file/symlink kept-exit STOPs: on a fresh provision no include destination
+        // node may pre-exist — an existing nested directory is aliasing or foreign content that
+        // must never fall under the include's ownership.
+        throw includeIdentityStop(rel, INCLUDE_PREEXIST_CAUSE);
       }
       for (const entry of fs.readdir(srcAbs)) {
-        copyNode({ srcAbs: join(srcAbs, entry), dstAbs: join(dstAbs, entry), wtRoot, rel: `${rel}/${entry}`, fs, report, copied });
+        copyNode({ srcAbs: join(srcAbs, entry), dstAbs: join(dstAbs, entry), wtRoot, rel: `${rel}/${entry}`, fs, report, copied, door });
       }
     } else if (st.isFile()) {
       if (lstatNoFollow(fs.lstat, dstAbs) !== null) {
+        if (door?.fresh) throw includeIdentityStop(rel, INCLUDE_PREEXIST_CAUSE);
         report.push(`  kept (already present): ${rel}`);
         return;
       }
-      guardDst(fs, wtRoot, dirname(dstAbs));
-      fs.mkdir(dirname(dstAbs));
-      guardDst(fs, wtRoot, dstAbs);
       try {
-        copyFileNoFollow({ srcAbs, dstAbs, sourceStat: st, rel, fs });
+        copyFileNoFollow({ srcAbs, dstAbs, sourceStat: st, rel, fs, door, wtRoot });
       } catch (err) {
-        const cause = err?.code === WORKTREES_STOP ? err : stop(`copy failed (${err?.code ?? 'fs error'}) at ${rel}`);
+        const cause = err?.code === WORKTREES_STOP ? err : stop(`copy failed (${err?.code ?? 'fs error'}) at ${rel}${err?.closeFailureSuffix ?? ''}`);
         if (err?.copyDoorDestinationCreated !== true) throw cause;
         failAfterCopy({ cause, dstAbs, wtRoot, fs });
       }
@@ -937,6 +1071,11 @@ export const NO_DEPENDENCIES_POSTURE = 'no install needed — the project declar
 // The recorded node_modules mode for that same verdict: provision neither advised nor created a
 // node_modules for this worktree.
 export const NODE_MODULES_NONE = 'no-dependencies';
+// The cleanup-ownership contract (AD-069): ownership is information content, decided live at
+// cleanup time — never provenance, never the handoff record. Doc-parity pins this exact sentence
+// into the worktrees mode doc; every ownership STOP emits it.
+export const CLEANUP_OWNERSHIP_RULE = "node_modules ownership is decided live: only a symlink whose raw target bytes equal MAIN's node_modules path, in the ignored lane, is provision-ephemeral; an absent node with no index entry is clean; every other state stops cleanup to protect user data or because inspection failed";
+export const INCLUDE_IDENTITY_RULE = 'An --include source is copied only through the identity door: a file include must still match the identity preflight recorded (device, inode, kind), a directory include root is re-checked at walk start, and every copied file is proven, with both descriptors open, not to be the node that IS the door-time queue — an absent queue keeps the lexical guard alone, and anything unprovable stops the copy';
 
 // The record is LINE-oriented and is parsed back for IDENTITY, so a value carrying a control byte
 // is refused rather than written: a newline spills a second line the parser reads as a real field
@@ -1074,19 +1213,22 @@ const assertIncludeRoundTrips = (rel) => {
 // to smuggle) falls back to the lexical compare alone; any other realpath failure (EACCES/EIO)
 // means the canonical identity cannot be established, and a silent fallback would quietly disable
 // the guard it exists to enforce.
-const assertIncludeNeverCopiesTheQueue = ({ rootReal, incReal, inc, fs }) => {
+const assertIncludeNeverCopiesTheQueue = ({ rootReal, incReal, inc, fs, contract = false }) => {
+  // `contract` marks the WALK-TIME (point-of-use) call: its failures are include-identity
+  // refusals and carry the door contract; the pre-mutation preflight call keeps the plain form.
+  const withContract = (message) => stop(contract ? `${message}\n${INCLUDE_IDENTITY_RULE}` : message);
   const queueLexical = join(rootReal, PLANS_REL, QUEUE_BASENAME);
   const queuePaths = [queueLexical];
   try {
     queuePaths.push(fs.realpath(queueLexical));
   } catch (err) {
     if (err?.code !== 'ENOENT') {
-      throw stop(`--include: cannot resolve the shared series index path (${err?.code ?? 'error'}), so the queue-copy guard cannot establish its canonical identity: ${PLANS_REL}/${QUEUE_BASENAME} — fix the path (or drop the --include) and re-run`);
+      throw withContract(`--include: cannot resolve the shared series index path (${err?.code ?? 'error'}), so the queue-copy guard cannot establish its canonical identity: ${PLANS_REL}/${QUEUE_BASENAME} — fix the path (or drop the --include) and re-run`);
     }
   }
   for (const queuePath of queuePaths) {
     if (incReal === queuePath || isInside(incReal, queuePath)) {
-      throw stop(`--include would copy the SHARED series index (${PLANS_REL}/${QUEUE_BASENAME}) into the worktree: ${inc}. The index lives only in main and is read there — a local copy silently diverges.`);
+      throw withContract(`--include would copy the SHARED series index (${PLANS_REL}/${QUEUE_BASENAME}) into the worktree: ${inc}. The index lives only in main and is read there — a local copy silently diverges.`);
     }
   }
 };
@@ -1178,20 +1320,45 @@ const writeSeedPlan = ({ wtRoot, srcAbs, name, fs, report }) => {
 // It is copied from that already-canonical `real`, NEVER re-resolved from the raw path: a fresh
 // realpath here (after the worktree exists) would re-open a TOCTOU where a swapped symlink could
 // redirect an include at the shared series index between the check and the copy.
-const provisionIncludes = ({ rootReal, wtRoot, includeSources, git, fs, report, copied }) => {
+const provisionIncludes = ({ rootReal, wtRoot, includeSources, resume, git, fs, report, copied }) => {
   const recorded = [];
-  for (const { rel, real } of includeSources) {
+  const queuePath = join(rootReal, PLANS_REL, QUEUE_BASENAME);
+  for (const { rel, real, identity } of includeSources) {
     // Defence in depth: re-assert the queue-copy prohibition on the canonical path at the POINT OF
     // USE, so it holds where the copy happens and not only where the path was first checked.
-    assertIncludeNeverCopiesTheQueue({ rootReal, incReal: real, inc: rel, fs });
-    const probeRel = fs.lstat(real).isDirectory() ? `${rel}/` : rel;
+    assertIncludeNeverCopiesTheQueue({ rootReal, incReal: real, inc: rel, fs, contract: true });
+    if (identity.kind === 'directory') {
+      // The walk-start ROOT recheck (a recheck, not a binding — the child walk stays path-based;
+      // a FILE root instead verifies its descriptor against the preflight identity at the door).
+      const live = (() => {
+        try {
+          return fs.lstat(real);
+        } catch (err) {
+          throw includeIdentityStop(rel, `cannot re-probe the include root (${err?.code ?? 'fs error'})`);
+        }
+      })();
+      if (!live.isDirectory() || live.dev !== identity.dev || live.ino !== identity.ino) {
+        throw includeIdentityStop(rel, 'the include root is not the node preflight approved');
+      }
+    }
+    const probeRel = identity.kind === 'directory' ? `${rel}/` : rel;
     if (!checkIgnored(git, probeRel, wtRoot)) {
       throw stop(
         `--include destination is not ignored in the worktree: ${rel} — it would become a land-preflight leftover. ` +
           'Recovery: ignore the path (shared exclude / .gitignore) or drop the --include.',
       );
     }
-    copyNode({ srcAbs: real, dstAbs: join(wtRoot, rel), wtRoot, rel, fs, report, copied });
+    // On a FRESH provision nothing may legitimately pre-populate an IGNORED include destination
+    // (overlaps refuse pre-mutation; a tracked rel was just refused above), so an existing
+    // destination root is filesystem aliasing the comparator missed — fail closed at the door.
+    // `--resume` keeps the copy-if-missing kept-exit (the stated prior-run residual).
+    if (!resume && lstatNoFollow(fs.lstat, join(wtRoot, rel)) !== null) {
+      throw includeIdentityStop(rel, INCLUDE_PREEXIST_CAUSE);
+    }
+    const door = identity.kind === 'file'
+      ? { identity, queuePath, fresh: !resume }
+      : { queuePath, fresh: !resume };
+    copyNode({ srcAbs: real, dstAbs: join(wtRoot, rel), wtRoot, rel, fs, report, copied, door });
     recorded.push(rel);
   }
   return recorded;
@@ -1567,6 +1734,16 @@ export const runProvision = ({ argvSlug, flags, cwd, git, deps, log }) => {
   const seed = validateSeedPlan({ root, rootReal, planFlag: flags.plan, asFlag: flags.as ?? null, fs });
 
   const sources = assertProvisionSourcesContained({ root, rootReal, fs, statFollow: deps.stat ?? statSync });
+  // FROZEN before any git mutation and used for BOTH the overlap refusal below and the copy loop
+  // in finishProvision — a re-computed set could admit a registry path that appeared after
+  // preflight inside an include root and copy it through the doorless copy-if-missing lane.
+  const provisionSet = provisionCopySet(root, deps);
+  const provisionSetRels = provisionSet.map((pattern) => patternToProbe(pattern).replace(/\/$/, ''));
+  const reservedRels = [
+    ...provisionSetRels,
+    `${PLANS_REL}/${seed.name}`,
+    `${PLANS_REL}/${handoffBasename(slug)}`,
+  ];
   const includeSources = [];
   for (const inc of flags.include) {
     const incAbs = resolve(root, inc);
@@ -1580,7 +1757,30 @@ export const runProvision = ({ argvSlug, flags, cwd, git, deps, log }) => {
     assertIncludeNeverCopiesTheQueue({ rootReal, incReal, inc, fs });
     const rel = relative(rootReal, incReal);
     assertIncludeRoundTrips(rel);
-    includeSources.push({ rel, real: incReal });
+    // Preflight identity (F3): {dev, ino, kind} of the canonical node, captured BEFORE any git
+    // mutation. A root that is neither a regular file nor a directory, or an erroring probe,
+    // refuses pre-mutation (a plain usage STOP — the door contract applies to the copy walk).
+    const incNode = (() => {
+      try {
+        return fs.lstat(incReal);
+      } catch (err) {
+        throw stop(`--include: cannot establish the identity of ${inc} (${err?.code ?? 'fs error'}) — fix the path (or drop the --include) and re-run`);
+      }
+    })();
+    const kind = incNode.isDirectory() ? 'directory' : incNode.isFile() ? 'file' : null;
+    if (kind === null) throw stop(`--include must be a regular file or a directory: ${inc}`);
+    // Overlap refusal (pre-mutation): an include rel that another provision lane also populates
+    // (the frozen registry footprint, the seeded plan, the handoff) — or another include root —
+    // would meet the copy-if-missing kept-exit and skip the identity door entirely.
+    const reserved = reservedRels.find((r) => includeRelsOverlap(rel, r));
+    if (reserved !== undefined) {
+      throw stop(`--include overlaps a path provision itself populates (${reserved}): ${inc} — the footprint, the seeded plan, and the handoff are copied by provision; drop the --include`);
+    }
+    const clashing = includeSources.find((prior) => includeRelsOverlap(rel, prior.rel));
+    if (clashing !== undefined) {
+      throw stop(`--include roots overlap: ${clashing.rel} and ${rel} — name each copied path once`);
+    }
+    includeSources.push({ rel, real: incReal, identity: { dev: incNode.dev, ino: incNode.ino, kind } });
   }
   assertTargetOutsideSources({ targetReal, sources: [...sources, ...includeSources] });
   // The TARGET path reaches the record too — the `install` field embeds the worktree dir — and it
@@ -1627,7 +1827,7 @@ export const runProvision = ({ argvSlug, flags, cwd, git, deps, log }) => {
   // any failure past this point leaves a real created worktree — the error must say so and
   // hand back the exact finish command, never just the local cause
   try {
-    return finishProvision({ root, rootReal, targetPath: targetReal, slug, branch, flags, seed, includeSources, git, deps, fs, report, log });
+    return finishProvision({ root, rootReal, targetPath: targetReal, slug, branch, flags, seed, includeSources, provisionSet, git, deps, fs, report, log });
   } catch (err) {
     if (!flags.resume && err?.message) {
       err.message += `\nNOTE: the worktree at ${targetReal} (branch ${branch}) was created and KEPT — finish with: ${composeProvisionArgv({ root, slug, flags: { ...flags, resume: true } })} (or reclaim it with the consented cleanup).`;
@@ -1636,18 +1836,18 @@ export const runProvision = ({ argvSlug, flags, cwd, git, deps, log }) => {
   }
 };
 
-const finishProvision = ({ root, rootReal, targetPath, slug, branch, flags, seed, includeSources, git, deps, fs, report, log }) => {
+const finishProvision = ({ root, rootReal, targetPath, slug, branch, flags, seed, includeSources, provisionSet, git, deps, fs, report, log }) => {
   writeHandoffStubIfAbsent({ root, wtRoot: targetPath, slug, branch, fs, report });
 
   const copied = new Set();
   report.push('copying the provision set (copy-if-missing; tracked files come from the checkout):');
-  for (const pattern of provisionCopySet(root, deps)) {
+  for (const pattern of provisionSet) {
     const rel = patternToProbe(pattern).replace(/\/$/, '');
     copyNode({ srcAbs: join(root, rel), dstAbs: join(targetPath, rel), wtRoot: targetPath, rel, fs, report, copied });
   }
 
   writeSeedPlan({ wtRoot: targetPath, srcAbs: seed.srcAbs, name: seed.name, fs, report });
-  const includesRecorded = provisionIncludes({ rootReal, wtRoot: targetPath, includeSources, git, fs, report, copied });
+  const includesRecorded = provisionIncludes({ rootReal, wtRoot: targetPath, includeSources, resume: flags.resume, git, fs, report, copied });
   // Computed ONCE, from the satellite's own checkout, and threaded to both consumers — the report
   // lane and the record must state the SAME verdict.
   const dependencyFree = declaresNoDependencies({ wtRoot: targetPath, fs });
@@ -2266,7 +2466,6 @@ const provisionKnownRoots = (identity) => {
     ...registryRoots(),
     ...identity.record.includes.map(safeRecordedPath),
     PLANS_REL,
-    'node_modules',
   ];
   if (identity.record.vscode === 'written') roots.push('.vscode/settings.json');
   return [...new Set(roots)];
@@ -2277,7 +2476,6 @@ const provisionKnownDirectoryRoots = ({ root, identity, fs }) => {
     ...KIT_OWN_PATHS.filter(isDirPattern),
     ...KNOWN_FOOTPRINT.filter((entry) => entry.type === 'dir').map((entry) => entry.pattern),
     PLANS_REL,
-    'node_modules',
   ].map((path) => normalizeSlashes(path).replace(/^\//, '').replace(/\/$/, ''));
   for (const include of identity.record.includes.map(safeRecordedPath)) {
     const kind = classifyNodeNoFollow(join(root, include), fs).kind;
@@ -2294,7 +2492,7 @@ const rootCoveringPath = (path, roots) => roots.find((root) => {
   return path === root || path.startsWith(`${root}/`);
 }) ?? null;
 
-const foreignIgnoredPaths = ({ root, git, identity, fs }) => {
+const foreignIgnoredPaths = ({ root, git, identity, fs, exemptNodeModules = false }) => {
   const result = gitRead(
     git, ['status', '--porcelain=v1', '-z', '--ignored', '--untracked-files=all'], root,
     'git status --ignored failed',
@@ -2305,6 +2503,9 @@ const foreignIgnoredPaths = ({ root, git, identity, fs }) => {
     for (const rawPath of entry.paths) {
       const normalized = normalizeSlashes(rawPath);
       const path = normalized.replace(/\/$/, '');
+      // The ONE ownership exemption (AD-069): the gate has already proven this exact node an
+      // ignored-lane matching symlink; it is neither re-probed nor reported here.
+      if (exemptNodeModules && path === NODE_MODULES_REL) continue;
       const kind = classifyNodeNoFollow(join(root, path), fs).kind;
       const rootType = kind === 'plain-directory' || kind === 'symlink-to-directory'
         ? 'directory'
@@ -2327,6 +2528,88 @@ const foreignIgnoredPaths = ({ root, git, identity, fs }) => {
   }).map(([path]) => path);
 };
 
+// ── the node_modules ownership gate (AD-069) ──────────────────────────────────────────────
+// Class {absent, ephemeral, foreign} × lane {tracked, ignored, untracked}, decided live from
+// exactly one no-follow lstat + (symlink only) one buffer-form readlink + the git lane probes.
+// The record is never consulted; every probe error is FOREIGN fail-closed with no recovery
+// command. The single exempt state — the ignored-lane matching link — is re-proven immediately
+// before the irreversible worktree remove.
+
+const NODE_MODULES_REL = 'node_modules';
+
+const nodeModulesInspectStop = (nmPath, detail) => stop(
+  `cleanup stopped: cannot inspect ${nmPath} (${detail})\n${CLEANUP_OWNERSHIP_RULE}`,
+);
+
+const nodeModulesSnapshot = ({ wtRoot, mainRoot, git, fs }) => {
+  const nmPath = join(wtRoot, NODE_MODULES_REL);
+  const node = (() => {
+    try {
+      return { stat: fs.lstat(nmPath) };
+    } catch (error) {
+      return error?.code === 'ENOENT' ? { stat: null } : { error: error?.code ?? 'fs error' };
+    }
+  })();
+  if (node.error) throw nodeModulesInspectStop(nmPath, node.error);
+  const trackedProbe = git(['ls-files', '--cached', '-z', '--', NODE_MODULES_REL], wtRoot);
+  if (trackedProbe.status !== 0) {
+    throw nodeModulesInspectStop(nmPath, `git ls-files failed: ${(trackedProbe.stderr || trackedProbe.stdout).trim()}`);
+  }
+  const tracked = trackedProbe.stdout.length > 0;
+  if (node.stat === null) {
+    return { klass: 'absent', kind: 'absent', lane: tracked ? 'tracked' : null, nmPath };
+  }
+  const lane = tracked ? 'tracked' : (() => {
+    const probe = git(['check-ignore', '--', NODE_MODULES_REL], wtRoot);
+    if (probe.status === 0) return 'ignored';
+    if (probe.status === 1) return 'untracked';
+    throw nodeModulesInspectStop(nmPath, `git check-ignore failed: ${(probe.stderr || probe.stdout).trim()}`);
+  })();
+  if (!node.stat.isSymbolicLink()) {
+    const kind = node.stat.isDirectory() ? 'directory' : node.stat.isFile() ? 'file' : 'special';
+    return { klass: 'foreign', kind, lane, nmPath };
+  }
+  const target = (() => {
+    try {
+      return { bytes: fs.readlink(nmPath, { encoding: 'buffer' }) };
+    } catch (error) {
+      return { error: error?.code ?? 'fs error' };
+    }
+  })();
+  if (target.error) throw nodeModulesInspectStop(nmPath, target.error);
+  // Raw BYTES against MAIN's node_modules path — never decoded, never resolved: a relative or
+  // re-encoded form that merely RESOLVES to main stays foreign, and the target's kind is
+  // irrelevant (unlink touches only the link).
+  const matches = Buffer.compare(target.bytes, Buffer.from(join(mainRoot, NODE_MODULES_REL))) === 0;
+  return { klass: matches ? 'ephemeral' : 'foreign', kind: 'symlink', lane, nmPath };
+};
+
+const nodeModulesExemptVerdict = (snapshot) => snapshot.klass === 'ephemeral' && snapshot.lane === 'ignored';
+
+const composeNodeModulesStop = ({ snapshot, slug, branch, changed = false }) => {
+  const { klass, kind, lane, nmPath } = snapshot;
+  const kindDesc = kind === 'symlink'
+    ? (klass === 'ephemeral' ? 'a main-matching symlink' : 'a foreign symlink')
+    : kind === 'directory' ? 'a directory'
+      : kind === 'file' ? 'a regular file'
+        : kind === 'special' ? 'a special node' : 'absent';
+  const head = `cleanup stopped: ${nmPath} is ${kindDesc} in the ${lane} lane`
+    + `${changed ? ' (changed during cleanup)' : ''}\n${CLEANUP_OWNERSHIP_RULE}`;
+  if (lane === 'tracked') {
+    return stop([
+      head,
+      'this node_modules is tracked: removing it by hand only creates drift that stops cleanup earlier — land its removal from MAIN, then re-run cleanup',
+      destructiveRecovery({ slug, branch }),
+    ].join('\n'));
+  }
+  const removal = kind === 'directory' ? `rm -rf -- ${shellQuoteArg(nmPath)}` : `rm -- ${shellQuoteArg(nmPath)}`;
+  return stop([
+    head,
+    `remove it yourself, then re-run cleanup: ${removal}`,
+    destructiveRecovery({ slug, branch }),
+  ].join('\n'));
+};
+
 const composeCleanupCommand = ({ slug, branch, abandon }) =>
   `cleanup ${shellQuoteArg(slug)}` +
   `${branch === `${DEFAULT_BRANCH_PREFIX}${slug}` ? '' : ` --branch ${shellQuoteArg(branch)}`}` +
@@ -2380,6 +2663,7 @@ export const runCleanup = ({ argvSlug, flags, cwd, git, deps, log }) => {
 
     const knownRoots = provisionKnownRoots(identity);
     let removalRoots = [];
+    let nodeModulesExempt = false;
     if (!flags.abandon) {
       const mainHead = gitRead(git, ['rev-parse', 'HEAD'], root, 'cannot resolve main HEAD').stdout.trim();
       // Transfer verification excludes docs/ai and docs/plans; their tracked drift is checked separately before reset.
@@ -2422,6 +2706,16 @@ export const runCleanup = ({ argvSlug, flags, cwd, git, deps, log }) => {
         );
       }
 
+      // The ownership gate (AD-069) runs BEFORE the inventories: it also catches tracked
+      // node_modules and empty untracked directories git never lists. Clean-absent proceeds on
+      // the legacy path with no post-reset ownership arm; the single exemption is re-proven
+      // below, immediately before the irreversible remove.
+      const ownership = nodeModulesSnapshot({ wtRoot: entry.path, mainRoot: root, git, fs });
+      if (!nodeModulesExemptVerdict(ownership) && !(ownership.klass === 'absent' && ownership.lane !== 'tracked')) {
+        throw composeNodeModulesStop({ snapshot: ownership, slug, branch });
+      }
+      nodeModulesExempt = nodeModulesExemptVerdict(ownership);
+
       const untracked = untrackedPaths(git, entry.path);
       const foreign = [];
       for (const path of untracked) {
@@ -2435,7 +2729,7 @@ export const runCleanup = ({ argvSlug, flags, cwd, git, deps, log }) => {
           destructiveRecovery({ slug, branch }),
         );
       }
-      const foreignIgnored = foreignIgnoredPaths({ root: entry.path, git, identity, fs });
+      const foreignIgnored = foreignIgnoredPaths({ root: entry.path, git, identity, fs, exemptNodeModules: nodeModulesExempt });
       if (foreignIgnored.length > 0) {
         throw stop(`foreign ignored content requires --abandon:\n${foreignIgnored.join('\n')}`);
       }
@@ -2455,6 +2749,20 @@ export const runCleanup = ({ argvSlug, flags, cwd, git, deps, log }) => {
       for (const rel of removalRoots) {
         removeNodeNoFollow({ root: entry.path, abs: join(entry.path, rel), fs, label: rel });
       }
+      if (nodeModulesExempt) {
+        // The authoritative re-proof (AD-069): the verdict authorizing the irreversible remove
+        // postdates the last tree-mutating operation. Strict equality with the exempt state —
+        // never re-authorization: ANY deviation fails closed with no remove call.
+        const revalidated = nodeModulesSnapshot({ wtRoot: entry.path, mainRoot: root, git, fs });
+        if (!nodeModulesExemptVerdict(revalidated)) {
+          if (revalidated.klass === 'absent' && revalidated.lane !== 'tracked') {
+            throw stop(
+              `cleanup stopped: ${revalidated.nmPath} changed during cleanup (now absent) — re-run cleanup\n${CLEANUP_OWNERSHIP_RULE}`,
+            );
+          }
+          throw composeNodeModulesStop({ snapshot: revalidated, slug, branch, changed: true });
+        }
+      }
     }
 
     removeWorktree({ root, entry, branch, abandon: flags.abandon, git });