@deftai/directive-core 0.87.0 → 0.89.0

package/dist/branch/evaluate.js

@@ -1,6 +1,7 @@
 import { recordBypassSignal, recordGateCatch } from "../events/attribution-ledger.js";
 import { disclosureLine } from "../policy/disclosure.js";
 import { policyColonInvocation } from "../policy/policy-invocation.js";
+import { humanMergeBranchNote, resolveHumanMergePolicy } from "../policy/require-human-merge.js";
 import { ENV_BYPASS, resolvePolicy } from "../policy/resolve.js";
 import { currentBranch, GitNotFoundError } from "./git.js";
 export const DEFAULT_BRANCHES = new Set(["master", "main"]);
@@ -93,9 +94,13 @@ export function evaluate(projectRoot, options = {}) {
         };
     }
     if (!isDefaultBranch(branch, defaultBranches)) {
+        // Surface (2) human-merge gate: advisory note on feature branches (#1193).
+        const hm = resolveHumanMergePolicy(projectRoot);
+        const hmNote = humanMergeBranchNote(hm);
+        const base = `✓ deft branch-protection: feature branch '${branch}' -- proceeding.`;
         return {
             exitCode: 0,
-            message: `✓ deft branch-protection: feature branch '${branch}' -- proceeding.`,
+            message: hmNote !== null ? `${base}\n${hmNote}` : base,
         };
     }
     const result = resolvePolicy(projectRoot);

package/dist/cache/fetch.js

@@ -1,6 +1,6 @@
-import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
-import { assertWriteTargetSafe, ProjectionContainmentError } from "../fs/projection-containment.js";
+import { ContainedWriteError, containedWrite } from "../fs/contained-write.js";
 import { GhRestError, InvalidRepoError, restIssueView, runGhApi, } from "../scm/gh-rest.js";
 import { DEFAULT_BATCH_SIZE, DEFAULT_DELAY_MS } from "./constants.js";
 import { CacheError, CacheFetchError } from "./errors.js";
@@ -622,8 +622,13 @@ function readSelfHealState(cacheRoot) {
 }
 function writeSelfHealState(projectRoot, cacheRoot, when) {
     const path = join(resolve(cacheRoot), SELF_HEAL_STATE_FILENAME);
-    assertWriteTargetSafe(projectRoot, path);
-    writeFileSync(path, `${JSON.stringify({ last_reconcile_at: when.toISOString() })}\n`, "utf8");
+    // #2980 wave C: product write sink routes through containedWrite.
+    containedWrite({
+        root: resolve(projectRoot),
+        target: path,
+        data: `${JSON.stringify({ last_reconcile_at: when.toISOString() })}\n`,
+        mode: "replace",
+    });
 }
 /** TTL-bounded closed-reconcile for session ritual / triage:welcome self-healing (#1886). */
 export function maybeSelfHealCache(projectRoot, options = {}) {
@@ -679,7 +684,7 @@ export function maybeSelfHealCache(projectRoot, options = {}) {
                 writeSelfHealState(projectRoot, cacheRoot, now);
             }
             catch (err) {
-                if (err instanceof ProjectionContainmentError) {
+                if (err instanceof ContainedWriteError) {
                     return { skipped: true, skipReason: "containment-refused", drift, refresh: null };
                 }
                 throw err;

package/dist/cache/io.d.ts

@@ -1,7 +1,14 @@
 import { tmpdir } from "node:os";
-/** Write text via tempfile + rename (mirrors Python `_atomic_write_text`). */
+/**
+ * Write text via tempfile + rename (mirrors Python `_atomic_write_text`).
+ * #2951 Phase 2: temp payload write uses containedWrite under the parent dir.
+ */
 export declare function atomicWriteText(path: string, text: string): void;
-/** Append one JSON audit record (mirrors `_append_audit`). */
+/**
+ * Append one JSON audit record (mirrors `_append_audit`).
+ * #2951 Phase 2: product write sink routes through containedWrite.
+ * Create cacheRoot first — containedWrite requires the containment root to exist.
+ */
 export declare function appendAudit(record: Record<string, unknown>, cacheRoot: string): void;
 /** Touch mtime for LRU signal; failures swallowed. */
 export declare function touchMtime(path: string): void;

package/dist/cache/io.js

@@ -1,14 +1,25 @@
 import { randomBytes } from "node:crypto";
-import { appendFileSync, mkdirSync, renameSync, rmSync, statSync, utimesSync, writeFileSync, } from "node:fs";
+import { mkdirSync, renameSync, rmSync, statSync, utimesSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { dirname, join } from "node:path";
+import { basename, dirname, join, resolve } from "node:path";
+import { containedWrite } from "../fs/contained-write.js";
 import { pythonJsonLine } from "./json.js";
-/** Write text via tempfile + rename (mirrors Python `_atomic_write_text`). */
+/**
+ * Write text via tempfile + rename (mirrors Python `_atomic_write_text`).
+ * #2951 Phase 2: temp payload write uses containedWrite under the parent dir.
+ */
 export function atomicWriteText(path, text) {
-    mkdirSync(dirname(path), { recursive: true });
-    const tmp = join(dirname(path), `${path.split(/[/\\]/).pop() ?? "file"}.${randomBytes(4).toString("hex")}.tmp`);
+    const dir = dirname(path);
+    mkdirSync(dir, { recursive: true });
+    const tmpName = `${basename(path)}.${randomBytes(4).toString("hex")}.tmp`;
+    const tmp = join(dir, tmpName);
     try {
-        writeFileSync(tmp, text, { encoding: "utf8" });
+        containedWrite({
+            root: resolve(dir),
+            target: tmpName,
+            data: text,
+            mode: "create",
+        });
         renameSync(tmp, path);
     }
     catch (err) {
@@ -21,11 +32,20 @@ export function atomicWriteText(path, text) {
         throw err;
     }
 }
-/** Append one JSON audit record (mirrors `_append_audit`). */
+/**
+ * Append one JSON audit record (mirrors `_append_audit`).
+ * #2951 Phase 2: product write sink routes through containedWrite.
+ * Create cacheRoot first — containedWrite requires the containment root to exist.
+ */
 export function appendAudit(record, cacheRoot) {
-    const path = join(cacheRoot, "quarantine-audit.jsonl");
-    mkdirSync(dirname(path), { recursive: true });
-    appendFileSync(path, `${pythonJsonLine(record)}\n`, { encoding: "utf8" });
+    const root = resolve(cacheRoot);
+    mkdirSync(root, { recursive: true });
+    containedWrite({
+        root,
+        target: "quarantine-audit.jsonl",
+        data: `${pythonJsonLine(record)}\n`,
+        mode: "append",
+    });
 }
 /** Touch mtime for LRU signal; failures swallowed. */
 export function touchMtime(path) {

package/dist/cache/scanner.d.ts

@@ -2,7 +2,7 @@
  * Quarantine scanner v2 port (mirrors `scripts/cache_scanner.py`).
  * SCANNER_VERSION must stay in lockstep with the Python module.
  */
-export declare const SCANNER_VERSION = "2.1.0";
+export declare const SCANNER_VERSION = "2.2.0";
 export interface ScanFlag {
     category: string;
     severity: string;
@@ -21,6 +21,16 @@ export interface ScanResult {
  * Scans the line once; byte-identical match semantics to the prior regex.
  */
 export declare function lineHasShellVector(line: string): boolean;
+/**
+ * Neutralize a body line so it cannot act as a CommonMark fence open/close.
+ * Used on content placed inside a ```quarantined wrapper (#2915 / cache-quarantine-03).
+ *
+ * A nested bare ``` (or longer run, optional ≤3-space indent) would otherwise
+ * early-close the outer fence and let following attacker text render outside
+ * the quarantined info-string. Break the delimiter run by inserting a backslash
+ * after the first fence character: ``` → `\`` , ~~~ → ~\~~ .
+ */
+export declare function neutralizeFenceLine(line: string): string;
 /** Run scanner v2 over content markdown. */
 export declare function scan(contentMd: string, scannedAt?: string): ScanResult;
 /** Map scan flags for meta.json (omit match_count when zero). */

package/dist/cache/scanner.js

@@ -3,9 +3,12 @@ import { parseMarkdownHeading } from "../text/redos-safe.js";
  * Quarantine scanner v2 port (mirrors `scripts/cache_scanner.py`).
  * SCANNER_VERSION must stay in lockstep with the Python module.
  */
-export const SCANNER_VERSION = "2.1.0";
+export const SCANNER_VERSION = "2.2.0";
 const CREDENTIAL_PATTERNS = [
     ["github-pat", /\bgh[pousr]_[A-Za-z0-9]{30,}\b/],
+    // #2910: fine-grained PATs (`github_pat_...`) — aligned with product-signal
+    // SECRET_PATTERNS so cache/ingest fail-closes on modern GitHub tokens.
+    ["github-fine-grained-pat", /\bgithub_pat_[A-Za-z0-9_]{20,}\b/],
     ["anthropic-api-key", /\bsk-ant-[A-Za-z0-9_-]{20,}\b/],
     ["openai-api-key", /\bsk-[A-Za-z0-9]{20,}\b/],
     ["slack-token", /\bxox[bp]-[A-Za-z0-9-]{20,}\b/],
@@ -151,6 +154,26 @@ export function lineHasShellVector(line) {
 const FENCE_RE = /^(```|~~~)/;
 const QUARANTINE_FENCE_OPEN = "```quarantined";
 const QUARANTINE_FENCE_CLOSE = "```";
+/**
+ * Neutralize a body line so it cannot act as a CommonMark fence open/close.
+ * Used on content placed inside a ```quarantined wrapper (#2915 / cache-quarantine-03).
+ *
+ * A nested bare ``` (or longer run, optional ≤3-space indent) would otherwise
+ * early-close the outer fence and let following attacker text render outside
+ * the quarantined info-string. Break the delimiter run by inserting a backslash
+ * after the first fence character: ``` → `\`` , ~~~ → ~\~~ .
+ */
+export function neutralizeFenceLine(line) {
+    const match = /^( {0,3})(`{3,}|~{3,})(.*)$/.exec(line);
+    if (match === null)
+        return line;
+    const indent = match[1] ?? "";
+    const delim = match[2] ?? "";
+    const rest = match[3] ?? "";
+    // One backslash after the first fence char breaks the delimiter run.
+    // Concat (not a template literal) so "\\" is unambiguously a single "\".
+    return indent + delim[0] + "\\" + delim.slice(1) + rest;
+}
 function isInvisible(ch) {
     const cp = ch.codePointAt(0);
     if (cp === undefined)
@@ -277,7 +300,8 @@ function detectInjectionHeading(text) {
             if (hSignal || bSignal) {
                 out.push(QUARANTINE_FENCE_OPEN);
                 for (let j = i; j < sectionEnd; j += 1) {
-                    out.push(lines[j] ?? "");
+                    // #2915: neutralize nested fence lines so they cannot early-close.
+                    out.push(neutralizeFenceLine(lines[j] ?? ""));
                 }
                 out.push(QUARANTINE_FENCE_CLOSE);
                 sectionsWrapped += 1;
@@ -292,7 +316,8 @@ function detectInjectionHeading(text) {
         }
         if (headingSignal(line) || lineHasShellVector(line)) {
             out.push(QUARANTINE_FENCE_OPEN);
-            out.push(line);
+            // #2915: neutralize in case the single line itself is fence-shaped.
+            out.push(neutralizeFenceLine(line));
             out.push(QUARANTINE_FENCE_CLOSE);
             sectionsWrapped += 1;
             i += 1;
@@ -310,7 +335,7 @@ function detectInjectionHeading(text) {
         {
             category: "injection-heading",
             severity: "fence-and-pass",
-            detail: `wrapped ${sectionsWrapped} injection-shaped section(s) in \`quarantined\` fence (v2.1.0 strict-signal policy)`,
+            detail: `wrapped ${sectionsWrapped} injection-shaped section(s) in \`quarantined\` fence (v2.2.0 strict-signal policy)`,
             match_count: sectionsWrapped,
         },
     ];

package/dist/cache/task-cache/store.js

@@ -1,6 +1,6 @@
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
-import { assertWriteTargetSafe } from "../../fs/projection-containment.js";
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { containedWrite } from "../../fs/contained-write.js";
 import { DEFAULT_TASK_CACHE_ROOT, TASK_CACHE_MANIFEST } from "./constants.js";
 function entryDir(projectRoot, cacheKey, cacheRoot = DEFAULT_TASK_CACHE_ROOT) {
     return join(resolve(projectRoot), cacheRoot, cacheKey.slice(0, 2), cacheKey);
@@ -22,12 +22,16 @@ export function writeCachedTaskRecord(projectRoot, cacheKey, record, cacheRoot =
     if (record.exitCode !== 0) {
         return;
     }
+    const root = resolve(projectRoot);
     const dir = entryDir(projectRoot, cacheKey, cacheRoot);
     const manifest = join(dir, TASK_CACHE_MANIFEST);
-    assertWriteTargetSafe(resolve(projectRoot), dir);
-    mkdirSync(dirname(manifest), { recursive: true });
-    assertWriteTargetSafe(resolve(projectRoot), manifest);
-    writeFileSync(manifest, `${JSON.stringify(record, null, 2)}\n`, "utf8");
+    // #2951 Phase 2: product write sink routes through containedWrite (mkdir + replace).
+    containedWrite({
+        root,
+        target: manifest,
+        data: `${JSON.stringify(record, null, 2)}\n`,
+        mode: "replace",
+    });
 }
 export function clearTaskCache(projectRoot, cacheRoot = DEFAULT_TASK_CACHE_ROOT) {
     const root = join(resolve(projectRoot), cacheRoot);

package/dist/capacity/backfill.js

@@ -1,9 +1,9 @@
 import { execFileSync } from "node:child_process";
-import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { referenceTypeMatches } from "@deftai/directive-types";
 import { sortedStringifyCompact } from "../codebase/json.js";
-import { assertWriteTargetSafe } from "../fs/projection-containment.js";
+import { containedWrite } from "../fs/contained-write.js";
 import { hasArtifactSuffix, resolveLifecycleFolder } from "../layout/resolve.js";
 import { classifyBucket, loadBucketMatchers, resolveCapacityAllocation, SOURCE_MATCH, } from "../policy/capacity.js";
 export const COMPLETED_FOLDER = "completed";
@@ -139,7 +139,7 @@ function inWindow(completedAt, windowDays, now) {
     return ageDays >= 0 && ageDays <= windowDays;
 }
 function writeMetadata(projectRoot, path, data, plan, metadata, options) {
-    assertWriteTargetSafe(projectRoot, path);
+    // #2980 wave D: product write sink routes through containedWrite.
     if (typeof plan.metadata !== "object" || plan.metadata === null || Array.isArray(plan.metadata)) {
         plan.metadata = metadata;
     }
@@ -152,7 +152,13 @@ function writeMetadata(projectRoot, path, data, plan, metadata, options) {
             metadata.capacityBucketSource = options.source;
         }
     }
-    writeFileSync(path, `${JSON.stringify(data, null, 2)}\n`, { encoding: "utf8" });
+    const root = resolve(projectRoot);
+    containedWrite({
+        root,
+        target: path,
+        data: `${JSON.stringify(data, null, 2)}\n`,
+        mode: "replace",
+    });
 }
 /** Backfill capacityBucket / completedAt on completed vBRIEFs. */
 export async function backfill(projectRoot, options = {}) {

package/dist/category-b-namespace/index.js

@@ -9,9 +9,10 @@
  * order-preserving (the namespaced key takes the legacy key's slot, keeping
  * artifact diffs minimal).
  */
-import { existsSync, lstatSync, readdirSync, readFileSync, writeFileSync, } from "node:fs";
+import { existsSync, lstatSync, readdirSync, readFileSync } from "node:fs";
 import { join, relative, resolve } from "node:path";
-import { assertDirectoryNotSymlink, assertWriteTargetSafe } from "../fs/projection-containment.js";
+import { containedWrite } from "../fs/contained-write.js";
+import { assertDirectoryNotSymlink } from "../fs/projection-containment.js";
 import { hasArtifactSuffix, resolveLifecycleRoot } from "../layout/resolve.js";
 import { LEGACY_PLAN_COMPLETED_NOTE_KEY, LEGACY_PLAN_POLICY_KEY, PLAN_COMPLETED_NOTE_KEY, PLAN_POLICY_KEY, } from "../policy/plan-extensions.js";
 /** The locked Category B renames (#1650): directive's own config, not xbrief data. */
@@ -141,7 +142,13 @@ export function migrateCategoryBCorpus(projectRoot) {
         }
         if (result.changed) {
             try {
-                assertWriteTargetSafe(root, file);
+                // #2980 wave D: product write sink routes through containedWrite.
+                containedWrite({
+                    root,
+                    target: file,
+                    data: `${JSON.stringify(result.doc, null, 2)}\n`,
+                    mode: "replace",
+                });
             }
             catch (err) {
                 conflicts.push({
@@ -150,7 +157,6 @@ export function migrateCategoryBCorpus(projectRoot) {
                 });
                 continue;
             }
-            writeFileSync(file, `${JSON.stringify(result.doc, null, 2)}\n`, "utf8");
             changed.push(relPath);
         }
     }

package/dist/check/gate-lists.js

@@ -19,6 +19,7 @@ export const FRAMEWORK_CHECK_GATES = [
     "verify:rule-ownership",
     "verify:biome-config",
     "verify:content-manifest",
+    "verify:license-sync",
     "verify:skill-external-fetch-gate",
     "verify:contract-drift",
     "verify:cursor-tier1",

package/dist/codebase/default-extractor.js

@@ -20,6 +20,9 @@ export const SKIP_DIRS = new Set([
     "build",
     "dist",
     "node_modules",
+    // Swarm / agent worktrees are not source modules (#2953, #1656).
+    ".deft-scratch",
+    // Legacy swarm worktree root name (pre-.deft-scratch layout).
     "swarm-worktrees",
 ]);
 export const LANGUAGE_BY_SUFFIX = {

package/dist/codebase/map.js

@@ -1,5 +1,6 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute, join, relative, resolve } from "node:path";
+import { containedWrite } from "../fs/contained-write.js";
 import { assertProjectionContained } from "../fs/projection-containment.js";
 import { resolveProjectDefinitionPath } from "../layout/resolve.js";
 import { extractCodeStructure, loadJsonFile } from "../verify-source/code-structure-validate.js";
@@ -249,8 +250,14 @@ export function writeCodebaseMap(projectRoot, options) {
         artifactPath: options.artifactPath,
     });
     const document = renderCodebaseMap(selection.artifact);
-    mkdirSync(dirname(resolvedOutput), { recursive: true });
-    writeFileSync(resolvedOutput, document, { encoding: "utf8" });
+    // #2980 wave D: product write sink routes through containedWrite.
+    const root = resolve(projectRoot);
+    containedWrite({
+        root,
+        target: resolvedOutput,
+        data: document,
+        mode: "replace",
+    });
     return resolvedOutput;
 }
 export function runCodebaseMapCli(argv) {

package/dist/content-contracts/skills/helpers.d.ts

@@ -13,6 +13,16 @@ export declare function resolveRepoPath(relPath: string): string;
 export declare function readRepoFile(relPath: string): string;
 export declare function repoFileExists(relPath: string): boolean;
 export declare function readSkill(relPath: string): string;
+/**
+ * Progressive-disclosure surface for deft-directive-swarm (#2928).
+ * Thin SKILL.md is the dispatch card; operative depth lives under references/.
+ * Content contracts assert against this ordered join so host adapters can leave
+ * the always-loaded SKILL without dropping coverage.
+ */
+export declare const SWARM_SKILL_REL = "skills/deft-directive-swarm/SKILL.md";
+/** Stable load order: core phases, then host launch adapters, then ops. */
+export declare const SWARM_REFERENCE_ORDER: readonly ["core-phase-0.md", "core-phase-1-2.md", "core-phase-3.md", "host-warp.md", "host-generic.md", "host-grok-build.md", "host-cursor.md", "host-openclaw.md", "core-phase-4.md", "core-phase-5-6.md", "core-ops.md"];
+export declare function readSwarmSkillSurface(): string;
 export declare function readAgentsMd(): string;
 /** Slice the first `## Returning Sessions` section body out of AGENTS.md. */
 export declare function returningSessionsSection(): string;

package/dist/content-contracts/skills/helpers.js

@@ -32,6 +32,41 @@ export function repoFileExists(relPath) {
 export function readSkill(relPath) {
     return readRepoFile(relPath);
 }
+/**
+ * Progressive-disclosure surface for deft-directive-swarm (#2928).
+ * Thin SKILL.md is the dispatch card; operative depth lives under references/.
+ * Content contracts assert against this ordered join so host adapters can leave
+ * the always-loaded SKILL without dropping coverage.
+ */
+export const SWARM_SKILL_REL = "skills/deft-directive-swarm/SKILL.md";
+/** Stable load order: core phases, then host launch adapters, then ops. */
+export const SWARM_REFERENCE_ORDER = [
+    "core-phase-0.md",
+    "core-phase-1-2.md",
+    "core-phase-3.md",
+    "host-warp.md",
+    "host-generic.md",
+    "host-grok-build.md",
+    "host-cursor.md",
+    "host-openclaw.md",
+    "core-phase-4.md",
+    "core-phase-5-6.md",
+    "core-ops.md",
+];
+export function readSwarmSkillSurface() {
+    const parts = [readRepoFile(SWARM_SKILL_REL)];
+    for (const name of SWARM_REFERENCE_ORDER) {
+        const rel = `skills/deft-directive-swarm/references/${name}`;
+        // Fail-loud: SWARM_REFERENCE_ORDER is the complete shipped surface (#2928).
+        // Silently skipping a missing reference lets incomplete packs pass contracts
+        // that never assert markers unique to the omitted file (Greptile on #2936).
+        if (!repoFileExists(rel)) {
+            throw new Error(`readSwarmSkillSurface: missing declared reference ${rel}`);
+        }
+        parts.push(readRepoFile(rel));
+    }
+    return parts.join("\n\n");
+}
 export function readAgentsMd() {
     return readRepoFile("AGENTS.md");
 }

package/dist/deposit/copy-tree.d.ts

@@ -5,12 +5,30 @@
  * directories are created mode 0o755; files keep their source permission bits
  * (including the executable bit for hooks and the `run` launcher).
  *
- * Refs #1942 S1, #1477.
+ * `replaceTree` is the npm-path counterpart of Go `swapInCore` (#2913): full
+ * destination replace so dst-only agent content cannot survive a refresh.
+ *
+ * Refs #1942 S1, #1477, #2913.
  */
 /**
  * Recursively copy `src` into `dst`, preserving nested structure and file modes.
  *
  * The contents of `src` are placed under `dst` (equivalent to Go `copyDir`).
+ * This is **additive** — pre-existing destination entries not present in `src`
+ * survive. Prefer {@link replaceTree} for deposit refresh integrity (#2913).
  */
 export declare function copyTree(src: string, dst: string): Promise<void>;
+/**
+ * Full-tree replace of `dst` with the contents of `src` (Go `swapInCore` parity).
+ *
+ * Stages the new tree out-of-line, moves any existing `dst` aside, then moves
+ * the staged tree into place. On failure after the old tree was moved, restores
+ * the previous payload. Destination-only files (stale or malicious) do **not**
+ * survive — unlike additive {@link copyTree}.
+ *
+ * Refuses to operate when `dst` itself is a symlink (#2305 / #2912).
+ *
+ * Refs #2913, #2904 (install-deposit-06).
+ */
+export declare function replaceTree(src: string, dst: string): Promise<void>;
 //# sourceMappingURL=copy-tree.d.ts.map

package/dist/deposit/copy-tree.js

@@ -5,22 +5,27 @@
  * directories are created mode 0o755; files keep their source permission bits
  * (including the executable bit for hooks and the `run` launcher).
  *
- * Refs #1942 S1, #1477.
+ * `replaceTree` is the npm-path counterpart of Go `swapInCore` (#2913): full
+ * destination replace so dst-only agent content cannot survive a refresh.
+ *
+ * Refs #1942 S1, #1477, #2913.
  */
 import { constants } from "node:fs";
-import { lstat, mkdir, open, readdir, readFile, stat } from "node:fs/promises";
+import { lstat, mkdir, mkdtemp, open, readdir, readFile, rename, rm, stat } from "node:fs/promises";
+import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 const DEFAULT_FILE_MODE = 0o644;
 const DEFAULT_DIR_MODE = 0o755;
-async function assertDestinationIsNotSymlink(path) {
+async function assertDestinationIsNotSymlink(path, label = "copyTree") {
     try {
         const info = await lstat(path);
         if (info.isSymbolicLink()) {
-            throw new Error(`copyTree: refusing to write through destination symlink ${path}`);
+            throw new Error(`${label}: refusing to write through destination symlink ${path}`);
         }
     }
     catch (err) {
-        if (err instanceof Error && err.message.startsWith("copyTree: refusing")) {
+        if (err instanceof Error &&
+            err.message.includes("refusing to write through destination symlink")) {
             throw err;
         }
         if (err.code === "ENOENT") {
@@ -77,6 +82,8 @@ async function copyDirContents(src, dst) {
  * Recursively copy `src` into `dst`, preserving nested structure and file modes.
  *
  * The contents of `src` are placed under `dst` (equivalent to Go `copyDir`).
+ * This is **additive** — pre-existing destination entries not present in `src`
+ * survive. Prefer {@link replaceTree} for deposit refresh integrity (#2913).
  */
 export async function copyTree(src, dst) {
     const srcInfo = await stat(src);
@@ -85,4 +92,126 @@ export async function copyTree(src, dst) {
     }
     await copyDirContents(src, dst);
 }
+async function pathExists(path) {
+    try {
+        await lstat(path);
+        return true;
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return false;
+        throw err;
+    }
+}
+/**
+ * Move `src` to `dst`, falling back to copy+remove across devices (EXDEV),
+ * mirroring Go `movePayload` used by `swapInCore`.
+ */
+async function moveTree(src, dst) {
+    await mkdir(dirname(dst), { recursive: true, mode: DEFAULT_DIR_MODE });
+    try {
+        await rename(src, dst);
+        return;
+    }
+    catch (err) {
+        const code = err.code;
+        if (code !== "EXDEV" && code !== "EPERM") {
+            // On some platforms rename across volumes raises EXDEV; fall through only
+            // for cross-device / permission cases that still allow a copy fallback.
+            if (code !== "EINVAL")
+                throw err;
+        }
+    }
+    await copyDirContents(src, dst);
+    await rm(src, { recursive: true, force: true });
+}
+/**
+ * Full-tree replace of `dst` with the contents of `src` (Go `swapInCore` parity).
+ *
+ * Stages the new tree out-of-line, moves any existing `dst` aside, then moves
+ * the staged tree into place. On failure after the old tree was moved, restores
+ * the previous payload. Destination-only files (stale or malicious) do **not**
+ * survive — unlike additive {@link copyTree}.
+ *
+ * Refuses to operate when `dst` itself is a symlink (#2305 / #2912).
+ *
+ * Refs #2913, #2904 (install-deposit-06).
+ */
+export async function replaceTree(src, dst) {
+    const srcInfo = await stat(src);
+    if (!srcInfo.isDirectory()) {
+        throw new Error(`replaceTree: source ${src} is not a directory`);
+    }
+    await assertDestinationIsNotSymlink(dst, "replaceTree");
+    const parent = dirname(dst);
+    await mkdir(parent, { recursive: true, mode: DEFAULT_DIR_MODE });
+    const staging = await mkdtemp(join(tmpdir(), "deft-core-stage-"));
+    let backup = null;
+    /** When true, leave `backup` on disk so an operator can recover after dual failure. */
+    let preserveBackupOnExit = false;
+    try {
+        await copyDirContents(src, staging);
+        if (await pathExists(dst)) {
+            backup = await mkdtemp(join(tmpdir(), "deft-core-bak-"));
+            // mkdtemp created an empty dir; remove it so moveTree can rename onto the path.
+            await rm(backup, { recursive: true, force: true });
+            try {
+                await moveTree(dst, backup);
+            }
+            catch (asideErr) {
+                // Greptile P1: moveTree may fall back to copy+remove. If removal fails after a
+                // successful copy (or after a partial delete of dst), `backup` is the only full
+                // recovery copy while dst may already be damaged. Do NOT let `finally` delete it.
+                if (await pathExists(backup)) {
+                    preserveBackupOnExit = true;
+                }
+                else {
+                    backup = null;
+                }
+                const asideMsg = asideErr instanceof Error ? asideErr.message : String(asideErr);
+                throw new Error(`replaceTree: failed to move existing destination aside (${asideMsg})` +
+                    (backup ? ` — recovery copy at ${backup}` : ""));
+            }
+        }
+        try {
+            await moveTree(staging, dst);
+        }
+        catch (err) {
+            if (backup !== null) {
+                try {
+                    if (await pathExists(dst)) {
+                        await rm(dst, { recursive: true, force: true });
+                    }
+                    await moveTree(backup, dst);
+                    backup = null;
+                }
+                catch (restoreErr) {
+                    preserveBackupOnExit = true;
+                    const installMsg = err instanceof Error ? err.message : String(err);
+                    const restoreMsg = restoreErr instanceof Error ? restoreErr.message : String(restoreErr);
+                    throw new Error(`replaceTree: install new payload failed (${installMsg}); ROLLBACK ALSO FAILED (${restoreMsg})` +
+                        (backup ? ` — previous payload preserved at ${backup}` : ""));
+                }
+            }
+            throw err instanceof Error
+                ? err
+                : new Error(`replaceTree: install new payload failed: ${String(err)}`);
+        }
+        // Successful install — best-effort drop the backup (Go keeps it for operator
+        // rollback; the npm path does not surface a backup path today and must not
+        // litter TEMP). Cleanup MUST NOT fail the replace: the new payload is already
+        // live at `dst`. A thrown rm here would reject replaceTree and skip the
+        // VERSION stamp in runRefreshDeposit → version drift (Greptile P1).
+        if (backup !== null) {
+            await rm(backup, { recursive: true, force: true }).catch(() => undefined);
+            backup = null;
+        }
+    }
+    finally {
+        await rm(staging, { recursive: true, force: true }).catch(() => undefined);
+        if (backup !== null && !preserveBackupOnExit) {
+            await rm(backup, { recursive: true, force: true }).catch(() => undefined);
+        }
+    }
+}
 //# sourceMappingURL=copy-tree.js.map