@deftai/directive 0.94.0 → 0.95.0

package/dist/authz.d.ts

@@ -1,4 +1,32 @@
 #!/usr/bin/env node
-export declare function main(argv?: string[]): number;
+/**
+ * Env markers that indicate an agent/host/CI shell even when stdin reports a TTY
+ * (pseudo-terminal residual; #3110 Greptile). Presence refuses mutating authz.
+ * Expanded for dogfood conf 5/5 — markers are fail-closed (any non-empty value).
+ */
+export declare const AUTHZ_AGENT_SHELL_ENV_MARKERS: readonly ["CLAUDECODE", "CLAUDE_CODE", "CLAUDE_CODE_ENTRYPOINT", "CURSOR_AGENT", "CURSOR_TRACE_ID", "CURSOR_SESSION_ID", "AIDER", "CONTINUE_CLI", "CODEX_SANDBOX", "CODEX_CI", "OPENAI_CODEX", "OPENCLAW", "OPENCLAW_STATE_DIR", "DEFT_PROBE_OPENCLAW", "DEFT_HOOK_HOST", "DEFT_AGENT_SHELL", "DEFT_AGENT_RUNTIME", "WARP_SESSION_ID", "WARP_HARNESS", "WARP_RUN_ID", "GEMINI_CLI", "AMP_CLI", "SWARM_AGENT", "AI_AGENT", "CI", "CONTINUOUS_INTEGRATION", "GITHUB_ACTIONS", "GITLAB_CI", "CIRCLECI", "BUILDKITE", "TRAVIS", "JENKINS_URL", "TEAMCITY_VERSION", "TF_BUILD", "APPVEYOR", "BITBUCKET_BUILD_NUMBER", "CODEBUILD_BUILD_ID"];
+/** Phrase an operator must type on the controlling TTY after --confirm (#3110). */
+export declare const AUTHZ_INTERACTIVE_CONFIRM_PHRASE = "mint";
+/** Testable seams for TTY / agent-shell detection (#3110). */
+export interface AuthzMainSeams {
+    /**
+     * When true, interactive human TTY is present.
+     * Default: both stdin and stdout report isTTY (pseudo-TTY residual; #3110).
+     */
+    readonly isTty?: () => boolean;
+    /** Environ for agent-shell marker detection (default: process.env). */
+    readonly environ?: NodeJS.ProcessEnv;
+    /**
+     * True when a controlling terminal device is available (`/dev/tty` or `CONIN$`).
+     * Default: open/close the platform controlling terminal (fail-closed on error).
+     */
+    readonly hasControllingTerminal?: () => boolean;
+    /**
+     * Read one interactive confirmation line from the operator (trimmed).
+     * Default: one line from stdin. Tests inject a fixed phrase.
+     */
+    readonly readInteractiveConfirm?: () => string | null;
+}
+export declare function main(argv?: string[], seams?: AuthzMainSeams): number;
 export default main;
 //# sourceMappingURL=authz.d.ts.map

package/dist/authz.js

@@ -1,17 +1,75 @@
 #!/usr/bin/env node
 /**
- * Authz CLI (#2944 Wave 1 + #1095 Wave 4): human-origin grants + UAT lease +
+ * Authz CLI (#2944 Wave 1 + #1095 Wave 4 + #3110): human-origin grants + UAT lease +
  * AFK closed-verb templates (mint via mintHumanOriginGrant only).
  *
  *   deft authz:show
- *   deft authz:uat-start -- --campaign <id> [--actor <name>] [--note <text>]
- *   deft authz:uat-suspend
- *   deft authz:grant -- --operations edit,push --surfaces 'src/**' --cohort <id> ...
- *   deft authz:grant -- --template release-publish --target 0.30.0
- *   deft authz:grant -- --template finish-loop
- *   deft authz:revoke -- <grant-id>
+ *   deft authz:uat-start -- --campaign <id> [--actor <name>] [--note <text>] [--confirm]
+ *   deft authz:uat-suspend [--confirm]
+ *   deft authz:grant -- --operations edit,push --surfaces 'src/**' --cohort <id> ... [--confirm]
+ *   deft authz:grant -- --template release-publish --target 0.30.0 [--confirm]
+ *   deft authz:grant -- --template finish-loop [--confirm]
+ *   deft authz:revoke -- <grant-id> [--confirm]
+ *
+ * **UAT-active hard refuse (#3110):** while any UAT lease is active, ALL mutating
+ * verbs (`uat-start`, `uat-suspend`, `grant`, `revoke`) refuse unconditionally —
+ * no TTY, no `--confirm`, no typed phrase path. Self-approval under UAT is
+ * impossible by construction (agent PTY cannot mint operator-cli authority).
+ *
+ * **Outside UAT:** mutating verbs require multi-factor human presence: interactive
+ * TTY + controlling terminal + `--confirm` + typed phrase `mint`; agent/CI env
+ * markers refuse fail-closed. Argv `--confirm` alone is never enough.
+ */
+import { closeSync, openSync, readSync } from "node:fs";
+import { AFK_TEMPLATE_NAMES, AUTHZ_OPERATIONS, CLOSED_VERB_TEMPLATE_NAMES, FINISH_LOOP_TEMPLATE_NAME, isAfkTemplateName, isClosedVerbTemplateName, isFinishLoopTemplateName, loadAuthzState, mintAfkTemplateGrant, mintHumanOriginGrant, revokeGrant, showAuthzSnapshot, startUatLease, suspendUatLease, } from "@deftai/directive-core/authz";
+/**
+ * Env markers that indicate an agent/host/CI shell even when stdin reports a TTY
+ * (pseudo-terminal residual; #3110 Greptile). Presence refuses mutating authz.
+ * Expanded for dogfood conf 5/5 — markers are fail-closed (any non-empty value).
  */
-import { AFK_TEMPLATE_NAMES, AUTHZ_OPERATIONS, CLOSED_VERB_TEMPLATE_NAMES, FINISH_LOOP_TEMPLATE_NAME, isAfkTemplateName, isClosedVerbTemplateName, isFinishLoopTemplateName, mintAfkTemplateGrant, mintHumanOriginGrant, revokeGrant, showAuthzSnapshot, startUatLease, suspendUatLease, } from "@deftai/directive-core/authz";
+export const AUTHZ_AGENT_SHELL_ENV_MARKERS = [
+    // Coding agents / IDEs
+    "CLAUDECODE",
+    "CLAUDE_CODE",
+    "CLAUDE_CODE_ENTRYPOINT",
+    "CURSOR_AGENT",
+    "CURSOR_TRACE_ID",
+    "CURSOR_SESSION_ID",
+    "AIDER",
+    "CONTINUE_CLI",
+    "CODEX_SANDBOX",
+    "CODEX_CI",
+    "OPENAI_CODEX",
+    "OPENCLAW",
+    "OPENCLAW_STATE_DIR",
+    "DEFT_PROBE_OPENCLAW",
+    "DEFT_HOOK_HOST",
+    "DEFT_AGENT_SHELL",
+    "DEFT_AGENT_RUNTIME",
+    "WARP_SESSION_ID",
+    "WARP_HARNESS",
+    "WARP_RUN_ID",
+    "GEMINI_CLI",
+    "AMP_CLI",
+    "SWARM_AGENT",
+    "AI_AGENT",
+    // CI / automation (never a human interactive operator mint)
+    "CI",
+    "CONTINUOUS_INTEGRATION",
+    "GITHUB_ACTIONS",
+    "GITLAB_CI",
+    "CIRCLECI",
+    "BUILDKITE",
+    "TRAVIS",
+    "JENKINS_URL",
+    "TEAMCITY_VERSION",
+    "TF_BUILD",
+    "APPVEYOR",
+    "BITBUCKET_BUILD_NUMBER",
+    "CODEBUILD_BUILD_ID",
+];
+/** Phrase an operator must type on the controlling TTY after --confirm (#3110). */
+export const AUTHZ_INTERACTIVE_CONFIRM_PHRASE = "mint";
 function parseOps(raw) {
     const allowed = new Set(AUTHZ_OPERATIONS);
     const out = [];
@@ -47,6 +105,7 @@ function parseArgv(argv) {
         template: null,
         target: null,
         format: "text",
+        confirm: false,
     };
     const args = [...argv];
     // Drop leading `--` separators from task-style invocation.
@@ -165,6 +224,10 @@ function parseArgv(argv) {
             base.target = args[++i] ?? null;
             continue;
         }
+        if (a === "--confirm") {
+            base.confirm = true;
+            continue;
+        }
         if (!a.startsWith("-") && base.cmd === "revoke" && base.grantId === null) {
             base.grantId = a;
             continue;
@@ -179,16 +242,26 @@ function helpText() {
     return [
         "Usage:",
         "  deft authz:show [--format json]",
-        "  deft authz:uat-start -- --campaign <id> [--actor <name>] [--note <text>]",
-        "  deft authz:uat-suspend",
+        "  deft authz:uat-start -- --campaign <id> [--actor <name>] [--note <text>] [--confirm]",
+        "  deft authz:uat-suspend [--confirm]",
         "  deft authz:grant -- --operations edit,push --surfaces 'src/**' --cohort <id> \\",
-        "      [--stories 2944] [--plan-ref <id>] [--repo owner/name] [--branch <b>] [--expires ISO]",
-        "  deft authz:grant -- --template release-publish --target 0.30.0 [--actor <name>] [--expires ISO]",
-        "  deft authz:grant -- --template finish-loop [--actor <name>] [--expires ISO]",
-        "  deft authz:revoke -- <grant-id>",
+        "      [--stories 2944] [--plan-ref <id>] [--repo owner/name] [--branch <b>] [--expires ISO] [--confirm]",
+        "  deft authz:grant -- --template release-publish --target 0.30.0 [--actor <name>] [--expires ISO] [--confirm]",
+        "  deft authz:grant -- --template finish-loop [--actor <name>] [--expires ISO] [--confirm]",
+        "  deft authz:revoke -- <grant-id> [--confirm]",
         "",
         "Human-origin grants are minted only via this CLI (origin.kind=operator-cli).",
         "Self-authored xBRIEF/lifecycle/dispatch tokens never satisfy implement gates (#2944).",
+        "While any UAT lease is ACTIVE (#3110): ALL mutating verbs refuse unconditionally",
+        "  (grant / uat-start / uat-suspend / revoke) — no TTY, --confirm, or phrase path.",
+        "  Self-approval under UAT is impossible by construction. Mint grants BEFORE uat-start.",
+        "Outside UAT, mutating verbs require multi-factor human presence (#3110):",
+        "  - Interactive TTY (stdin+stdout) + controlling terminal (/dev/tty|CONIN$)",
+        "  - Explicit --confirm (argv flag alone never enough)",
+        "  - Typed phrase 'mint' on the controlling TTY (PTY+--confirm alone never enough)",
+        "  - Known agent/CI env markers always refuse (fail-closed).",
+        "  End UAT only after the lease is cleared out-of-band (state edit / suspend path",
+        "  that does not run while the lease is active) — or suspend before re-minting.",
         "",
         `AFK templates (#1095 / #871): ${AFK_TEMPLATE_NAMES.join(", ")}`,
         `  Closed-verb (#1095): ${CLOSED_VERB_TEMPLATE_NAMES.join(", ")} — require --target`,
@@ -197,7 +270,131 @@ function helpText() {
         "  Env bypass for a single shell: DEFT_ALLOW_RELEASE_PUBLISH=1 / DEFT_ALLOW_FINISH_LOOP=1.",
     ].join("\n");
 }
-export function main(argv = process.argv.slice(2)) {
+function looksLikeAgentShell(environ) {
+    for (const key of AUTHZ_AGENT_SHELL_ENV_MARKERS) {
+        const v = environ[key];
+        if (v !== undefined && String(v).trim().length > 0)
+            return true;
+    }
+    return false;
+}
+function defaultHasControllingTerminal() {
+    try {
+        const path = process.platform === "win32" ? "CONIN$" : "/dev/tty";
+        const fd = openSync(path, "r");
+        closeSync(fd);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function defaultReadInteractiveConfirm() {
+    // Read from the controlling terminal device — not redirected/piped stdin —
+    // so agent-controlled stdin alone cannot supply the confirm phrase (#3110).
+    let fd = null;
+    try {
+        const path = process.platform === "win32" ? "CONIN$" : "/dev/tty";
+        fd = openSync(path, "r");
+        const buf = Buffer.alloc(256);
+        const n = readSync(fd, buf, 0, buf.length, null);
+        if (n <= 0)
+            return null;
+        return buf.subarray(0, n).toString("utf8").trim();
+    }
+    catch {
+        return null;
+    }
+    finally {
+        if (fd !== null) {
+            try {
+                closeSync(fd);
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    }
+}
+/**
+ * While any UAT lease is active, refuse ALL mutating authz CLI verbs (#3110).
+ *
+ * No multi-factor escape: TTY, `--confirm`, and typed phrase never authorize.
+ * Self-approval under UAT is impossible by construction — agents with a PTY
+ * cannot mint/suspend/revoke operator-cli authority during an active lease.
+ * Operators mint fix-cohort grants *before* `uat-start`.
+ *
+ * Returns exit code when blocked, or null when the command may continue.
+ */
+function refuseMutatingAuthzWhileUatActive(projectRoot, cmd) {
+    if (cmd === "show")
+        return null;
+    const state = loadAuthzState(projectRoot);
+    if (state.uat === null || !state.uat.active)
+        return null;
+    process.stderr.write(`authz:${cmd}: refusing mutating authz while UAT lease is ACTIVE ` +
+        `(campaign=${state.uat.campaignId}). Under active UAT, grant / uat-start / ` +
+        "uat-suspend / revoke are hard-refused — no TTY, --confirm, or phrase path " +
+        "authorizes self-approval (#3110). Mint grants before uat-start; clear the " +
+        "lease out-of-band (edit .deft/authz/state.json as a human outside agent hooks) " +
+        "to end UAT.\n");
+    return 2;
+}
+/**
+ * Refuse non-interactive / agent-shell operator-cli stamps outside UAT (#3110).
+ *
+ * Multi-factor human-presence gate (applies only when UAT lease is inactive):
+ * 1. No known agent/CI env markers
+ * 2. Interactive TTY (stdin + stdout isTTY)
+ * 3. Controlling terminal device present (`/dev/tty` / `CONIN$`)
+ * 4. Explicit argv `--confirm` (flag alone never enough)
+ * 5. Interactive typed phrase `mint` (argv --confirm alone never enough even on PTY)
+ *
+ * Fail-closed: if a real human interactive path cannot be proven, refuse mint.
+ * Returns an exit code when blocked, or null when the mutation may proceed.
+ */
+function refuseNonInteractiveMint(cmd, isTty, environ, confirm, hasControllingTerminal, readInteractiveConfirm) {
+    if (cmd === "show")
+        return null;
+    if (looksLikeAgentShell(environ)) {
+        process.stderr.write(`authz:${cmd}: refusing operator-cli stamp from an agent/host/CI shell ` +
+            `(detected agent or CI env marker). Mutating authz requires a human interactive ` +
+            "TTY without agent-shell markers, plus --confirm and typed phrase (#3110).\n");
+        return 2;
+    }
+    const tty = isTty();
+    if (!tty && !confirm) {
+        process.stderr.write(`authz:${cmd}: refusing non-interactive operator-cli stamp. ` +
+            "Mutating authz verbs require interactive TTY, --confirm, and typed phrase " +
+            `'${AUTHZ_INTERACTIVE_CONFIRM_PHRASE}' (#3110).\n`);
+        return 2;
+    }
+    if (!tty) {
+        process.stderr.write(`authz:${cmd}: refusing non-TTY operator-cli stamp. ` +
+            "--confirm alone never authorizes mint — interactive TTY is required (#3110).\n");
+        return 2;
+    }
+    if (!confirm) {
+        process.stderr.write(`authz:${cmd}: refusing operator-cli stamp without --confirm. ` +
+            "Interactive TTY alone never authorizes mint — pass --confirm explicitly (#3110).\n");
+        return 2;
+    }
+    if (!hasControllingTerminal()) {
+        process.stderr.write(`authz:${cmd}: refusing operator-cli stamp without a controlling terminal. ` +
+            "Open a real interactive console (not a headless/agent pipe) to mint (#3110).\n");
+        return 2;
+    }
+    process.stderr.write(`authz:${cmd}: type '${AUTHZ_INTERACTIVE_CONFIRM_PHRASE}' and press Enter to confirm operator mint: `);
+    const line = readInteractiveConfirm();
+    const phrase = (line ?? "").trim().toLowerCase();
+    if (phrase !== AUTHZ_INTERACTIVE_CONFIRM_PHRASE) {
+        process.stderr.write(`\nauthz:${cmd}: interactive confirm phrase mismatch (got ${JSON.stringify(line ?? "")}). ` +
+            `Type exactly '${AUTHZ_INTERACTIVE_CONFIRM_PHRASE}' on the controlling TTY (#3110).\n`);
+        return 2;
+    }
+    return null;
+}
+export function main(argv = process.argv.slice(2), seams = {}) {
     const args = parseArgv(argv);
     if (args.error === "help") {
         process.stdout.write(`${helpText()}\n`);
@@ -208,6 +405,23 @@ export function main(argv = process.argv.slice(2)) {
         process.stderr.write(`${helpText()}\n`);
         return 2;
     }
+    // Both stdin and stdout TTY — agent-allocated single-side PTY is not enough.
+    const isTty = seams.isTty ?? (() => process.stdin.isTTY === true && process.stdout.isTTY === true);
+    const environ = seams.environ ?? process.env;
+    const hasControllingTerminal = seams.hasControllingTerminal ?? defaultHasControllingTerminal;
+    const readInteractiveConfirm = seams.readInteractiveConfirm ?? defaultReadInteractiveConfirm;
+    /**
+     * Mutating-verb gate stack (#3110):
+     * 1. Active UAT → hard refuse (no multi-factor escape; self-approval impossible)
+     * 2. Else multi-factor: TTY + controlling tty + --confirm + typed phrase; agent/CI markers refuse
+     * Required-arg validation runs before this so missing --campaign / --ops still report clearly.
+     */
+    const gateConfirm = () => {
+        const uatBlocked = refuseMutatingAuthzWhileUatActive(args.projectRoot, args.cmd);
+        if (uatBlocked !== null)
+            return uatBlocked;
+        return refuseNonInteractiveMint(args.cmd, isTty, environ, args.confirm, hasControllingTerminal, readInteractiveConfirm);
+    };
     try {
         switch (args.cmd) {
             case "show": {
@@ -242,6 +456,9 @@ export function main(argv = process.argv.slice(2)) {
                     process.stderr.write("authz:uat-start requires --campaign <id>\n");
                     return 2;
                 }
+                const blocked = gateConfirm();
+                if (blocked !== null)
+                    return blocked;
                 const { lease } = startUatLease({
                     projectRoot: args.projectRoot,
                     campaignId: args.campaign,
@@ -254,6 +471,9 @@ export function main(argv = process.argv.slice(2)) {
                 return 0;
             }
             case "uat-suspend": {
+                const blocked = gateConfirm();
+                if (blocked !== null)
+                    return blocked;
                 const state = suspendUatLease({
                     projectRoot: args.projectRoot,
                     actor: args.actor,
@@ -278,6 +498,9 @@ export function main(argv = process.argv.slice(2)) {
                         process.stderr.write(`authz:grant --template ${args.template} requires --target <version>\n`);
                         return 2;
                     }
+                    const blocked = gateConfirm();
+                    if (blocked !== null)
+                        return blocked;
                     const grant = mintAfkTemplateGrant({
                         projectRoot: args.projectRoot,
                         template: args.template,
@@ -309,6 +532,11 @@ export function main(argv = process.argv.slice(2)) {
                     process.stderr.write("authz:grant requires --operations <edit,push,...> or --template <finish-loop|release-*> \n");
                     return 2;
                 }
+                {
+                    const blocked = gateConfirm();
+                    if (blocked !== null)
+                        return blocked;
+                }
                 const grant = mintHumanOriginGrant({
                     projectRoot: args.projectRoot,
                     actor: args.actor,
@@ -335,6 +563,11 @@ export function main(argv = process.argv.slice(2)) {
                     process.stderr.write("authz:revoke requires <grant-id>\n");
                     return 2;
                 }
+                {
+                    const blocked = gateConfirm();
+                    if (blocked !== null)
+                        return blocked;
+                }
                 const revoked = revokeGrant({
                     projectRoot: args.projectRoot,
                     grantId: args.grantId,

package/dist/dispatch.d.ts

@@ -12,7 +12,7 @@ export interface DispatchIo {
 /** 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", "hook-dispatch", "umbrella-current-shape", "changelog-check", "change-init", "commit-lint", "coverage-hotspots", "policy", "authz", "escalation-cli", "pr-closing-keywords", "pr-merge-readiness", "pr-monitor", "pr-protected-issues", "pr-wait-mergeable", "pr-watch", "pr-finish-loop", "directive-finish-loop", "preflight-cache", "preflight-gh", "probe-session", "release", "release-e2e", "release-publish", "release-rollback", "scope-lifecycle", "lifecycle-event", "lifecycle-stats", "session-start", "session-ready", "plan-sequence", "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", "xbrief-create", "xbrief-verify", "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-contained-writes", "verify-content-manifest", "verify-skill-external-fetch-gate", "verify-contract-drift", "verify-cursor-tier1", "verify-openclaw-tier1", "verify-go-freeze", "verify-scm-boundary", "verify-session-ritual", "verify-plan-sequence", "verify-stubs", "verify-xbrief-drift", "rule-ownership-lint", "verify-story-ready", "verify-review-monitor", "verify-l4-owner", "verify-subagent-alive", "review-monitor-register", "review-monitor-release", "verify-tools", "verify-wip-cap", "verify-orphan-active", "verify-agents-md-budget", "verify-agents-md-advisory", "verify-eval-health-relocation", "verify-eval-triggers-relocation", "eval-health", "eval-run", "eval-report", "eval-triggers"];
 /** Core-only CLI entrypoints without a packages/cli wrapper. */
-export declare const CORE_MODULE_VERBS: readonly ["scm", "scm-readiness", "github-auth-modes", "github-body", "issue-emit", "issue-ingest", "issue-sync-from-xbrief", "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", "rule-map", "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", "feedback-file", "value-readback", "product-signal"];
+export declare const CORE_MODULE_VERBS: readonly ["scm", "scm-readiness", "github-auth-modes", "github-body", "issue-emit", "issue-ingest", "issue-sync-from-xbrief", "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", "rule-map", "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", "feedback-file", "value-readback", "product-signal", "freshness-report"];
 /** Colon aliases for triage-actions (mirrors cli-router SUBCOMMAND_ROUTES). */
 export declare const TRIAGE_ACTION_ALIAS_SUBCOMMANDS: Readonly<Record<string, string>>;
 /** Colon aliases for policy subcommands (mirrors cli-router SUBCOMMAND_ROUTES). */
@@ -25,6 +25,8 @@ export declare const ESCALATION_ACTION_ALIAS_SUBCOMMANDS: Readonly<Record<string
 export declare const PLAN_SEQUENCE_ALIAS_SUBCOMMANDS: Readonly<Record<string, string>>;
 /** Colon aliases for product-signal subcommands (#2693). */
 export declare const PRODUCT_SIGNAL_ALIAS_SUBCOMMANDS: Readonly<Record<string, string>>;
+/** Colon aliases for freshness subcommands (#3117). */
+export declare const FRESHNESS_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 (display only) — keep in lockstep with .github/workflows/ci.yml env.GHX_VERSION. */

package/dist/dispatch.js

@@ -186,6 +186,7 @@ export const CORE_MODULE_VERBS = [
     "feedback-file",
     "value-readback",
     "product-signal",
+    "freshness-report",
 ];
 /** Colon aliases for triage-actions (mirrors cli-router SUBCOMMAND_ROUTES). */
 export const TRIAGE_ACTION_ALIAS_SUBCOMMANDS = {
@@ -245,6 +246,14 @@ export const PRODUCT_SIGNAL_ALIAS_SUBCOMMANDS = {
     "product-signal:bootstrap-sink": "bootstrap-sink",
 };
 const PRODUCT_SIGNAL_COLON_ALIASES = Object.fromEntries(Object.keys(PRODUCT_SIGNAL_ALIAS_SUBCOMMANDS).map((alias) => [alias, "product-signal"]));
+/** Colon aliases for freshness subcommands (#3117). */
+export const FRESHNESS_ALIAS_SUBCOMMANDS = {
+    "freshness:report": "report",
+    "freshness:bind": "bind",
+    "session:freshness": "report",
+    freshness: "report",
+};
+const FRESHNESS_COLON_ALIASES = Object.fromEntries(Object.keys(FRESHNESS_ALIAS_SUBCOMMANDS).map((alias) => [alias, "freshness-report"]));
 /** Task-style aliases (framework_commands / Taskfile names). */
 export const VERB_ALIASES = {
     "hook:dispatch": "hook-dispatch",
@@ -321,6 +330,7 @@ export const VERB_ALIASES = {
     upgrade: "install-upgrade",
     "session:start": "session-start",
     "session:ready": "session-ready",
+    ...FRESHNESS_COLON_ALIASES,
     "lifecycle:event": "lifecycle-event",
     "lifecycle:stats": "lifecycle-stats",
     "toolchain:check": "toolchain-check",
@@ -2445,6 +2455,10 @@ async function loadCoreModuleHandler(verb, io) {
             const { mainEntry } = await import("@deftai/directive-core/dist/product-signal/submit.js");
             return mainEntry;
         }
+        case "freshness-report": {
+            const { mainEntry } = await import("@deftai/directive-core/dist/freshness/cli.js");
+            return mainEntry;
+        }
         default:
             throw new Error(`unknown core verb: ${verb}`);
     }
@@ -2547,6 +2561,14 @@ const CURATED_HELP_GROUPS = [
                 name: "session:ready",
                 summary: "One-shot recovery to gated write-ready (session + ritual + cache)",
             },
+            {
+                name: "freshness:report",
+                summary: "Bound vs live deposit generation (current|stale_soft|stale_hard)",
+            },
+            {
+                name: "freshness:bind",
+                summary: "Bind live deposit generation into this session (no host restart)",
+            },
             {
                 name: "scm:status",
                 summary: "Probe gh/ghx + auth readiness in this execution env (#2275)",
@@ -2683,6 +2705,7 @@ export async function dispatch(argv, io = defaultIo()) {
         const escalationSubcommand = verb !== undefined ? ESCALATION_ACTION_ALIAS_SUBCOMMANDS[verb] : undefined;
         const planSequenceSubcommand = verb !== undefined ? PLAN_SEQUENCE_ALIAS_SUBCOMMANDS[verb] : undefined;
         const productSignalSubcommand = verb !== undefined ? PRODUCT_SIGNAL_ALIAS_SUBCOMMANDS[verb] : undefined;
+        const freshnessSubcommand = verb !== undefined ? FRESHNESS_ALIAS_SUBCOMMANDS[verb] : undefined;
         const handlerArgv = canonical === "framework-commands" && verb !== undefined && verb !== canonical
             ? [verb, ...rest]
             : triageSubcommand !== undefined && canonical === "triage-actions"
@@ -2697,7 +2720,9 @@ export async function dispatch(argv, io = defaultIo()) {
                                 ? [planSequenceSubcommand, ...rest]
                                 : productSignalSubcommand !== undefined && canonical === "product-signal"
                                     ? [productSignalSubcommand, ...rest]
-                                    : rest;
+                                    : freshnessSubcommand !== undefined && canonical === "freshness-report"
+                                        ? [freshnessSubcommand, ...rest]
+                                        : rest;
         return await invokeHandler(handler, handlerArgv);
     }
     catch (err) {

package/dist/triage-classify.d.ts

@@ -1,13 +1,22 @@
 #!/usr/bin/env node
-interface ParsedArgs {
+import type { LabelClient } from "@deftai/directive-core/dist/vbrief-reconcile/types.js";
+export interface ParsedArgs {
     projectRoot: string;
     doList: boolean;
     doValidate: boolean;
+    doMirror: boolean;
+    apply: boolean;
+    json: boolean;
+    repo: string | null;
+    allowCrossRepo: boolean;
     error?: string;
 }
-/** Parse triage-classify CLI args, mirroring the Python argparse surface. */
+/** Parse triage-classify CLI args (#1129 + #1423 Wave 1 mirror flags). */
 export declare function parseArgs(argv: string[]): ParsedArgs;
+export interface RunOptions {
+    /** Injected LabelClient for tests (apply path). */
+    readonly labelClient?: LabelClient;
+}
 /** Run the CLI and return the process exit code. */
-export declare function run(argv: string[]): number;
-export {};
+export declare function run(argv: string[], options?: RunOptions): number;
 //# sourceMappingURL=triage-classify.d.ts.map

package/dist/triage-classify.js

@@ -2,13 +2,18 @@
 import { statSync } from "node:fs";
 import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { listProject, validateProject } from "@deftai/directive-core/dist/triage/classify/index.js";
-/** Parse triage-classify CLI args, mirroring the Python argparse surface. */
+import { labelMirrorOutcomeToJson, listProject, mirrorLabels, renderLabelMirrorReport, validateProject, } from "@deftai/directive-core/dist/triage/classify/index.js";
+/** Parse triage-classify CLI args (#1129 + #1423 Wave 1 mirror flags). */
 export function parseArgs(argv) {
     const parsed = {
         projectRoot: ".",
         doList: false,
         doValidate: false,
+        doMirror: false,
+        apply: false,
+        json: false,
+        repo: null,
+        allowCrossRepo: false,
     };
     for (let i = 0; i < argv.length; i += 1) {
         const arg = argv[i];
@@ -18,6 +23,29 @@ export function parseArgs(argv) {
         else if (arg === "--validate") {
             parsed.doValidate = true;
         }
+        else if (arg === "--mirror") {
+            parsed.doMirror = true;
+        }
+        else if (arg === "--apply") {
+            parsed.apply = true;
+        }
+        else if (arg === "--json") {
+            parsed.json = true;
+        }
+        else if (arg === "--allow-cross-repo") {
+            parsed.allowCrossRepo = true;
+        }
+        else if (arg === "--repo") {
+            const value = argv[i + 1];
+            if (value === undefined) {
+                return { ...parsed, error: "argument --repo: expected one argument" };
+            }
+            parsed.repo = value;
+            i += 1;
+        }
+        else if (arg?.startsWith("--repo=")) {
+            parsed.repo = arg.slice("--repo=".length);
+        }
         else if (arg === "--project-root") {
             const value = argv[i + 1];
             if (value === undefined) {
@@ -36,10 +64,16 @@ export function parseArgs(argv) {
             return { ...parsed, error: `unrecognized arguments: ${arg}` };
         }
     }
+    if (parsed.apply && !parsed.doMirror) {
+        return {
+            ...parsed,
+            error: "--apply requires --mirror (Tier-1 label mirror, #1423)",
+        };
+    }
     return parsed;
 }
 /** Run the CLI and return the process exit code. */
-export function run(argv) {
+export function run(argv, options = {}) {
     const args = parseArgs(argv);
     if (args.error !== undefined) {
         process.stderr.write(`ERR: ${args.error}\n`);
@@ -67,6 +101,23 @@ export function run(argv) {
         }
         return result.code;
     }
+    if (args.doMirror) {
+        const mirrorOpts = {
+            dryRun: !args.apply,
+            repo: args.repo,
+            allowCrossRepo: args.allowCrossRepo,
+            ...(options.labelClient !== undefined ? { client: options.labelClient } : {}),
+        };
+        const [code, outcome] = mirrorLabels(projectRoot, mirrorOpts);
+        if (args.json) {
+            process.stdout.write(`${JSON.stringify(labelMirrorOutcomeToJson(outcome), null, 2)}\n`);
+        }
+        else {
+            process.stdout.write(renderLabelMirrorReport(outcome));
+        }
+        return code;
+    }
+    // Default / --list: print effective rules
     process.stdout.write(listProject(projectRoot));
     return 0;
 }

package/dist/verify-hooks-installed.d.ts

@@ -1,12 +1,22 @@
 #!/usr/bin/env node
+import { type AgentHookHealthResult, type AgentHookReadinessResult, type EvaluateResult } from "@deftai/directive-core/verify-env";
 type HookScope = "git" | "agent" | "all";
 interface ParsedArgs {
     projectRoot: string;
     quiet: boolean;
     scope: HookScope;
+    live: boolean;
     error?: string;
 }
+export interface VerifyHooksInstalledCliSeams {
+    readonly evaluateGit?: (projectRoot: string) => EvaluateResult;
+    readonly evaluateAgent?: (projectRoot: string) => AgentHookHealthResult;
+    readonly evaluateReadiness?: (projectRoot: string) => AgentHookReadinessResult;
+    readonly writeOut?: (text: string) => void;
+    readonly writeErr?: (text: string) => void;
+}
 export declare function parseArgs(argv: string[]): ParsedArgs;
-export declare function run(argv: string[]): number;
+/** Verify git hooks, structural agent hooks, or functional agent-hook readiness. */
+export declare function run(argv: string[], seams?: VerifyHooksInstalledCliSeams): number;
 export {};
 //# sourceMappingURL=verify-hooks-installed.d.ts.map

package/dist/verify-hooks-installed.js

@@ -1,13 +1,15 @@
 #!/usr/bin/env node
 import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { evaluate, evaluateAgentHooks } from "@deftai/directive-core/verify-env";
+import { evaluate, evaluateAgentHookReadinessSafely, evaluateAgentHooks, } from "@deftai/directive-core/verify-env";
 export function parseArgs(argv) {
-    const parsed = { projectRoot: ".", quiet: false, scope: "git" };
+    const parsed = { projectRoot: ".", quiet: false, scope: "git", live: false };
     for (let i = 0; i < argv.length; i += 1) {
         const arg = argv[i];
         if (arg === "--quiet")
             parsed.quiet = true;
+        else if (arg === "--live")
+            parsed.live = true;
         else if (arg === "--project-root") {
             const value = argv[i + 1];
             if (value === undefined) {
@@ -41,26 +43,39 @@ export function parseArgs(argv) {
             return { ...parsed, error: `unrecognized arguments: ${arg}` };
         }
     }
+    if (parsed.live && parsed.scope === "git") {
+        return { ...parsed, error: "argument --live requires --scope=agent or --scope=all" };
+    }
     return parsed;
 }
-export function run(argv) {
+/** Verify git hooks, structural agent hooks, or functional agent-hook readiness. */
+export function run(argv, seams = {}) {
     const args = parseArgs(argv);
+    const writeOut = seams.writeOut ?? ((text) => process.stdout.write(text));
+    const writeErr = seams.writeErr ?? ((text) => process.stderr.write(text));
     if (args.error !== undefined) {
-        process.stderr.write(`${args.error}\n`);
+        writeErr(`${args.error}\n`);
         return 2;
     }
     const projectRoot = resolve(args.projectRoot);
+    const evaluateGit = seams.evaluateGit ?? evaluate;
+    const evaluateAgent = seams.evaluateAgent ?? evaluateAgentHooks;
+    const evaluateReadiness = seams.evaluateReadiness
+        ? (root) => evaluateAgentHookReadinessSafely(root, seams.evaluateReadiness)
+        : evaluateAgentHookReadinessSafely;
     const results = [
-        ...(args.scope === "git" || args.scope === "all" ? [evaluate(projectRoot)] : []),
-        ...(args.scope === "agent" || args.scope === "all" ? [evaluateAgentHooks(projectRoot)] : []),
+        ...(args.scope === "git" || args.scope === "all" ? [evaluateGit(projectRoot)] : []),
+        ...(args.scope === "agent" || args.scope === "all"
+            ? [args.live ? evaluateReadiness(projectRoot) : evaluateAgent(projectRoot)]
+            : []),
     ];
     if (!args.quiet) {
         for (const result of results) {
             if (result.stream === "stdout") {
-                process.stdout.write(`${result.message}\n`);
+                writeOut(`${result.message}\n`);
             }
             else if (result.stream === "stderr") {
-                process.stderr.write(`${result.message}\n`);
+                writeErr(`${result.message}\n`);
             }
         }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deftai/directive",
-  "version": "0.94.0",
+  "version": "0.95.0",
   "description": "Directive CLI — npm install path for the Deft Directive framework.",
   "license": "MIT",
   "homepage": "https://deftai.github.io/directive/",
@@ -34,8 +34,8 @@
     "provenance": true
   },
   "dependencies": {
-    "@deftai/directive-core": "^0.94.0",
-    "@deftai/directive-content": "^0.94.0"
+    "@deftai/directive-core": "^0.95.0",
+    "@deftai/directive-content": "^0.95.0"
   },
   "scripts": {
     "build": "tsc -b"