@deftai/directive 0.66.2 → 0.68.0

package/dist/dispatch.js

@@ -3,8 +3,9 @@
  * Routes to ported command modules in packages/cli and packages/core.
  */
 import { spawnSync } from "node:child_process";
-import { existsSync, mkdirSync, readdirSync, readFileSync, readSync, statSync, writeFileSync, } from "node:fs";
-import { homedir } from "node:os";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, readSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { homedir, tmpdir } from "node:os";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { engineInfo } from "@deftai/directive-core";
 import { parseInitArgv, runInitDepositCli, userConfigDir, } from "@deftai/directive-core/init-deposit";
@@ -50,6 +51,7 @@ export const CLI_MODULE_VERBS = [
     "pr-monitor",
     "pr-protected-issues",
     "pr-wait-mergeable",
+    "pr-watch",
     "preflight-cache",
     "preflight-gh",
     "probe-session",
@@ -85,12 +87,14 @@ export const CLI_MODULE_VERBS = [
     "vbrief-validation",
     "verify-branch",
     "verify-encoding",
+    "verify-forward-coverage",
     "verify-hooks-installed",
     "verify-investigation",
     "verify-judgment-gates",
     "verify-no-task-runtime",
     "validate-links",
     "validate-strategy-output",
+    "verify-biome-config",
     "verify-bridge-drift",
     "verify-capacity",
     "verify-content-manifest",
@@ -105,6 +109,8 @@ export const CLI_MODULE_VERBS = [
     "verify-story-ready",
     "verify-tools",
     "verify-wip-cap",
+    "verify-agents-md-budget",
+    "verify-agents-md-advisory",
 ];
 /** Core-only CLI entrypoints without a packages/cli wrapper. */
 export const CORE_MODULE_VERBS = [
@@ -116,6 +122,7 @@ export const CORE_MODULE_VERBS = [
     "reconcile-issues",
     "swarm-launch",
     "swarm-complete-cohort",
+    "swarm-finalize-cohort",
     "swarm-readiness",
     "swarm-routing-verify",
     "swarm-routing-set",
@@ -159,9 +166,12 @@ const TRIAGE_ACTION_COLON_ALIASES = Object.fromEntries(Object.keys(TRIAGE_ACTION
 /** Task-style aliases (framework_commands / Taskfile names). */
 export const VERB_ALIASES = {
     "verify:encoding": "verify-encoding",
+    "verify:forward-coverage": "verify-forward-coverage",
     "verify:branch": "verify-branch",
     "verify:vbrief-conformance": "vbrief-validate",
     "verify:wip-cap": "verify-wip-cap",
+    "verify:agents-md-budget": "verify-agents-md-budget",
+    "verify:agents-md-advisory": "verify-agents-md-advisory",
     "verify:hooks-installed": "verify-hooks-installed",
     "verify:no-task-runtime": "verify-no-task-runtime",
     "vbrief:validate": "vbrief-validate",
@@ -176,6 +186,7 @@ export const VERB_ALIASES = {
     "validate:links": "validate-links",
     "verify:rule-ownership": "rule-ownership-lint",
     "rule:ownership-lint": "rule-ownership-lint",
+    "verify:biome-config": "verify-biome-config",
     "verify:content-manifest": "verify-content-manifest",
     "verify:contract-drift": "verify-contract-drift",
     "verify:cursor-tier1": "verify-cursor-tier1",
@@ -218,6 +229,7 @@ export const VERB_ALIASES = {
 const SUBDIR_CLI_STEMS = {
     "verify-stubs": "verify-source-cli/verify-stubs",
     "rule-ownership-lint": "verify-source-cli/rule-ownership-lint",
+    "verify-biome-config": "verify-source-cli/verify-biome-config",
     "verify-content-manifest": "verify-source-cli/verify-content-manifest",
     "verify-contract-drift": "verify-source-cli/verify-contract-drift",
     "verify-cursor-tier1": "verify-source-cli/verify-cursor-tier1",
@@ -711,40 +723,115 @@ function extractExtraFrontmatter(frontmatter) {
         extra.pop();
     return extra.length ? extra.join("\n") : null;
 }
-const ROUTING_HEADING = "## Skill Routing";
-const ROUTING_PATH_RE = /`(?:content\/)?(skills\/[^`]+\/SKILL\.md)`/;
-const ARROW_SPLIT_RE = /\u2192|->/;
-function parseRouting(agentsMd) {
+// Skill trigger keywords are sourced from durable, post-#838 surfaces rather
+// than the removed AGENTS.md "## Skill Routing" table (#838 / #2152). Priority:
+//   1. each SKILL.md frontmatter `triggers:` list (the skill's own contract);
+//   2. the REFERENCES.md "Skills Index" table (the #838 single source of truth).
+// This decouples the skills pack from AGENTS.md, so adding a skill no longer
+// requires editing the always-loaded policy file and the trigger map stays
+// non-empty after #838 removed the heading parseRouting used to read.
+const SKILLS_INDEX_HEADING_RE = /Skills Index/i;
+const HEADING_LINE_RE = /^#{1,6}\s/;
+const SKILL_LINK_RE = /\(([^)]*skills\/[^)]+\/SKILL\.md)\)/;
+const BACKTICK_TOKEN_RE = /`([^`]+)`/g;
+/** Normalize a REFERENCES.md skill link path to the `skills/<name>/SKILL.md` key. */
+function normalizeSkillIndexPath(linkPath) {
+    let p = linkPath.trim();
+    if (p.startsWith("./"))
+        p = p.slice(2);
+    const marker = p.indexOf("skills/");
+    return marker >= 0 ? p.slice(marker) : p;
+}
+/**
+ * Parse the REFERENCES.md "Skills Index" table into a `skills/<name>/SKILL.md`
+ * -> triggers map. Skill rows are identified by their SKILL.md link (so the
+ * header and separator rows are skipped); the trigger cell is the last
+ * pipe-delimited column and its keywords are the backtick-quoted tokens.
+ */
+function parseSkillsIndexTriggers(referencesMd) {
     const mapping = new Map();
-    const start = agentsMd.indexOf(ROUTING_HEADING);
-    if (start === -1)
-        return mapping;
-    const rest = agentsMd.slice(start + ROUTING_HEADING.length);
-    const end = rest.indexOf("\n## ");
-    const section = end !== -1 ? rest.slice(0, end) : rest;
-    for (const raw of splitLines(section)) {
+    let inSection = false;
+    for (const raw of splitLines(referencesMd)) {
         const line = raw.trim();
-        if (!line.startsWith("- "))
+        if (HEADING_LINE_RE.test(line)) {
+            inSection = SKILLS_INDEX_HEADING_RE.test(line);
             continue;
-        const pathMatch = ROUTING_PATH_RE.exec(line);
-        if (!pathMatch)
-            continue;
-        const path = pathMatch[1] ?? "";
-        const head = line.split(ARROW_SPLIT_RE)[0] ?? "";
-        const keywords = (head.match(/"[^"]+"/g) ?? []).map((quoted) => quoted.slice(1, -1));
-        let bucket = mapping.get(path);
-        if (!bucket) {
-            bucket = [];
-            mapping.set(path, bucket);
         }
-        for (const keyword of keywords) {
-            if (!bucket.includes(keyword))
+        if (!inSection || !line.startsWith("|"))
+            continue;
+        const linkMatch = SKILL_LINK_RE.exec(line);
+        if (!linkMatch)
+            continue;
+        const path = normalizeSkillIndexPath(linkMatch[1] ?? "");
+        const cells = line
+            .split("|")
+            .map((cell) => cell.trim())
+            .filter((cell) => cell.length > 0);
+        const triggerCell = cells[cells.length - 1] ?? "";
+        const bucket = mapping.get(path) ?? [];
+        for (const match of triggerCell.matchAll(BACKTICK_TOKEN_RE)) {
+            const keyword = (match[1] ?? "").trim();
+            if (keyword && !bucket.includes(keyword))
                 bucket.push(keyword);
         }
+        if (bucket.length > 0)
+            mapping.set(path, bucket);
     }
     return mapping;
 }
-function buildSkillEntry(skillMd, skillsDir, routing, captureBody) {
+// Split on quoted phrases (single or double) or bare comma-delimited runs, so a
+// quoted trigger containing a comma (`["what's next, please", other]`) is not
+// mis-tokenised. All shipped skills use the block-list form today; this keeps
+// the inline flow-list form correct for future skills.
+const FLOW_LIST_TOKEN_RE = /(?:"([^"]*)")|(?:'([^']*)')|([^,]+)/g;
+/** Split an inline YAML flow list (`[a, "b"]`) into trimmed, unquoted tokens. */
+function parseFlowListTokens(value) {
+    const inner = value.replace(/^\[/, "").replace(/\]$/, "");
+    const out = [];
+    for (const match of inner.matchAll(FLOW_LIST_TOKEN_RE)) {
+        const token = (match[1] ?? match[2] ?? match[3] ?? "").trim();
+        if (token)
+            out.push(token);
+    }
+    return out;
+}
+/** Extract a `triggers:` list (block or inline flow form) from SKILL.md frontmatter. */
+function parseFrontmatterTriggers(frontmatter) {
+    const lines = frontmatter.split("\n");
+    const n = lines.length;
+    for (let i = 0; i < n; i += 1) {
+        const line = lineAt(lines, i);
+        if (isIndented(line))
+            continue;
+        const match = KEY_RE.exec(line);
+        if (!match || (match[1] ?? "") !== "triggers")
+            continue;
+        const value = (match[2] ?? "").trim();
+        if (value.startsWith("["))
+            return parseFlowListTokens(value);
+        const out = [];
+        let j = i + 1;
+        while (j < n) {
+            const nxt = lineAt(lines, j);
+            if (nxt.trim() === "") {
+                j += 1;
+                continue;
+            }
+            if (!isIndented(nxt))
+                break;
+            const item = nxt.trim();
+            if (item.startsWith("- ")) {
+                const token = pyStrip(pyStrip(item.slice(2).trim(), '"'), "'");
+                if (token)
+                    out.push(token);
+            }
+            j += 1;
+        }
+        return out;
+    }
+    return [];
+}
+function buildSkillEntry(skillMd, skillsDir, indexTriggers, captureBody) {
     const text = readFileSync(skillMd, "utf8");
     const [frontmatter, body] = splitFrontmatter(text);
     if (frontmatter === null)
@@ -754,7 +841,11 @@ function buildSkillEntry(skillMd, skillsDir, routing, captureBody) {
     if (!name)
         return null;
     const relPath = relPosix(dirname(resolve(skillsDir)), resolve(skillMd));
-    const triggers = routing.get(relPath) ?? [];
+    // Prefer the skill's own frontmatter `triggers:` contract; fall back to the
+    // REFERENCES.md Skills Index (#838 single source of truth) so shipped skills
+    // that carry no frontmatter triggers still get a non-empty trigger list.
+    const frontmatterTriggers = parseFrontmatterTriggers(frontmatter);
+    const triggers = frontmatterTriggers.length > 0 ? frontmatterTriggers : (indexTriggers.get(relPath) ?? []);
     const version = (fields.version ?? "").trim() || DEFAULT_SKILL_VERSION;
     return {
         id: name,
@@ -766,22 +857,22 @@ function buildSkillEntry(skillMd, skillsDir, routing, captureBody) {
         frontmatter_extra: extractExtraFrontmatter(frontmatter),
     };
 }
-function buildSkillsPack(skillsDir, agentsMd, proofSkill) {
-    const routing = parseRouting(readFileSync(agentsMd, "utf8"));
+function buildSkillsPack(skillsDir, referencesMd, proofSkill) {
+    const indexTriggers = parseSkillsIndexTriggers(readFileSync(referencesMd, "utf8"));
     const captureAll = proofSkill === null;
     const proofPath = proofSkill !== null ? `skills/${proofSkill}/SKILL.md` : null;
     const base = dirname(resolve(skillsDir));
     const skills = [];
     for (const skillMd of globSkillMd(skillsDir)) {
         const relPath = relPosix(base, resolve(skillMd));
-        const entry = buildSkillEntry(skillMd, skillsDir, routing, captureAll || relPath === proofPath);
+        const entry = buildSkillEntry(skillMd, skillsDir, indexTriggers, captureAll || relPath === proofPath);
         if (entry !== null)
             skills.push(entry);
     }
     return {
         pack: "skills-pack-0.1",
         version: PACK_VERSION,
-        generated_from: "skills/*/SKILL.md + AGENTS.md (Skill Routing)",
+        generated_from: "skills/*/SKILL.md frontmatter triggers + REFERENCES.md (Skills Index)",
         skills,
     };
 }
@@ -988,24 +1079,24 @@ function parsePackArgs(argv, valueFlags, listFlags = []) {
 }
 function runPackMigrateSkills(argv, io) {
     const contentRoot = resolveContentRoot();
-    const parsed = parsePackArgs(argv, ["--skills-dir", "--agents-md", "--proof-skill", "--out"]);
+    const parsed = parsePackArgs(argv, ["--skills-dir", "--references-md", "--proof-skill", "--out"]);
     if (parsed.error !== undefined) {
         io.writeErr(`error: ${parsed.error}\n`);
         return 2;
     }
     const skillsDir = parsed.values["--skills-dir"] ?? join(contentRoot, "skills");
-    const agentsMd = parsed.values["--agents-md"] ?? join(resolveDeftRoot(), "AGENTS.md");
+    const referencesMd = parsed.values["--references-md"] ?? join(resolveDeftRoot(), "REFERENCES.md");
     const proofSkill = parsed.values["--proof-skill"] ?? null;
     const out = parsed.values["--out"] ?? join(contentRoot, "packs", "skills", "skills-pack-0.1.json");
     if (!isDirSafe(skillsDir)) {
         io.writeErr(`error: skills directory not found: ${skillsDir}\n`);
         return 1;
     }
-    if (!isFileSafe(agentsMd)) {
-        io.writeErr(`error: AGENTS.md not found: ${agentsMd}\n`);
+    if (!isFileSafe(referencesMd)) {
+        io.writeErr(`error: REFERENCES.md not found: ${referencesMd}\n`);
         return 1;
     }
-    const pack = buildSkillsPack(skillsDir, agentsMd, proofSkill);
+    const pack = buildSkillsPack(skillsDir, referencesMd, proofSkill);
     if (pack.skills.length === 0) {
         io.writeErr(`error: no skills with frontmatter discovered under ${skillsDir}\n`);
         return 1;
@@ -1116,15 +1207,81 @@ function runPackMigrateSwarmSpec(argv, io) {
     return 0;
 }
 // ===========================================================================
-// Native setup:ghx handler (#2022 Phase 1).
+// Native setup:ghx handler (#2022 Phase 1; #2178 download-verify-execute).
 //
 // Port of scripts/setup_ghx.py to native TypeScript: consent-gated ghx proxy
 // installer with three-state exit (0 ok / 1 install failure / 2 config error).
+//
+// #2178: the installer no longer pipes remote bytes straight into a shell
+// (`curl | bash` / `irm | iex`). Socket Security's AI-malware heuristic flags
+// exactly that live-pipe-with-no-integrity-check pattern and blocks every
+// consumer PR that bumps @deftai/directive (Socket scored the package ~65%
+// likely malicious, severity 0.78 -- seen on deftai/evolution#1046 / #1047).
+// Instead: download the installer script to memory, verify it against a
+// SHA-256 vendored below, write it to a private local temp file, and only
+// then execute that local file directly. The fetch URL also pins to the
+// immutable commit SHA that GHX_VERSION resolved to at vendor time (not the
+// mutable tag name), so a future tag force-move on the upstream repo cannot
+// swap the fetched bytes out from under the vendored hash without also
+// failing the hash check.
+//
+// Bumping GHX_VERSION (`.github/workflows/ci.yml` env.GHX_VERSION MUST stay
+// in lockstep):
+//   1. Resolve the new tag's commit SHA:
+//        gh api repos/brunoborges/ghx/git/refs/tags/<new-version>
+//      Use `object.sha`. If `object.type` is "tag" (an annotated tag, not a
+//      lightweight one), resolve one level further:
+//        gh api repos/brunoborges/ghx/git/tags/<object.sha>
+//      and use THAT response's `object.sha` (the commit, not the tag object).
+//   2. Refetch both installers at the resolved commit and recompute hashes:
+//        curl -fsSL https://raw.githubusercontent.com/brunoborges/ghx/<sha>/install.sh  | sha256sum
+//        curl -fsSL https://raw.githubusercontent.com/brunoborges/ghx/<sha>/install.ps1 | sha256sum
+//   3. Update GHX_VERSION, GHX_COMMIT_SHA, GHX_INSTALL_SH_SHA256, and
+//      GHX_INSTALL_PS1_SHA256 below IN THE SAME COMMIT as the matching
+//      `.github/workflows/ci.yml` env values -- never let the two drift.
 // ===========================================================================
-/** Pinned ghx version — keep in lockstep with .github/workflows/ci.yml env.GHX_VERSION. */
+/** Pinned ghx version (display only) — keep in lockstep with .github/workflows/ci.yml env.GHX_VERSION. */
 export const GHX_VERSION = "v1.5.1";
-export const INSTALL_PS1_URL = `https://raw.githubusercontent.com/brunoborges/ghx/${GHX_VERSION}/install.ps1`;
-export const INSTALL_SH_URL = `https://raw.githubusercontent.com/brunoborges/ghx/${GHX_VERSION}/install.sh`;
+/**
+ * Immutable commit SHA the GHX_VERSION tag resolved to at vendor time
+ * (2026-07-02, via `gh api repos/brunoborges/ghx/git/refs/tags/v1.5.1`).
+ * Fetch URLs pin to this SHA rather than the mutable tag name so a future
+ * tag force-move on brunoborges/ghx cannot silently swap the fetched bytes
+ * out from under the vendored SHA-256 hashes below (#2178).
+ */
+export const GHX_COMMIT_SHA = "aa4a2786660e27392b0d3e8886f140e0a0261a0c";
+export const INSTALL_PS1_URL = `https://raw.githubusercontent.com/brunoborges/ghx/${GHX_COMMIT_SHA}/install.ps1`;
+export const INSTALL_SH_URL = `https://raw.githubusercontent.com/brunoborges/ghx/${GHX_COMMIT_SHA}/install.sh`;
+/**
+ * SHA-256 of the installer scripts at GHX_COMMIT_SHA, vendored so the
+ * download-verify-execute pipeline below can refuse to run tampered bytes.
+ * Matches `.github/workflows/ci.yml` env.GHX_INSTALL_SH_SHA256 /
+ * GHX_INSTALL_PS1_SHA256 (#1070 / #1328) — keep both in lockstep (#2178).
+ */
+export const GHX_INSTALL_SH_SHA256 = "08c768feb6d2bc485079898f7e76c2b07576cbb1188a356acf99dac0fc55d1cb";
+export const GHX_INSTALL_PS1_SHA256 = "5f67eab68970ecc55bb0fc1b8399ba6f3ce4b2aadeee39255d628e96d187a5ed";
+async function defaultGhxDownload(url) {
+    const res = await fetch(url);
+    if (!res.ok) {
+        throw new Error(`download failed: HTTP ${res.status} ${res.statusText} for ${url}`);
+    }
+    return Buffer.from(await res.arrayBuffer());
+}
+/** True when `buf`'s SHA-256 (hex) matches `expectedHex`, case- and whitespace-insensitive. */
+export function verifyGhxSha256(buf, expectedHex) {
+    const actual = createHash("sha256").update(buf).digest("hex");
+    return actual.toLowerCase() === expectedHex.trim().toLowerCase();
+}
+export function resolveGhxInstallerAsset(host) {
+    if (host === "windows") {
+        return { url: INSTALL_PS1_URL, sha256: GHX_INSTALL_PS1_SHA256, fileExt: "ps1" };
+    }
+    if (host === "darwin" || host === "linux") {
+        return { url: INSTALL_SH_URL, sha256: GHX_INSTALL_SH_SHA256, fileExt: "sh" };
+    }
+    throw new Error(`no upstream ghx installer available for host '${host}'; ` +
+        "see https://github.com/brunoborges/ghx#install for manual options");
+}
 function parseSetupGhxArgs(argv) {
     let yes = false;
     let check = false;
@@ -1174,34 +1331,97 @@ export function promptSetupGhxConsent(io, readLine = readConsentLineFromStdin) {
     const answer = readLine().trim().toLowerCase();
     return answer === "y" || answer === "yes";
 }
-export function buildSetupGhxInstallCommand(host, whichFn = defaultWhich) {
-    if (host === "windows") {
-        const psBin = whichFn("pwsh") ?? whichFn("powershell") ?? "powershell";
-        return [
-            psBin,
+function ghxTempFileName(fileExt) {
+    return `ghx-install-${GHX_VERSION}.${fileExt}`;
+}
+/**
+ * Downloads `asset`, verifies it against its vendored SHA-256, and writes it
+ * to a private local temp file. Returns the local path, ready for direct
+ * local-file execution (never piped into a shell). Throws -- without
+ * writing or executing anything -- on a hash mismatch (#2178). Split out
+ * from `fetchAndVerifyGhxInstaller` so tests can exercise the download ->
+ * verify -> write pipeline against a synthetic asset/hash without depending
+ * on the real vendored constants or the network.
+ */
+export async function fetchAndVerifyGhxInstallerAsset(asset, downloadFn = defaultGhxDownload) {
+    const bytes = await downloadFn(asset.url);
+    if (!verifyGhxSha256(bytes, asset.sha256)) {
+        const actual = createHash("sha256").update(bytes).digest("hex");
+        throw new Error(`ghx installer SHA-256 mismatch for ${asset.url} ` +
+            `(expected ${asset.sha256}, got ${actual}); refusing to execute. ` +
+            "The pinned commit's bytes may have changed, or the download was tampered with.");
+    }
+    const dir = mkdtempSync(join(tmpdir(), "deft-ghx-"));
+    const installerPath = join(dir, ghxTempFileName(asset.fileExt));
+    writeFileSync(installerPath, bytes, { mode: 0o700 });
+    return installerPath;
+}
+/**
+ * Downloads the pinned installer for `host`, verifies it against the
+ * vendored SHA-256, and writes it to a private local temp file. Returns the
+ * local path, ready for direct local-file execution (never piped into a
+ * shell). Throws -- without writing or executing anything -- on a hash
+ * mismatch (#2178).
+ */
+export async function fetchAndVerifyGhxInstaller(host, downloadFn = defaultGhxDownload) {
+    return fetchAndVerifyGhxInstallerAsset(resolveGhxInstallerAsset(host), downloadFn);
+}
+/**
+ * Executes an already-downloaded, hash-verified installer from its local
+ * temp path. No live pipe (`curl | bash` / `irm | iex`) and no
+ * `-ExecutionPolicy Bypass` -- the file is written by Node, so it never
+ * carries a Windows Mark-of-the-Web zone identifier the way a browser or
+ * `Invoke-WebRequest` download would; `RemoteSigned` treats it as a local,
+ * unsigned-but-trusted script (#2178).
+ */
+export function executeVerifiedGhxInstaller(host, installerPath, whichFn = defaultWhich, runner = spawnSync) {
+    const cmd = host === "windows"
+        ? [
+            whichFn("pwsh") ?? whichFn("powershell") ?? "powershell",
             "-NoProfile",
             "-ExecutionPolicy",
-            "Bypass",
-            "-Command",
-            `irm ${INSTALL_PS1_URL} | iex`,
-        ];
-    }
-    if (host === "darwin" || host === "linux") {
-        return ["bash", "-c", `curl -fsSL ${INSTALL_SH_URL} | bash`];
-    }
-    throw new Error(`no upstream ghx installer available for host '${host}'; ` +
-        "see https://github.com/brunoborges/ghx#install for manual options");
-}
-export function installSetupGhx(host, whichFn = defaultWhich, runner = spawnSync) {
-    const cmd = buildSetupGhxInstallCommand(host, whichFn);
+            "RemoteSigned",
+            "-File",
+            installerPath,
+        ]
+        : ["bash", installerPath];
     const proc = runner(cmd[0] ?? "", cmd.slice(1), {
         env: { ...process.env, GHX_VERSION },
         stdio: "inherit",
     });
     return proc.status ?? 1;
 }
+/**
+ * Downloads, hash-verifies, and executes `asset` for `host`. Cleans up the
+ * temp file (and its containing directory) regardless of outcome. Split out
+ * from `installSetupGhx` so tests can exercise the full download -> verify
+ * -> execute -> cleanup pipeline against a synthetic asset without depending
+ * on the real vendored constants or the network (#2178).
+ */
+export async function installVerifiedGhxAsset(asset, host, whichFn = defaultWhich, runner = spawnSync, downloadFn = defaultGhxDownload) {
+    const installerPath = await fetchAndVerifyGhxInstallerAsset(asset, downloadFn);
+    try {
+        return executeVerifiedGhxInstaller(host, installerPath, whichFn, runner);
+    }
+    finally {
+        try {
+            rmSync(dirname(installerPath), { recursive: true, force: true });
+        }
+        catch {
+            // Best-effort cleanup; a leftover temp file is not fatal.
+        }
+    }
+}
+/**
+ * Downloads, hash-verifies, and executes the ghx installer for `host`.
+ * Cleans up the temp file (and its containing directory) regardless of
+ * outcome (#2178).
+ */
+export async function installSetupGhx(host, whichFn = defaultWhich, runner = spawnSync, downloadFn = defaultGhxDownload) {
+    return installVerifiedGhxAsset(resolveGhxInstallerAsset(host), host, whichFn, runner, downloadFn);
+}
 /** Native `setup:ghx` handler (replaces scripts/setup_ghx.py shell-out, #2022 Phase 1). */
-export function runSetupGhx(argv, io, deps = {}) {
+export async function runSetupGhx(argv, io, deps = {}) {
     const args = parseSetupGhxArgs(argv);
     if (args.error !== undefined) {
         io.writeErr(`setup-ghx: ${args.error}\n`);
@@ -1248,9 +1468,10 @@ export function runSetupGhx(argv, io, deps = {}) {
         return 0;
     }
     const host = detectSetupGhxHost();
-    const runInstall = deps.runInstall ?? ((h) => installSetupGhx(h, whichFn));
+    const runInstall = deps.runInstall ??
+        ((h) => installSetupGhx(h, whichFn, deps.runner, deps.downloadFn));
     try {
-        const rc = runInstall(host);
+        const rc = await runInstall(host);
         if (rc !== 0) {
             io.writeErr(`[setup_ghx] error: upstream installer exited ${rc}. ` +
                 "See https://github.com/brunoborges/ghx#install for manual options.\n");
@@ -1943,6 +2164,10 @@ async function loadCoreModuleHandler(verb, io) {
             const { completeCohortMain } = await import("@deftai/directive-core/dist/swarm/complete-cohort-cli.js");
             return completeCohortMain;
         }
+        case "swarm-finalize-cohort": {
+            const { finalizeCohortMain } = await import("@deftai/directive-core/dist/swarm/finalize-cohort-cli.js");
+            return finalizeCohortMain;
+        }
         case "swarm-readiness": {
             const { readinessMain } = await import("@deftai/directive-core/dist/swarm/readiness-cli.js");
             return readinessMain;

package/dist/doctor.js

@@ -5,7 +5,7 @@ import { fileURLToPath } from "node:url";
 import { parseDoctorFlags } from "@deftai/directive-core/dist/doctor/flags.js";
 import { cmdDoctor } from "@deftai/directive-core/dist/doctor/main.js";
 import { renderPrecutoverLine } from "@deftai/directive-core/dist/vbrief-validate/precutover.js";
-import { renderXbriefMigrationLine } from "@deftai/directive-core/xbrief-migrate";
+import { renderStaleHeaderLine, renderXbriefMigrationLine, } from "@deftai/directive-core/xbrief-migrate";
 /** Advisory when a consumer deposit carries git-vendored framework source (#2142). */
 export function renderStrayPackagesAdvisoryLine(projectRoot) {
     const packagesDir = join(projectRoot, ".deft", "core", "packages");
@@ -26,6 +26,7 @@ export function run(argv) {
         const projectRoot = flags.projectRoot ?? process.cwd();
         process.stdout.write(`${renderPrecutoverLine(projectRoot)}\n`);
         process.stdout.write(`${renderXbriefMigrationLine(projectRoot)}\n`);
+        process.stdout.write(`${renderStaleHeaderLine(projectRoot)}\n`);
         process.stdout.write(`${renderStrayPackagesAdvisoryLine(projectRoot)}\n`);
     }
     return cmdDoctor(argv);

package/dist/install-upgrade.d.ts

@@ -1,11 +1,41 @@
 #!/usr/bin/env node
-export interface ParsedInstallUpgradeArgs {
-    projectRoot: string;
-    frameworkRoot: string;
-    migrate: boolean;
-    force: boolean;
-    error?: string;
+import type { DispatchIo } from "./dispatch.js";
+/**
+ * #2064: `deft install-upgrade` is now a thin redirect onto the SAME code path
+ * as `directive update` (`runRefreshDeposit`). The two verbs previously had
+ * overlapping-but-divergent semantics: `directive update` file-swaps the
+ * vendored `.deft/core` payload, rewrites the install manifest (#2056), and
+ * regenerates the `.deft-version` marker (#2055), whereas the old
+ * `install-upgrade` only wrote the marker/manifest and refreshed AGENTS.md
+ * WITHOUT swapping the payload -- so on a stale deposit it reported a confident
+ * false no-op ("Project already at X. Nothing to do.") that steered operators
+ * away from the command that actually works. Consolidating to one path removes
+ * that hazard and gives consumers a single upgrade mental model:
+ *   npm i -g @deftai/directive@latest -> deft update -> deft migrate -> deft doctor
+ *
+ * The legacy `.deft/VERSION` cleanup that only `install-upgrade` used to perform
+ * is folded into the shared `runRefreshDeposit` path (see
+ * `migrateLegacyInstallManifest` in init-deposit/refresh.ts) so no manifest
+ * behavior is dropped. Layout migration (the old `--migrate` flag) is the
+ * separate `deft migrate` step in the canonical flow above.
+ */
+/** One-line notice emitted on the redirect so operators learn the canonical verb. */
+export declare const REDIRECT_NOTICE: string;
+export interface InstallUpgradeDeps {
+    /** Injectable seam so tests can drive the shared update path with fixtures. */
+    readonly runUpdate?: (argv: readonly string[], io: DispatchIo) => Promise<number>;
 }
-export declare function parseArgs(argv: readonly string[]): ParsedInstallUpgradeArgs;
-export declare function run(argv: readonly string[]): number;
+/**
+ * Translate the historical `install-upgrade` flag surface onto the
+ * `directive update` argv. `--project-root <p>` maps to `--repo-root <p>`;
+ * `--framework-root` is dropped (update resolves its own content root) and the
+ * legacy `--migrate` / `--force` flags are dropped (layout migration is now the
+ * separate `deft migrate` step). Any other argv passes through unchanged.
+ */
+export declare function translateArgs(argv: readonly string[]): string[];
+/**
+ * Redirect handler: emit the one-line notice, then delegate to the identical
+ * code path `directive update` uses so deposit state + stdout are identical.
+ */
+export declare function run(argv: readonly string[], io?: DispatchIo, deps?: InstallUpgradeDeps): Promise<number>;
 //# sourceMappingURL=install-upgrade.d.ts.map