@deftai/directive 0.66.2 → 0.68.0

package/dist/agents-refresh.js

@@ -2,10 +2,9 @@
 /**
  * agents:refresh — rewrite AGENTS.md managed section from the canonical template (#768 / #1996).
  */
-import { writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { agentsRefreshPlan } from "@deftai/directive-core/platform";
+import { applyAgentsRefresh } from "@deftai/directive-core/platform";
 export function parseAgentsRefreshArgs(argv) {
     let projectRoot = process.cwd();
     let check = false;
@@ -41,8 +40,13 @@ export function runAgentsRefresh(argv) {
         process.stderr.write(`agents:refresh: ${args.error}\n`);
         return 2;
     }
-    const plan = agentsRefreshPlan(args.projectRoot);
-    const state = String(plan.state ?? "unknown");
+    // The read->compute->write is serialized behind an advisory lock and written
+    // atomically inside applyAgentsRefresh, so concurrent refreshers cannot clobber
+    // one another's session= write or observe a partial write (#1329).
+    const { state, path, writable } = applyAgentsRefresh(args.projectRoot, {
+        check: args.check,
+        dryRun: args.dryRun,
+    });
     if (args.check) {
         if (state === "current")
             return 0;
@@ -57,17 +61,14 @@ export function runAgentsRefresh(argv) {
         process.stderr.write(`agents:refresh failed: ${state}\n`);
         return 2;
     }
-    const newContent = plan.new_content;
-    if (typeof newContent !== "string") {
+    if (!writable) {
         process.stderr.write("agents:refresh failed: plan produced no new_content\n");
         return 2;
     }
-    const path = String(plan.path ?? resolve(args.projectRoot, "AGENTS.md"));
     if (args.dryRun) {
         process.stdout.write(`[dry-run] would write ${path} (state=${state})\n`);
         return 0;
     }
-    writeFileSync(path, newContent, "utf8");
     process.stdout.write(`AGENTS.md updated (state=${state}).\n`);
     return 0;
 }

package/dist/cli-router/route-argv.js

@@ -35,6 +35,7 @@ export const PR_VERB_MAP = {
     "check-protected-issues": "pr-protected-issues",
     "check-closing-keywords": "pr-closing-keywords",
     "wait-mergeable-and-merge": "pr-wait-mergeable",
+    watch: "pr-watch",
 };
 /** verify:* aliases that map to non-verify-* handler stems. */
 export const VERIFY_VERB_MAP = {

package/dist/dispatch.d.ts

@@ -10,30 +10,97 @@ export interface DispatchIo {
     writeErr: (text: string) => void;
 }
 /** CLI modules in packages/cli/src (excluding parity harnesses and bin/index). */
-export declare const CLI_MODULE_VERBS: readonly ["agents-refresh", "cache", "check", "capacity-backfill", "capacity-show", "codebase-default-extractor", "codebase-map", "codebase-map-fresh", "codebase-projection-registry", "codebase-provider", "doctor", "install-upgrade", "install-uninstall", "migrate-preflight", "migrate-xbrief", "migrate-category-b", "framework-check-updates", "umbrella-current-shape", "changelog-check", "change-init", "commit-lint", "policy", "pr-closing-keywords", "pr-merge-readiness", "pr-monitor", "pr-protected-issues", "pr-wait-mergeable", "preflight-cache", "preflight-gh", "probe-session", "release", "release-e2e", "release-publish", "release-rollback", "scope-lifecycle", "session-start", "slice", "subagent-monitor", "toolchain-check", "triage-actions", "triage-bootstrap", "triage-bulk", "triage-classify", "triage-help", "triage-queue", "triage-reconcile", "triage-refresh", "triage-scope", "triage-scope-drift", "triage-smoketest", "triage-subscribe", "triage-summary", "triage-welcome", "ts-check-lane", "vbrief-activate", "vbrief-build", "vbrief-preflight", "vbrief-reconcile", "vbrief-validate", "vbrief-validation", "verify-branch", "verify-encoding", "verify-hooks-installed", "verify-investigation", "verify-judgment-gates", "verify-no-task-runtime", "validate-links", "validate-strategy-output", "verify-bridge-drift", "verify-capacity", "verify-content-manifest", "verify-contract-drift", "verify-cursor-tier1", "verify-go-freeze", "verify-scm-boundary", "verify-session-ritual", "verify-stubs", "verify-xbrief-drift", "rule-ownership-lint", "verify-story-ready", "verify-tools", "verify-wip-cap"];
+export declare const CLI_MODULE_VERBS: readonly ["agents-refresh", "cache", "check", "capacity-backfill", "capacity-show", "codebase-default-extractor", "codebase-map", "codebase-map-fresh", "codebase-projection-registry", "codebase-provider", "doctor", "install-upgrade", "install-uninstall", "migrate-preflight", "migrate-xbrief", "migrate-category-b", "framework-check-updates", "umbrella-current-shape", "changelog-check", "change-init", "commit-lint", "policy", "pr-closing-keywords", "pr-merge-readiness", "pr-monitor", "pr-protected-issues", "pr-wait-mergeable", "pr-watch", "preflight-cache", "preflight-gh", "probe-session", "release", "release-e2e", "release-publish", "release-rollback", "scope-lifecycle", "session-start", "slice", "subagent-monitor", "toolchain-check", "triage-actions", "triage-bootstrap", "triage-bulk", "triage-classify", "triage-help", "triage-queue", "triage-reconcile", "triage-refresh", "triage-scope", "triage-scope-drift", "triage-smoketest", "triage-subscribe", "triage-summary", "triage-welcome", "ts-check-lane", "vbrief-activate", "vbrief-build", "vbrief-preflight", "vbrief-reconcile", "vbrief-validate", "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", "verify-contract-drift", "verify-cursor-tier1", "verify-go-freeze", "verify-scm-boundary", "verify-session-ritual", "verify-stubs", "verify-xbrief-drift", "rule-ownership-lint", "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 declare const CORE_MODULE_VERBS: readonly ["scm", "github-auth-modes", "github-body", "issue-emit", "issue-ingest", "reconcile-issues", "swarm-launch", "swarm-complete-cohort", "swarm-readiness", "swarm-routing-verify", "swarm-routing-set", "swarm-verify-review-clean", "swarm-worktrees", "framework-commands", "pack-render", "packs-slice", "prd-render", "export-spec", "project-render", "roadmap-render", "spec-render", "spec-validate", "code-structure-validate", "pack-migrate-skills", "pack-migrate-rules", "pack-migrate-strategies", "pack-migrate-patterns", "pack-migrate-swarm-spec", "policy-set", "setup-ghx", "scope-undo", "scope-demote", "scope-decompose", "changelog-resolve-unreleased", "architecture-preflight-sor"];
+export declare const CORE_MODULE_VERBS: readonly ["scm", "github-auth-modes", "github-body", "issue-emit", "issue-ingest", "reconcile-issues", "swarm-launch", "swarm-complete-cohort", "swarm-finalize-cohort", "swarm-readiness", "swarm-routing-verify", "swarm-routing-set", "swarm-verify-review-clean", "swarm-worktrees", "framework-commands", "pack-render", "packs-slice", "prd-render", "export-spec", "project-render", "roadmap-render", "spec-render", "spec-validate", "code-structure-validate", "pack-migrate-skills", "pack-migrate-rules", "pack-migrate-strategies", "pack-migrate-patterns", "pack-migrate-swarm-spec", "policy-set", "setup-ghx", "scope-undo", "scope-demote", "scope-decompose", "changelog-resolve-unreleased", "architecture-preflight-sor"];
 /** Colon aliases for triage-actions (mirrors cli-router SUBCOMMAND_ROUTES). */
 export declare const TRIAGE_ACTION_ALIAS_SUBCOMMANDS: Readonly<Record<string, string>>;
 /** Task-style aliases (framework_commands / Taskfile names). */
 export declare const VERB_ALIASES: Readonly<Record<string, string>>;
-/** 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 declare const GHX_VERSION = "v1.5.1";
-export declare const INSTALL_PS1_URL = "https://raw.githubusercontent.com/brunoborges/ghx/v1.5.1/install.ps1";
-export declare const INSTALL_SH_URL = "https://raw.githubusercontent.com/brunoborges/ghx/v1.5.1/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 declare const GHX_COMMIT_SHA = "aa4a2786660e27392b0d3e8886f140e0a0261a0c";
+export declare const INSTALL_PS1_URL = "https://raw.githubusercontent.com/brunoborges/ghx/aa4a2786660e27392b0d3e8886f140e0a0261a0c/install.ps1";
+export declare const INSTALL_SH_URL = "https://raw.githubusercontent.com/brunoborges/ghx/aa4a2786660e27392b0d3e8886f140e0a0261a0c/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 declare const GHX_INSTALL_SH_SHA256 = "08c768feb6d2bc485079898f7e76c2b07576cbb1188a356acf99dac0fc55d1cb";
+export declare const GHX_INSTALL_PS1_SHA256 = "5f67eab68970ecc55bb0fc1b8399ba6f3ce4b2aadeee39255d628e96d187a5ed";
 export type SetupGhxHost = "windows" | "darwin" | "linux" | string;
+/** Downloads a URL and resolves to its raw bytes. Injectable so tests never hit the network. */
+export type GhxDownloadFn = (url: string) => Promise<Buffer>;
+/** True when `buf`'s SHA-256 (hex) matches `expectedHex`, case- and whitespace-insensitive. */
+export declare function verifyGhxSha256(buf: Buffer, expectedHex: string): boolean;
+export interface GhxInstallerAsset {
+    url: string;
+    sha256: string;
+    fileExt: "sh" | "ps1";
+}
+export declare function resolveGhxInstallerAsset(host: SetupGhxHost): GhxInstallerAsset;
 export interface SetupGhxDeps {
     whichFn?: WhichFn;
     readConsentLine?: () => string;
-    runInstall?: (host: SetupGhxHost) => number;
+    runInstall?: (host: SetupGhxHost) => number | Promise<number>;
+    downloadFn?: GhxDownloadFn;
+    runner?: typeof spawnSync;
 }
 export declare function ghxPresent(whichFn?: WhichFn): boolean;
 export declare function detectSetupGhxHost(): SetupGhxHost;
 export declare function promptSetupGhxConsent(io: DispatchIo, readLine?: () => string): boolean;
-export declare function buildSetupGhxInstallCommand(host: SetupGhxHost, whichFn?: WhichFn): string[];
-export declare function installSetupGhx(host: SetupGhxHost, whichFn?: WhichFn, runner?: typeof spawnSync): number;
+/**
+ * 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 declare function fetchAndVerifyGhxInstallerAsset(asset: GhxInstallerAsset, downloadFn?: GhxDownloadFn): Promise<string>;
+/**
+ * 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 declare function fetchAndVerifyGhxInstaller(host: SetupGhxHost, downloadFn?: GhxDownloadFn): Promise<string>;
+/**
+ * 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 declare function executeVerifiedGhxInstaller(host: SetupGhxHost, installerPath: string, whichFn?: WhichFn, runner?: typeof spawnSync): number;
+/**
+ * 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 declare function installVerifiedGhxAsset(asset: GhxInstallerAsset, host: SetupGhxHost, whichFn?: WhichFn, runner?: typeof spawnSync, downloadFn?: GhxDownloadFn): Promise<number>;
+/**
+ * Downloads, hash-verifies, and executes the ghx installer for `host`.
+ * Cleans up the temp file (and its containing directory) regardless of
+ * outcome (#2178).
+ */
+export declare function installSetupGhx(host: SetupGhxHost, whichFn?: WhichFn, runner?: typeof spawnSync, downloadFn?: GhxDownloadFn): Promise<number>;
 /** Native `setup:ghx` handler (replaces scripts/setup_ghx.py shell-out, #2022 Phase 1). */
-export declare function runSetupGhx(argv: string[], io: DispatchIo, deps?: SetupGhxDeps): number;
+export declare function runSetupGhx(argv: string[], io: DispatchIo, deps?: SetupGhxDeps): Promise<number>;
 export declare const SETUP_SKILL_REL_PATH = ".deft/core/skills/deft-directive-setup/SKILL.md";
 export type BootstrapPhaseLabel = "user" | "project" | "spec";
 export type BootstrapReEntry = "none" | "prompt" | "reconfigure" | "force";