@deftai/directive-core 0.94.0 → 0.96.0

package/dist/cache/main.js

@@ -1,5 +1,8 @@
 import { existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
+import { latestDecisions, readAuditLog } from "../triage/actions/candidates-log.js";
+import { resolveCandidatesLogPath } from "../triage/cache-path.js";
+import { archiveClosedEntries, DEFAULT_ARCHIVE_OLDER_THAN_DAYS, listArchivedEntries, restoreFromArchive, } from "./archive.js";
 import { ALLOWED_SOURCES, DEFAULT_BATCH_SIZE, DEFAULT_DELAY_MS, DEFAULT_PRUNE_OLDER_THAN_DAYS, } from "./constants.js";
 import { CacheCapBreachedError, CacheError, CacheFetchError, CacheNotFoundError, CacheValidationError, } from "./errors.js";
 import { cacheFetchAll, cacheRefreshClosed } from "./fetch.js";
@@ -8,7 +11,7 @@ import { cacheGet, cacheInvalidate, cachePrune, cachePruneToCap, cachePut } from
 import { resolveCaps } from "./quota.js";
 import { clearTaskCache } from "./task-cache/store.js";
 function usage() {
-    process.stderr.write("usage: cache [-h] {put,get,invalidate,fetch-all,prune,clear} ...\n");
+    process.stderr.write("usage: cache [-h] {put,get,invalidate,fetch-all,prune,clear,archive-closed,archive-list,restore-from-archive} ...\n");
 }
 function normaliseLabelFilter(raw) {
     if (!raw || raw.length === 0)
@@ -309,6 +312,293 @@ function cmdPrune(args) {
     process.stdout.write(`${pythonJsonPretty(payload)}\n`);
     return 0;
 }
+/**
+ * Reversible closed-entry archive (#1137). Operator-only; not TTL prune.
+ * Distinct from `cache prune` (hard-delete by expires_at).
+ */
+function cmdArchiveClosed(args) {
+    let olderThanDays = DEFAULT_ARCHIVE_OLDER_THAN_DAYS;
+    let source = "github-issue";
+    let repo;
+    let dryRun = false;
+    let json = false;
+    let terminalDecisionOnly = false;
+    let projectRoot;
+    let cacheRoot;
+    let reason;
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === "--older-than-days") {
+            olderThanDays = Number.parseInt(args[i + 1] ?? "", 10);
+            i += 1;
+        }
+        else if (arg === "--source") {
+            source = args[i + 1] ?? "github-issue";
+            i += 1;
+        }
+        else if (arg === "--repo") {
+            repo = args[i + 1];
+            i += 1;
+        }
+        else if (arg === "--dry-run") {
+            dryRun = true;
+        }
+        else if (arg === "--json") {
+            json = true;
+        }
+        else if (arg === "--terminal-decision-only") {
+            terminalDecisionOnly = true;
+        }
+        else if (arg === "--project-root") {
+            projectRoot = args[i + 1];
+            i += 1;
+        }
+        else if (arg === "--cache-root") {
+            cacheRoot = args[i + 1];
+            i += 1;
+        }
+        else if (arg === "--reason") {
+            reason = args[i + 1];
+            i += 1;
+        }
+        else if (arg === "-h" || arg === "--help") {
+            process.stdout.write("usage: cache archive-closed [--dry-run] [--older-than-days 30] [--repo OWNER/NAME]\n" +
+                "       [--source github-issue] [--json] [--terminal-decision-only]\n" +
+                "       [--project-root PATH] [--cache-root PATH] [--reason TEXT]\n" +
+                "\n" +
+                "Reversible archive of closed github-issue cache entries (not TTL cache:prune).\n" +
+                "Skips issues still referenced by xbrief/{proposed,pending,active}.\n" +
+                "Also available as: task triage:cache-archive\n");
+            return 0;
+        }
+        else {
+            throw new CacheError(`unexpected argument: ${arg}`);
+        }
+    }
+    const resolvedProjectRoot = projectRoot ?? process.cwd();
+    const resolvedCacheRoot = cacheRoot ?? (projectRoot !== undefined ? resolve(projectRoot, ".deft-cache") : undefined);
+    let latestDecisionMap = null;
+    if (terminalDecisionOnly) {
+        try {
+            const logPath = resolveCandidatesLogPath(resolvedProjectRoot);
+            latestDecisionMap = latestDecisions(readAuditLog(logPath, repo ?? null));
+        }
+        catch {
+            latestDecisionMap = new Map();
+        }
+    }
+    const result = archiveClosedEntries({
+        olderThanDays,
+        source,
+        repo: repo ?? null,
+        dryRun,
+        terminalDecisionOnly,
+        latestDecisions: latestDecisionMap,
+        projectRoot: resolvedProjectRoot,
+        cacheRoot: resolvedCacheRoot,
+        reason,
+    });
+    const payload = {
+        mode: "archive-closed",
+        note: "Reversible closed-entry archive; distinct from cache:prune (TTL hard-delete).",
+        dry_run: result.dryRun,
+        older_than_days: result.olderThanDays,
+        source: result.source,
+        repo: result.repo,
+        terminal_decision_only: terminalDecisionOnly,
+        archived_count: result.archivedCount,
+        skipped_count: result.skippedCount,
+        archived: result.archived.map((c) => ({
+            key: c.key,
+            live_dir: c.liveDir,
+            archive_dir: c.archiveDir,
+            age_basis: c.ageBasis,
+            closed_at: c.closedAt,
+            pre_archive_decision: c.preArchiveDecision,
+        })),
+        skipped: result.skipped.map((s) => ({
+            key: s.key,
+            reason: s.reason,
+            detail: s.detail ?? null,
+        })),
+    };
+    if (json) {
+        process.stdout.write(`${pythonJsonPretty(payload)}\n`);
+    }
+    else {
+        process.stdout.write(`cache:archive-closed dry_run=${pythonBool(result.dryRun)} archived=${result.archivedCount} skipped=${result.skippedCount} older_than_days=${result.olderThanDays}\n`);
+        for (const c of result.archived) {
+            process.stdout.write(`  archived ${c.key} -> ${c.archiveDir}\n`);
+        }
+        for (const s of result.skipped) {
+            process.stdout.write(`  skipped ${s.key} (${s.reason}${s.detail ? `: ${s.detail}` : ""})\n`);
+        }
+    }
+    return 0;
+}
+function cmdArchiveList(args) {
+    let source = "github-issue";
+    let repo;
+    let since;
+    let limit;
+    let format = "text";
+    let cacheRoot;
+    let projectRoot;
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === "--source") {
+            source = args[i + 1] ?? "github-issue";
+            i += 1;
+        }
+        else if (arg === "--repo") {
+            repo = args[i + 1];
+            i += 1;
+        }
+        else if (arg === "--since") {
+            since = args[i + 1];
+            i += 1;
+        }
+        else if (arg === "--limit") {
+            limit = Number.parseInt(args[i + 1] ?? "", 10);
+            i += 1;
+        }
+        else if (arg === "--format") {
+            format = args[i + 1] ?? "text";
+            i += 1;
+        }
+        else if (arg === "--format=json" || arg === "--json") {
+            format = "json";
+        }
+        else if (arg?.startsWith("--format=")) {
+            format = arg.slice("--format=".length);
+        }
+        else if (arg === "--cache-root") {
+            cacheRoot = args[i + 1];
+            i += 1;
+        }
+        else if (arg === "--project-root") {
+            projectRoot = args[i + 1];
+            i += 1;
+        }
+        else if (arg === "-h" || arg === "--help") {
+            process.stdout.write("usage: cache archive-list [--repo OWNER/NAME] [--since ISO] [--limit N]\n" +
+                "       [--format=json|text] [--source github-issue] [--cache-root PATH]\n" +
+                "Also available as: task triage:archive-list\n");
+            return 0;
+        }
+        else {
+            throw new CacheError(`unexpected argument: ${arg}`);
+        }
+    }
+    const resolvedCacheRoot = cacheRoot ?? (projectRoot !== undefined ? resolve(projectRoot, ".deft-cache") : undefined);
+    const result = listArchivedEntries({
+        source,
+        repo: repo ?? null,
+        since: since ?? null,
+        limit: limit ?? null,
+        cacheRoot: resolvedCacheRoot,
+    });
+    if (format === "json") {
+        process.stdout.write(`${pythonJsonPretty({
+            source: result.source,
+            repo: result.repo,
+            count: result.count,
+            entries: result.entries.map((e) => ({
+                key: e.key,
+                archived_at: e.archivedAt,
+                archive_dir: e.archiveDir,
+                meta: e.meta,
+            })),
+        })}\n`);
+    }
+    else {
+        process.stdout.write(`cache:archive-list count=${result.count}\n`);
+        for (const e of result.entries) {
+            process.stdout.write(`  ${e.key} archived_at=${e.archivedAt}\n`);
+        }
+    }
+    return 0;
+}
+function cmdRestoreFromArchive(args) {
+    let source = "github-issue";
+    let key;
+    let issue;
+    let repo;
+    let force = false;
+    let cacheRoot;
+    let projectRoot;
+    let json = false;
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === "--source") {
+            source = args[i + 1] ?? "github-issue";
+            i += 1;
+        }
+        else if (arg === "--key") {
+            key = args[i + 1];
+            i += 1;
+        }
+        else if (arg === "--issue") {
+            const rawIssue = args[i + 1] ?? "";
+            if (!/^[1-9]\d*$/.test(rawIssue)) {
+                throw new CacheError(`--issue must be a positive integer (got ${JSON.stringify(rawIssue)})`);
+            }
+            issue = Number.parseInt(rawIssue, 10);
+            i += 1;
+        }
+        else if (arg === "--repo") {
+            repo = args[i + 1];
+            i += 1;
+        }
+        else if (arg === "--force") {
+            force = true;
+        }
+        else if (arg === "--json") {
+            json = true;
+        }
+        else if (arg === "--cache-root") {
+            cacheRoot = args[i + 1];
+            i += 1;
+        }
+        else if (arg === "--project-root") {
+            projectRoot = args[i + 1];
+            i += 1;
+        }
+        else if (arg === "-h" || arg === "--help") {
+            process.stdout.write("usage: cache restore-from-archive -- --issue N --repo OWNER/NAME [--force]\n" +
+                "       [--key owner/repo/N] [--source github-issue] [--json]\n" +
+                "Also available as: task triage:restore-from-archive\n");
+            return 0;
+        }
+        else if (!key && arg && !arg.startsWith("-") && arg.includes("/")) {
+            key = arg;
+        }
+        else {
+            throw new CacheError(`unexpected argument: ${arg}`);
+        }
+    }
+    const resolvedCacheRoot = cacheRoot ?? (projectRoot !== undefined ? resolve(projectRoot, ".deft-cache") : undefined);
+    const result = restoreFromArchive({
+        source,
+        key,
+        issue,
+        repo: repo ?? null,
+        force,
+        cacheRoot: resolvedCacheRoot,
+    });
+    if (json) {
+        process.stdout.write(`${pythonJsonPretty(result)}\n`);
+    }
+    else {
+        process.stdout.write(`cache:restore-from-archive status=${result.status} key=${result.key} live=${result.liveDir}\n`);
+        if (result.detail) {
+            process.stdout.write(`  detail: ${result.detail}\n`);
+        }
+    }
+    if (result.status === "missing" || result.status === "conflict")
+        return 1;
+    return 0;
+}
 /** CLI entry point (mirrors `scripts/cache.py::main`). */
 export function main(argv) {
     if (argv.length === 0) {
@@ -332,6 +622,13 @@ export function main(argv) {
                 return cmdPrune(rest);
             case "clear":
                 return cmdClear(rest);
+            case "archive-closed":
+            case "cache-archive":
+                return cmdArchiveClosed(rest);
+            case "archive-list":
+                return cmdArchiveList(rest);
+            case "restore-from-archive":
+                return cmdRestoreFromArchive(rest);
             default:
                 usage();
                 process.stderr.write(`cache: error: argument cmd: invalid choice: '${cmd}'\n`);

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

@@ -21,7 +21,7 @@ export declare function readSkill(relPath: string): string;
  */
 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 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-claude-code.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. */

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

@@ -48,6 +48,7 @@ export const SWARM_REFERENCE_ORDER = [
     "host-generic.md",
     "host-grok-build.md",
     "host-cursor.md",
+    "host-claude-code.md",
     "host-openclaw.md",
     "core-phase-4.md",
     "core-phase-5-6.md",

package/dist/doctor/main.js

@@ -517,8 +517,11 @@ export function runAgentHooksHealthCheck(projectRoot, consumerContext, sink, add
             });
             return false;
         }
-        const message = `${checkName}: registered and structurally valid; ` +
-            "Codex runtime trust is user-controlled and must be reviewed with `/hooks`";
+        const codexEnabled = result.registrations.some((entry) => entry.host === "codex" && entry.status !== "disabled");
+        const message = `${checkName}: registered and structurally valid` +
+            (codexEnabled
+                ? "; Codex trust is manual-review-required — open `/hooks` to review the project commands"
+                : "");
         sink.success(message);
         addFinding({
             severity: "skip",
@@ -526,8 +529,11 @@ export function runAgentHooksHealthCheck(projectRoot, consumerContext, sink, add
             check: checkName,
             status: "registered",
             registrations: result.registrations,
-            trust_status: "not-verifiable",
-            trust_review: "Open `/hooks` in Codex and review the project hook commands.",
+            trust_status: codexEnabled ? "manual-review-required" : "not-applicable",
+            trust_review: codexEnabled
+                ? "Open `/hooks` in Codex and review the exact project hook commands."
+                : null,
+            interception_status: "not-directly-verified",
         });
         return true;
     }
@@ -543,7 +549,25 @@ export function runAgentHooksLiveProbeCheck(projectRoot, sink, addFinding, seams
     const liveCheckName = "agent-hooks-live-probe";
     try {
         const result = (seams.evaluateAgentHooks ?? evaluateAgentHooks)(projectRoot);
-        const liveResult = (seams.probeAgentHooksLive ?? probeAgentHooksLive)(projectRoot);
+        if (result.code !== 0) {
+            const message = `${checkName}: ${result.message.replace(/\s+/g, " ").trim()}`;
+            sink.warn(message);
+            addFinding({
+                severity: "warning",
+                message,
+                check: checkName,
+                status: result.code === 2 ? "unavailable" : "incomplete",
+                registrations: result.registrations,
+                suggestion: "deft update",
+            });
+            return;
+        }
+        const enabledHosts = result.registrations
+            .filter((entry) => entry.status !== "disabled")
+            .map((entry) => entry.host);
+        const liveResult = (seams.probeAgentHooksLive ?? probeAgentHooksLive)(projectRoot, {
+            hosts: enabledHosts,
+        });
         if (liveResult.code !== 0) {
             const message = `${liveCheckName}: ${liveResult.message.replace(/\s+/g, " ").trim()}`;
             sink.warn(message);
@@ -557,8 +581,12 @@ export function runAgentHooksLiveProbeCheck(projectRoot, sink, addFinding, seams
             });
             return;
         }
-        const message = `${checkName}: registered, structurally valid, and live probe passed; ` +
-            "Codex runtime trust is user-controlled and must be reviewed with `/hooks`";
+        const codexEnabled = result.registrations.some((entry) => entry.host === "codex" && entry.status !== "disabled");
+        const message = `${checkName}: registered, structurally valid, and live probe passed` +
+            (codexEnabled
+                ? "; Codex trust is manual-review-required — open `/hooks` to review the project commands"
+                : "") +
+            "; direct shim invocation does not verify host interception";
         sink.success(message);
         addFinding({
             severity: "skip",
@@ -566,9 +594,13 @@ export function runAgentHooksLiveProbeCheck(projectRoot, sink, addFinding, seams
             check: liveCheckName,
             status: "registered-and-functional",
             registrations: result.registrations,
-            trust_status: "not-verifiable",
-            trust_review: "Open `/hooks` in Codex and review the project hook commands.",
+            trust_status: codexEnabled ? "manual-review-required" : "not-applicable",
+            trust_review: codexEnabled
+                ? "Open `/hooks` in Codex and review the exact project hook commands."
+                : null,
+            interception_status: "not-directly-verified",
             live_probe: "passed",
+            live_probe_duration_ms: liveResult.durationMs,
         });
     }
     catch (cause) {

package/dist/doctor/types.d.ts

@@ -4,7 +4,7 @@ import type { EngineProbeResult } from "../resolution/classify.js";
 import type { ResolutionMode } from "../resolution/index.js";
 import type { ResolveUserMdResult } from "../user-config/resolve-user-md.js";
 import type { AgentHookHealthResult } from "../verify-env/agent-hooks.js";
-import type { AgentHookLiveProbeResult } from "../verify-env/agent-hooks-live-probe.js";
+import type { AgentHookLiveProbeResult, AgentHookLiveProbeSeams } from "../verify-env/agent-hooks-live-probe.js";
 export declare const EXIT_CLEAN = 0;
 export declare const EXIT_DRIFT = 1;
 export declare const EXIT_CONFIG_ERROR = 2;
@@ -153,7 +153,7 @@ export interface DoctorSeams {
     /** Read-only agent-host hook registration probe (#2438). */
     readonly evaluateAgentHooks?: (projectRoot: string) => AgentHookHealthResult;
     /** Live hook spawn probe for doctor --full (#2852). */
-    readonly probeAgentHooksLive?: (projectRoot: string) => AgentHookLiveProbeResult;
+    readonly probeAgentHooksLive?: (projectRoot: string, seams?: AgentHookLiveProbeSeams) => AgentHookLiveProbeResult;
     /**
      * xBRIEF project-envelope staleness probe (#2971). Injected so doctor can
      * fail closed on 0.6 project JSON under an xbrief/ layout without re-deriving

package/dist/freshness/bind.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Session bind of live deposit generation (#3117).
+ *
+ * Host-agnostic storage:
+ * - Default (no sessionId): `.deft/session-bind.json` — single-operator convenience.
+ * - With sessionId: `.deft/session-binds/<safeId>.json` — isolated multi-session binds.
+ *
+ * Multi-agent hosts MUST pass a stable host session identity when binding and
+ * reporting so one session cannot certify another as current.
+ */
+import { type BoundGeneration, type LiveGeneration } from "./types.js";
+/** Relative path for the default (no-sessionId) bind record. */
+export declare const SESSION_BIND_REL: string;
+/** Directory for per-session bind records. */
+export declare const SESSION_BINDS_DIR_REL: string;
+export declare function sessionBindPath(projectRoot: string, sessionId?: string | null): string;
+/**
+ * Stable filesystem-safe file name for a host session id.
+ * Keeps a short prefix for debug, hashes the rest to avoid path injection.
+ * Character filter is O(n) (no regex) — CodeQL poly-redos on uncontrolled ids.
+ */
+export declare function safeSessionFileName(sessionId: string): string;
+export interface BindSessionOptions {
+    readonly sessionId?: string | null;
+    readonly nowIso?: string;
+    /**
+     * When live generation is missing (legacy deposit), stamp generation 1 from
+     * contentVersion before binding. Default true.
+     */
+    readonly ensureLive?: boolean;
+    /** Used only when ensuring a missing live token. */
+    readonly contentVersion?: string;
+    readonly stampedBy?: string;
+    /**
+     * When binding with a sessionId, also write the default bind path.
+     * Default **false** — multi-agent isolation requires hosts to report with
+     * `--session-id`. Enabling this reopens cross-session false-current (Greptile).
+     */
+    readonly alsoWriteDefault?: boolean;
+    /**
+     * Host attests that payload surfaces for the live generation were reloaded
+     * into the session. Required for trusted readiness. Default false.
+     */
+    readonly payloadLoaded?: boolean;
+}
+export interface ReadBoundOptions {
+    /** When set, read only that session's bind (never the default). */
+    readonly sessionId?: string | null;
+}
+/** Parse a bound generation record (null if invalid). */
+export declare function parseBoundGeneration(raw: unknown): BoundGeneration | null;
+/** Read the session bind record (null when absent/unreadable). */
+export declare function readBoundGeneration(projectRoot: string, options?: ReadBoundOptions): BoundGeneration | null;
+/**
+ * Bind the current live generation into session context.
+ *
+ * Does not require restarting a shared host runtime — callers re-load payload
+ * surfaces into the session and call this (or `freshness:bind`) to rebind.
+ *
+ * Multi-agent hosts MUST supply `sessionId` so binds do not overwrite each other.
+ */
+export declare function bindSessionGeneration(projectRoot: string, options?: BindSessionOptions): {
+    bound: BoundGeneration;
+    live: LiveGeneration;
+    path: string;
+};
+//# sourceMappingURL=bind.d.ts.map