@deftai/directive-core 0.103.0 → 0.105.0

package/dist/fs/contained-write.js

@@ -15,10 +15,25 @@
  * onto this API over bespoke per-sink checks when equivalent. See
  * `docs/reference/contained-write.md`.
  *
- * Refs #2951.
+ * Delete coverage (#3392 / #3456): real dest deletes MUST go through
+ * {@link containedRemove} so a bound ledger (and ADR-004 record mode) records
+ * them. Raw `rmSync` on a dest path is a chokepoint bypass.
+ *
+ * Plan-mode zero-mutation (#3456 / ADR-004): `deft update --dry-run` binds
+ * this port in record mode (`runInPortRecordMode`). Dest write / remove /
+ * chmod / dest-mutating exec record and skip dest IO. Temp-file cleanups
+ * either use this chokepoint or live outside the project root.
+ *
+ * `tryCleanupLegacyDeftTree` is not on the update/dry-run path (classify
+ * refuses `migration-required` first). Its default removeDir still routes
+ * through containedRemove so the site is not a silent exception.
+ *
+ * Refs #2951 / #3392 / #3456.
  */
-import { closeSync, constants, existsSync, lstatSync, mkdirSync, openSync, realpathSync, writeSync, } from "node:fs";
-import { dirname, isAbsolute, relative, resolve } from "node:path";
+import { execFileSync } from "node:child_process";
+import { chmodSync, closeSync, constants, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, realpathSync, renameSync, rmSync, unlinkSync, writeSync, } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { isAtomicWriteTemp, isPortRecordMode, recordActiveMutation, } from "./mutation-ledger.js";
 import { assertWriteTargetSafe, ProjectionContainmentError } from "./projection-containment.js";
 /** Stable machine-readable error codes for contained-write refusals. */
 export const ContainedWriteErrorCode = {
@@ -133,6 +148,68 @@ function ensureParents(rootAbs, targetAbs) {
 function toBuffer(data, encoding) {
     return Buffer.isBuffer(data) ? data : Buffer.from(data, encoding);
 }
+/**
+ * Remove resolver: lexical nest + refuse parent-path symlinks. The leaf may be
+ * a symlink — unlink the link itself (never follow, never abort).
+ */
+function resolveExistingRootForRemove(root, target) {
+    const rootAbs = resolve(root);
+    try {
+        realpathSync(rootAbs);
+    }
+    catch {
+        throw new ContainedWriteError(`contained write refused: root ${rootAbs} does not exist`, {
+            code: ContainedWriteErrorCode.ROOT_MISSING,
+            root: rootAbs,
+            target: String(target),
+            offendingPath: rootAbs,
+        });
+    }
+    const targetAbs = resolveContainedTarget(rootAbs, target);
+    const parentAbs = dirname(targetAbs);
+    if (parentAbs !== rootAbs && parentAbs !== targetAbs) {
+        const rel = relative(rootAbs, parentAbs);
+        if (rel.length > 0 && !rel.startsWith("..") && !isAbsolute(rel)) {
+            let current = rootAbs;
+            for (const segment of rel.split(/[\\/]+/).filter((part) => part.length > 0)) {
+                current = join(current, segment);
+                let info;
+                try {
+                    info = lstatSync(current);
+                }
+                catch {
+                    break;
+                }
+                if (info.isSymbolicLink()) {
+                    throw new ContainedWriteError(`contained write refused: ${current} is a symlink on the remove parent path`, {
+                        code: ContainedWriteErrorCode.SYMLINK,
+                        root: rootAbs,
+                        target: targetAbs,
+                        offendingPath: current,
+                    });
+                }
+            }
+        }
+    }
+    return { rootAbs, targetAbs };
+}
+function recordWriteMutation(targetAbs, mutation) {
+    if (mutation === false)
+        return;
+    const kind = mutation?.kind ?? "wrote";
+    const path = mutation?.path ?? targetAbs;
+    if (mutation?.path === undefined && isAtomicWriteTemp(path))
+        return;
+    recordActiveMutation(kind, path);
+}
+function recordRemoveMutation(targetAbs, mutation) {
+    if (mutation === false)
+        return;
+    const path = mutation?.path ?? targetAbs;
+    if (mutation?.path === undefined && isAtomicWriteTemp(path))
+        return;
+    recordActiveMutation("deleted", path);
+}
 function writeNoFollow(targetAbs, buf, flags) {
     const fd = openSync(targetAbs, flags, 0o644);
     try {
@@ -144,6 +221,7 @@ function writeNoFollow(targetAbs, buf, flags) {
             }
             offset += n;
         }
+        fsyncSync(fd);
         return offset;
     }
     finally {
@@ -193,6 +271,27 @@ export function containedWrite(input) {
         }
         throw err;
     }
+    const encoding = input.encoding ?? "utf8";
+    const buf = toBuffer(input.data, encoding);
+    if (isPortRecordMode()) {
+        if (input.mode === "create") {
+            try {
+                lstatSync(targetAbs);
+                throw new ContainedWriteError(`contained write refused: target ${targetAbs} already exists (mode=create)`, {
+                    code: ContainedWriteErrorCode.EXISTS,
+                    root: rootAbs,
+                    target: targetAbs,
+                    offendingPath: targetAbs,
+                });
+            }
+            catch (err) {
+                if (err instanceof ContainedWriteError)
+                    throw err;
+            }
+        }
+        recordWriteMutation(targetAbs, input.mutation);
+        return { path: targetAbs, bytesWritten: buf.length, mode: input.mode };
+    }
     const doMkdir = input.mkdir !== false;
     if (doMkdir) {
         ensureParents(rootAbs, targetAbs);
@@ -207,8 +306,6 @@ export function containedWrite(input) {
         }
         throw err;
     }
-    const encoding = input.encoding ?? "utf8";
-    const buf = toBuffer(input.data, encoding);
     let exists = false;
     try {
         lstatSync(targetAbs);
@@ -238,6 +335,7 @@ export function containedWrite(input) {
             // replace
             bytesWritten = writeNoFollow(targetAbs, buf, constants.O_WRONLY | constants.O_CREAT | constants.O_TRUNC | constants.O_NOFOLLOW);
         }
+        recordWriteMutation(targetAbs, input.mutation);
         return { path: targetAbs, bytesWritten, mode: input.mode };
     }
     catch (err) {
@@ -278,4 +376,143 @@ export function containedWrite(input) {
         });
     }
 }
+/**
+ * Contained remove: resolve under root, refuse parent-path symlink / out-of-root,
+ * then delete. An in-root leaf symlink is unlinked (not followed, not refused).
+ * Missing targets are a no-op (not ledgered).
+ *
+ * @throws {ContainedWriteError} on containment refusal
+ */
+export function containedRemove(input) {
+    const { rootAbs, targetAbs } = resolveExistingRootForRemove(input.root, input.target);
+    let info;
+    try {
+        info = lstatSync(targetAbs);
+    }
+    catch (err) {
+        const code = typeof err === "object" && err !== null && "code" in err
+            ? err.code
+            : undefined;
+        if (code === "ENOENT") {
+            return { path: targetAbs, removed: false };
+        }
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new ContainedWriteError(`contained write I/O failed: ${msg}`, {
+            code: ContainedWriteErrorCode.IO,
+            root: rootAbs,
+            target: targetAbs,
+            offendingPath: targetAbs,
+        });
+    }
+    if (isPortRecordMode()) {
+        recordRemoveMutation(targetAbs, input.mutation);
+        return { path: targetAbs, removed: true };
+    }
+    try {
+        if (info.isSymbolicLink()) {
+            unlinkSync(targetAbs);
+        }
+        else {
+            rmSync(targetAbs, { force: true, recursive: input.recursive === true });
+        }
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new ContainedWriteError(`contained write I/O failed: ${msg}`, {
+            code: ContainedWriteErrorCode.IO,
+            root: rootAbs,
+            target: targetAbs,
+            offendingPath: targetAbs,
+        });
+    }
+    recordRemoveMutation(targetAbs, input.mutation);
+    return { path: targetAbs, removed: true };
+}
+/**
+ * Contained mkdir: nest under root. Record mode skips dest IO (dirs are not
+ * dest-file membership). Live path creates recursively.
+ */
+export function containedMkdir(input) {
+    const targetAbs = resolveContainedTarget(input.root, input.target);
+    if (isPortRecordMode()) {
+        return { path: targetAbs };
+    }
+    mkdirSync(targetAbs, { recursive: true });
+    return { path: targetAbs };
+}
+/**
+ * Contained chmod: resolve under root, refuse parent-path symlink / out-of-root,
+ * then set mode. Record mode records `chmod` and skips dest IO.
+ */
+export function containedChmod(input) {
+    const { rootAbs, targetAbs } = resolveExistingRootForRemove(input.root, input.target);
+    if (input.mutation !== false) {
+        recordActiveMutation("chmod", input.mutation?.path ?? targetAbs);
+    }
+    if (isPortRecordMode()) {
+        return { path: targetAbs };
+    }
+    try {
+        chmodSync(targetAbs, input.mode);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new ContainedWriteError(`contained write I/O failed: ${msg}`, {
+            code: ContainedWriteErrorCode.IO,
+            root: rootAbs,
+            target: targetAbs,
+            offendingPath: targetAbs,
+        });
+    }
+    return { path: targetAbs };
+}
+/**
+ * Contained rename: both paths must nest under root. Record mode records
+ * `wrote` on `to` (unless `mutation: false`) and skips dest IO.
+ */
+export function containedRename(input) {
+    const fromAbs = resolveContainedTarget(input.root, input.from);
+    const toAbs = resolveContainedTarget(input.root, input.to);
+    if (input.mutation !== false) {
+        const kind = input.mutation?.kind ?? "wrote";
+        recordActiveMutation(kind, input.mutation?.path ?? toAbs);
+    }
+    if (isPortRecordMode()) {
+        return { from: fromAbs, to: toAbs };
+    }
+    try {
+        renameSync(fromAbs, toAbs);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new ContainedWriteError(`contained write I/O failed: ${msg}`, {
+            code: ContainedWriteErrorCode.IO,
+            root: resolve(input.root),
+            target: toAbs,
+            offendingPath: toAbs,
+        });
+    }
+    return { from: fromAbs, to: toAbs };
+}
+/**
+ * Dest-mutating exec (git config, git add, …). Record mode records `exec` on
+ * `destTarget` and skips the child process. Allowlisted as the port impl.
+ */
+export function containedDestExec(input) {
+    const targetAbs = resolveContainedTarget(input.root, input.destTarget);
+    recordActiveMutation("exec", targetAbs);
+    if (isPortRecordMode()) {
+        return { ok: true, stdout: "" };
+    }
+    try {
+        const stdout = execFileSync(input.file, [...input.args], {
+            encoding: "utf8",
+            cwd: resolve(input.root),
+        });
+        return { ok: true, stdout };
+    }
+    catch {
+        return { ok: false, stdout: "" };
+    }
+}
 //# sourceMappingURL=contained-write.js.map

package/dist/fs/mutation-ledger.d.ts

@@ -0,0 +1,54 @@
+/**
+ * mutation-ledger.ts — typed deposit mutation log at the write chokepoint (#3392).
+ *
+ * A bound ledger records wrote / stripped / deleted as a side effect of
+ * containedWrite / containedRemove. Callers cannot discard mutations by
+ * ignoring a writer return value.
+ *
+ * Refs #3392 / #3378.
+ */
+export declare const MUTATION_KINDS: readonly ["wrote", "stripped", "deleted", "chmod", "exec"];
+export type MutationKind = (typeof MUTATION_KINDS)[number];
+export interface MutationEntry {
+    readonly kind: MutationKind;
+    readonly path: string;
+}
+export interface MutationSummary {
+    readonly wrote: readonly string[];
+    readonly stripped: readonly string[];
+    readonly deleted: readonly string[];
+    readonly chmod: readonly string[];
+    readonly exec: readonly string[];
+    readonly mutations: readonly MutationEntry[];
+}
+export declare function isAtomicWriteTemp(path: string): boolean;
+/** Posix-relative path under `root`, or empty when the target is not nested. */
+export declare function toLedgerPath(root: string, target: string): string;
+export declare function emptyMutationSummary(): MutationSummary;
+/** In-memory ledger for one deposit/refresh run. */
+export declare class MutationLedger {
+    readonly root: string;
+    private readonly recorded;
+    constructor(root: string);
+    record(kind: MutationKind, target: string): void;
+    entries(): readonly MutationEntry[];
+    summarize(): MutationSummary;
+}
+export declare function activeMutationLedger(): MutationLedger | undefined;
+/** ADR-004: dest-mutating port calls record and skip dest IO. */
+export declare function runInPortRecordMode<T>(fn: () => T): T;
+export declare function isPortRecordMode(): boolean;
+/** Bind a ledger for the duration of `fn` (including awaited continuations). */
+export declare function runWithMutationLedger<T>(root: string, fn: () => T): T;
+export declare function recordActiveMutation(kind: MutationKind, target: string): void;
+export declare function snapshotMutationSummary(): MutationSummary;
+/** Human summary: `Removed:` plus wrote/stripped. Empty when nothing mutated. */
+export declare function formatMutationSummary(summary: MutationSummary): string;
+export declare function mutationSummaryJson(summary: MutationSummary): {
+    wrote: string[];
+    stripped: string[];
+    deleted: string[];
+    chmod: string[];
+    exec: string[];
+};
+//# sourceMappingURL=mutation-ledger.d.ts.map

package/dist/fs/mutation-ledger.js

@@ -0,0 +1,133 @@
+/**
+ * mutation-ledger.ts — typed deposit mutation log at the write chokepoint (#3392).
+ *
+ * A bound ledger records wrote / stripped / deleted as a side effect of
+ * containedWrite / containedRemove. Callers cannot discard mutations by
+ * ignoring a writer return value.
+ *
+ * Refs #3392 / #3378.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+import { isAbsolute, relative, resolve } from "node:path";
+export const MUTATION_KINDS = ["wrote", "stripped", "deleted", "chmod", "exec"];
+/** Atomic-replace temps (`name.deft-<pid>.tmp`) are not logical mutations. */
+const ATOMIC_TMP = /\.deft-\d+\.tmp$/u;
+export function isAtomicWriteTemp(path) {
+    return ATOMIC_TMP.test(path.replace(/\\/g, "/"));
+}
+/** Posix-relative path under `root`, or empty when the target is not nested. */
+export function toLedgerPath(root, target) {
+    const rootAbs = resolve(root);
+    const targetAbs = isAbsolute(target) ? resolve(target) : resolve(rootAbs, target);
+    const rel = relative(rootAbs, targetAbs);
+    if (rel.length === 0 || rel.startsWith("..") || isAbsolute(rel))
+        return "";
+    return rel.split("\\").join("/");
+}
+export function emptyMutationSummary() {
+    return { wrote: [], stripped: [], deleted: [], chmod: [], exec: [], mutations: [] };
+}
+function summarizeEntries(entries) {
+    const latest = new Map();
+    const order = [];
+    for (const entry of entries) {
+        if (!latest.has(entry.path))
+            order.push(entry.path);
+        latest.set(entry.path, entry.kind);
+    }
+    const wrote = [];
+    const stripped = [];
+    const deleted = [];
+    const chmod = [];
+    const exec = [];
+    const mutations = [];
+    for (const path of order) {
+        const kind = latest.get(path);
+        if (kind === undefined)
+            continue;
+        mutations.push({ kind, path });
+        if (kind === "wrote")
+            wrote.push(path);
+        else if (kind === "stripped")
+            stripped.push(path);
+        else if (kind === "chmod")
+            chmod.push(path);
+        else if (kind === "exec")
+            exec.push(path);
+        else
+            deleted.push(path);
+    }
+    return { wrote, stripped, deleted, chmod, exec, mutations };
+}
+/** In-memory ledger for one deposit/refresh run. */
+export class MutationLedger {
+    root;
+    recorded = [];
+    constructor(root) {
+        this.root = resolve(root);
+    }
+    record(kind, target) {
+        const path = toLedgerPath(this.root, target);
+        if (path.length === 0)
+            return;
+        this.recorded.push({ kind, path });
+    }
+    entries() {
+        return this.recorded;
+    }
+    summarize() {
+        return summarizeEntries(this.recorded);
+    }
+}
+const storage = new AsyncLocalStorage();
+const recordModeStorage = new AsyncLocalStorage();
+export function activeMutationLedger() {
+    return storage.getStore();
+}
+/** ADR-004: dest-mutating port calls record and skip dest IO. */
+export function runInPortRecordMode(fn) {
+    return recordModeStorage.run(true, fn);
+}
+export function isPortRecordMode() {
+    return recordModeStorage.getStore() === true;
+}
+/** Bind a ledger for the duration of `fn` (including awaited continuations). */
+export function runWithMutationLedger(root, fn) {
+    return storage.run(new MutationLedger(root), fn);
+}
+export function recordActiveMutation(kind, target) {
+    activeMutationLedger()?.record(kind, target);
+}
+export function snapshotMutationSummary() {
+    return activeMutationLedger()?.summarize() ?? emptyMutationSummary();
+}
+/** Human summary: `Removed:` plus wrote/stripped. Empty when nothing mutated. */
+export function formatMutationSummary(summary) {
+    const lines = [];
+    if (summary.deleted.length > 0) {
+        lines.push(`Removed: ${summary.deleted.join(", ")}`);
+    }
+    if (summary.wrote.length > 0) {
+        lines.push(`wrote: ${summary.wrote.join(", ")}`);
+    }
+    if (summary.stripped.length > 0) {
+        lines.push(`stripped: ${summary.stripped.join(", ")}`);
+    }
+    if (summary.chmod.length > 0) {
+        lines.push(`chmod: ${summary.chmod.join(", ")}`);
+    }
+    if (summary.exec.length > 0) {
+        lines.push(`exec: ${summary.exec.join(", ")}`);
+    }
+    return lines.length > 0 ? `${lines.join("\n")}\n` : "";
+}
+export function mutationSummaryJson(summary) {
+    return {
+        wrote: [...summary.wrote],
+        stripped: [...summary.stripped],
+        deleted: [...summary.deleted],
+        chmod: [...summary.chmod],
+        exec: [...summary.exec],
+    };
+}
+//# sourceMappingURL=mutation-ledger.js.map

package/dist/fs/non-product-dirs.d.ts

@@ -0,0 +1,79 @@
+/**
+ * non-product-dirs.ts — one source of truth for the "not product source"
+ * directory basenames shared by every Directive filesystem walk (#3487).
+ *
+ * Directive shipped four independently hand-maintained exclusion sets:
+ *
+ *   - `EXCLUDE_DIRS`     — `verify-source/verify-stubs.ts`
+ *   - `EXCLUDE_DIRS`     — `validate-content/validate-links.ts`
+ *   - `SKIP_DIRS`        — `codebase/default-extractor.ts`
+ *   - `DEFAULT_EXCLUDES` — `release/build-dist.ts`
+ *
+ * They drifted from each other, which is exactly how #2953 added
+ * `.deft-scratch` / `swarm-worktrees` to some walks and missed the
+ * `verify-stubs` walk (#3481), and how none of them ever learned about agent
+ * working directories even though Directive ships first-class support for
+ * several agent hosts. Because `@deftai/directive-core` is published, a
+ * consumer cannot patch any of the four.
+ *
+ * `NON_PRODUCT_DIRS` is the common core each walk now extends. It carries only
+ * basenames that are never product source in any repo: VCS metadata,
+ * dependency trees, build output, tool caches, and agent working directories.
+ * Walk-specific entries (`tests`, `specs`, `.planning`, `htmlcov`, …) stay with
+ * the walk that needs them — this constant is a floor, not a ceiling.
+ *
+ * Adding a directory here is a one-line change all four walks pick up, and
+ * `non-product-dirs.test.ts` fails if any of them stops agreeing.
+ *
+ * Refs #3487, #3481, #2953, #2954, #1656.
+ */
+/**
+ * Swarm / agent scratch worktree roots (#2953, #1656).
+ *
+ * `.deft-scratch` is the current layout (`.deft-scratch/worktrees/<story-id>`,
+ * built by `swarm/launch.ts`); `swarm-worktrees` is the pre-`.deft-scratch`
+ * name, kept for repos that still carry one.
+ */
+export declare const AGENT_SCRATCH_DIRS: readonly string[];
+/**
+ * Agent-host directories that hold host *working* state rather than product
+ * source (#3487).
+ *
+ * Only names with evidence of a real working directory belong here. Directive
+ * knows several host directories (`.claude`, `.cursor`, `.grok`, `.codex`,
+ * `.github/skills`, `.agents`), but most of them hold nothing except
+ * Directive's own committed deposits — `commands.md` § Native multi-host
+ * registration (LockedDecision L8) says to *commit* those, so blanket-excluding
+ * them would hide committed team surface for no measured gain.
+ *
+ * `.claude` is different in kind: the Claude Code host keeps live session state
+ * in the same directory it keeps config — `settings.local.json`, and agent
+ * worktrees under `.claude/worktrees/<agent-id>`, each a full nested checkout.
+ * Three such worktrees added ~11,000 walkable entries to this repo
+ * (9,128 → 20,393) that no Directive walk skipped. Its Directive-managed
+ * contents (`.claude/settings.json`, `.claude/commands/*.md`,
+ * `.claude/skills/`) are deposits generated from `content/`, which every walk
+ * still visits at the authoring source.
+ *
+ * Deliberately **not** listed:
+ *   - `.openclaw` — there is no project-level `.openclaw/`; the host state dir
+ *     is `~/.openclaw` in `$HOME` (see `doctor/openclaw-skills.ts`), and
+ *     inventing a project one is explicitly forbidden by
+ *     `content/docs/openclaw-agent-host.md` and asserted against in
+ *     `slash/openclaw-adapter.test.ts`.
+ *   - `.cursor`, `.grok`, `.codex`, `.github` — committed Directive deposits
+ *     (`.cursor/hooks.json`, `.grok/commands/`, `.codex/prompts/`,
+ *     `.github/skills/`) with no known working/worktree subtree. No evidence
+ *     of a scratch convention was found for any of them.
+ */
+export declare const AGENT_HOST_WORKING_DIRS: readonly string[];
+/**
+ * Directory basenames no Directive walk should descend into.
+ *
+ * Every walk extends this set; none may shrink it. Keep entries to basenames
+ * that cannot be product source in any repo — a name that is merely *usually*
+ * uninteresting to one gate (`tests`, `scripts`, `specs`) belongs to that
+ * walk's own set, not here.
+ */
+export declare const NON_PRODUCT_DIRS: ReadonlySet<string>;
+//# sourceMappingURL=non-product-dirs.d.ts.map

package/dist/fs/non-product-dirs.js

@@ -0,0 +1,96 @@
+/**
+ * non-product-dirs.ts — one source of truth for the "not product source"
+ * directory basenames shared by every Directive filesystem walk (#3487).
+ *
+ * Directive shipped four independently hand-maintained exclusion sets:
+ *
+ *   - `EXCLUDE_DIRS`     — `verify-source/verify-stubs.ts`
+ *   - `EXCLUDE_DIRS`     — `validate-content/validate-links.ts`
+ *   - `SKIP_DIRS`        — `codebase/default-extractor.ts`
+ *   - `DEFAULT_EXCLUDES` — `release/build-dist.ts`
+ *
+ * They drifted from each other, which is exactly how #2953 added
+ * `.deft-scratch` / `swarm-worktrees` to some walks and missed the
+ * `verify-stubs` walk (#3481), and how none of them ever learned about agent
+ * working directories even though Directive ships first-class support for
+ * several agent hosts. Because `@deftai/directive-core` is published, a
+ * consumer cannot patch any of the four.
+ *
+ * `NON_PRODUCT_DIRS` is the common core each walk now extends. It carries only
+ * basenames that are never product source in any repo: VCS metadata,
+ * dependency trees, build output, tool caches, and agent working directories.
+ * Walk-specific entries (`tests`, `specs`, `.planning`, `htmlcov`, …) stay with
+ * the walk that needs them — this constant is a floor, not a ceiling.
+ *
+ * Adding a directory here is a one-line change all four walks pick up, and
+ * `non-product-dirs.test.ts` fails if any of them stops agreeing.
+ *
+ * Refs #3487, #3481, #2953, #2954, #1656.
+ */
+/**
+ * Swarm / agent scratch worktree roots (#2953, #1656).
+ *
+ * `.deft-scratch` is the current layout (`.deft-scratch/worktrees/<story-id>`,
+ * built by `swarm/launch.ts`); `swarm-worktrees` is the pre-`.deft-scratch`
+ * name, kept for repos that still carry one.
+ */
+export const AGENT_SCRATCH_DIRS = [".deft-scratch", "swarm-worktrees"];
+/**
+ * Agent-host directories that hold host *working* state rather than product
+ * source (#3487).
+ *
+ * Only names with evidence of a real working directory belong here. Directive
+ * knows several host directories (`.claude`, `.cursor`, `.grok`, `.codex`,
+ * `.github/skills`, `.agents`), but most of them hold nothing except
+ * Directive's own committed deposits — `commands.md` § Native multi-host
+ * registration (LockedDecision L8) says to *commit* those, so blanket-excluding
+ * them would hide committed team surface for no measured gain.
+ *
+ * `.claude` is different in kind: the Claude Code host keeps live session state
+ * in the same directory it keeps config — `settings.local.json`, and agent
+ * worktrees under `.claude/worktrees/<agent-id>`, each a full nested checkout.
+ * Three such worktrees added ~11,000 walkable entries to this repo
+ * (9,128 → 20,393) that no Directive walk skipped. Its Directive-managed
+ * contents (`.claude/settings.json`, `.claude/commands/*.md`,
+ * `.claude/skills/`) are deposits generated from `content/`, which every walk
+ * still visits at the authoring source.
+ *
+ * Deliberately **not** listed:
+ *   - `.openclaw` — there is no project-level `.openclaw/`; the host state dir
+ *     is `~/.openclaw` in `$HOME` (see `doctor/openclaw-skills.ts`), and
+ *     inventing a project one is explicitly forbidden by
+ *     `content/docs/openclaw-agent-host.md` and asserted against in
+ *     `slash/openclaw-adapter.test.ts`.
+ *   - `.cursor`, `.grok`, `.codex`, `.github` — committed Directive deposits
+ *     (`.cursor/hooks.json`, `.grok/commands/`, `.codex/prompts/`,
+ *     `.github/skills/`) with no known working/worktree subtree. No evidence
+ *     of a scratch convention was found for any of them.
+ */
+export const AGENT_HOST_WORKING_DIRS = [".claude"];
+/**
+ * Directory basenames no Directive walk should descend into.
+ *
+ * Every walk extends this set; none may shrink it. Keep entries to basenames
+ * that cannot be product source in any repo — a name that is merely *usually*
+ * uninteresting to one gate (`tests`, `scripts`, `specs`) belongs to that
+ * walk's own set, not here.
+ */
+export const NON_PRODUCT_DIRS = new Set([
+    // Version-control metadata.
+    ".git",
+    // Dependency trees and language virtualenvs.
+    "node_modules",
+    ".venv",
+    // Build output and operator backups.
+    "dist",
+    "backup",
+    // Tool caches.
+    "__pycache__",
+    ".mypy_cache",
+    ".pytest_cache",
+    ".ruff_cache",
+    // Agent working directories.
+    ...AGENT_SCRATCH_DIRS,
+    ...AGENT_HOST_WORKING_DIRS,
+]);
+//# sourceMappingURL=non-product-dirs.js.map

package/dist/hooks/dispatcher.d.ts

@@ -21,7 +21,9 @@ export type HookDecisionCode = "session-start" | "session-start-disabled" | "ses
 /** Enforcement skipped: root `.deft-directive-disable` test kill-switch (#3039). */
  | "directive-disabled" | "session-compact-rearm" | "session-compact-rearm-degraded" | "session-compact-noop" | "not-direct-write" | "invalid-input"
 /** Host closed stdin with zero bytes — integration failure, not a policy gate (#2864). */
- | "stdin-empty" | "ritual-not-ready" | "scope-not-ready" | "write-propose-ready"
+ | "stdin-empty" | "ritual-not-ready"
+/** Product-path write while another live session occupies this worktree (#3433). */
+ | "occupancy-occupied" | "scope-not-ready" | "write-propose-ready"
 /** Allowlisted assist/scratch write without active xBRIEF (#1802). */
  | "write-assist-scratch-ready" | "write-ready" | "read-only-deny" | "spawn-explore-ready"
 /** Non-lifecycle assist/docs spawn allowed without active xBRIEF (#3080). */