@deftai/directive-core 0.79.2 → 0.79.3

package/dist/review-monitor/record.js

@@ -0,0 +1,178 @@
+import { execFileSync } from "node:child_process";
+import { closeSync, existsSync, fdatasyncSync, mkdirSync, openSync, readFileSync, renameSync, writeSync, } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { DEFAULT_STALE_MINUTES, REVIEW_MONITOR_FILENAME, SCHEMA_VERSION } from "./constants.js";
+function resolveMainWorktreeRoot(startDir) {
+    let root = resolve(startDir);
+    try {
+        const out = execFileSync("git", ["rev-parse", "--git-common-dir"], {
+            cwd: startDir,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        if (out.length > 0) {
+            const commonDir = isAbsolute(out) ? out : resolve(startDir, out);
+            root = dirname(commonDir);
+        }
+    }
+    catch {
+        // Not a git work tree -- fall back to startDir.
+    }
+    return root;
+}
+export function reviewMonitorPath(projectRoot) {
+    const root = resolveMainWorktreeRoot(projectRoot);
+    return join(root, ".deft", REVIEW_MONITOR_FILENAME);
+}
+function atomicWriteJson(path, payload) {
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp-${process.pid}`;
+    const text = `${JSON.stringify(payload, null, 2)}\n`;
+    const fd = openSync(tmp, "w");
+    try {
+        writeSync(fd, text, undefined, "utf8");
+        fdatasyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+    renameSync(tmp, path);
+}
+export function emptyReviewMonitorFile() {
+    return { schema_version: SCHEMA_VERSION, records: [] };
+}
+export function readReviewMonitorFile(path) {
+    if (!existsSync(path)) {
+        return { data: emptyReviewMonitorFile(), error: null };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (exc) {
+        return { data: null, error: `${path}: invalid JSON (${String(exc)}).` };
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        return { data: null, error: `${path}: review-monitor file must be a JSON object.` };
+    }
+    const obj = parsed;
+    const recordsRaw = obj.records;
+    const records = [];
+    if (Array.isArray(recordsRaw)) {
+        for (const entry of recordsRaw) {
+            if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+                continue;
+            }
+            const e = entry;
+            const pr = e.pr;
+            const monitorAgentId = e.monitor_agent_id;
+            const platformPrimitive = e.platform_primitive;
+            const startedAt = e.started_at;
+            const worktreePath = e.worktree_path;
+            if (typeof pr !== "number" ||
+                !Number.isInteger(pr) ||
+                pr <= 0 ||
+                typeof monitorAgentId !== "string" ||
+                monitorAgentId.trim().length === 0 ||
+                typeof platformPrimitive !== "string" ||
+                typeof startedAt !== "string" ||
+                typeof worktreePath !== "string") {
+                continue;
+            }
+            records.push({
+                pr,
+                repo: typeof e.repo === "string" ? e.repo : null,
+                head_sha: typeof e.head_sha === "string" ? e.head_sha : null,
+                platform_primitive: platformPrimitive,
+                monitor_agent_id: monitorAgentId.trim(),
+                started_at: startedAt,
+                worktree_path: worktreePath,
+                parent_session_id: typeof e.parent_session_id === "string" ? e.parent_session_id : null,
+                ended_at: typeof e.ended_at === "string" ? e.ended_at : null,
+            });
+        }
+    }
+    return {
+        data: {
+            schema_version: typeof obj.schema_version === "number" ? obj.schema_version : SCHEMA_VERSION,
+            records,
+        },
+        error: null,
+    };
+}
+export function writeReviewMonitorFile(path, data) {
+    atomicWriteJson(path, data);
+}
+export function registerReviewMonitor(input) {
+    const path = reviewMonitorPath(input.projectRoot);
+    const { data, error } = readReviewMonitorFile(path);
+    if (data === null) {
+        throw new Error(error ?? "could not read review-monitor file");
+    }
+    const startedAt = (input.startedAt ?? new Date()).toISOString();
+    const record = {
+        pr: input.pr,
+        repo: input.repo ?? null,
+        head_sha: input.headSha ?? null,
+        platform_primitive: input.platformPrimitive,
+        monitor_agent_id: input.monitorAgentId.trim(),
+        started_at: startedAt,
+        worktree_path: resolve(input.projectRoot),
+        parent_session_id: input.parentSessionId ?? null,
+        ended_at: null,
+    };
+    const active = data.records.filter((r) => r.ended_at === null && r.pr !== input.pr);
+    writeReviewMonitorFile(path, {
+        schema_version: SCHEMA_VERSION,
+        records: [...active, record],
+    });
+    return { path, record };
+}
+export function parseIso8601Utc(value) {
+    if (typeof value !== "string" || value.length === 0) {
+        return null;
+    }
+    const trimmed = value.trim();
+    let candidate = trimmed;
+    if (trimmed.endsWith("Z")) {
+        candidate = `${trimmed.slice(0, -1)}+00:00`;
+    }
+    if (!candidate.endsWith("+00:00")) {
+        return null;
+    }
+    const parsed = new Date(candidate);
+    if (Number.isNaN(parsed.getTime())) {
+        return null;
+    }
+    return parsed;
+}
+export function isRecordActive(record, options) {
+    if (record.ended_at !== null) {
+        return false;
+    }
+    const started = parseIso8601Utc(record.started_at);
+    if (started === null) {
+        return false;
+    }
+    const now = options.now ?? new Date();
+    const staleMinutes = options.staleMinutes ?? DEFAULT_STALE_MINUTES;
+    const ageMs = now.getTime() - started.getTime();
+    if (ageMs > staleMinutes * 60 * 1000) {
+        return false;
+    }
+    if (options.headSha !== undefined && options.headSha !== null && record.head_sha !== null) {
+        return record.head_sha === options.headSha;
+    }
+    return true;
+}
+export function findActiveMonitorForPr(file, pr, options) {
+    const matches = file.records.filter((r) => r.pr === pr && isRecordActive(r, options));
+    if (matches.length === 0) {
+        return null;
+    }
+    return matches.sort((a, b) => b.started_at.localeCompare(a.started_at))[0] ?? null;
+}
+export function defaultSubagentStatusDir(projectRoot) {
+    return join(resolve(projectRoot), ".deft-scratch", "subagent-status");
+}
+//# sourceMappingURL=record.js.map

package/dist/review-monitor/tier-detection.d.ts

@@ -0,0 +1,15 @@
+import { MONITORING_TIER_1, MONITORING_TIER_2, MONITORING_TIER_3 } from "./constants.js";
+export type PlatformPrimitive = "start_agent" | "spawn_subagent" | "cursor-task";
+export interface MonitoringTierProbe {
+    readonly tier: typeof MONITORING_TIER_1 | typeof MONITORING_TIER_2 | typeof MONITORING_TIER_3;
+    readonly primitive: PlatformPrimitive | null;
+    readonly descriptor: string | null;
+}
+/**
+ * Inline Tier-1 detection aligned with the swarm Phase 3 / review-cycle matrix
+ * (#1877 / #2655). Prefer `task platform:capabilities` when available (#1357);
+ * this probe does not block MVP.
+ */
+export declare function probeMonitoringTier(environ?: NodeJS.ProcessEnv): MonitoringTierProbe;
+export declare function isTier1(probe: MonitoringTierProbe): boolean;
+//# sourceMappingURL=tier-detection.d.ts.map

package/dist/review-monitor/tier-detection.js

@@ -0,0 +1,61 @@
+import { MONITORING_TIER_1, MONITORING_TIER_2, MONITORING_TIER_3 } from "./constants.js";
+const TRUTHY = new Set(["1", "true", "yes", "on"]);
+function envTruthy(environ, name) {
+    return TRUTHY.has((environ[name] ?? "").trim().toLowerCase());
+}
+function probeOverride(environ) {
+    const raw = (environ.DEFT_MONITOR_TIER ?? environ.DEFT_MONITOR_TIER_OVERRIDE ?? "").trim();
+    if (raw === "1" || raw.toLowerCase() === "tier1") {
+        const primitive = environ.DEFT_MONITOR_TIER1_PRIMITIVE ?? "cursor-task";
+        return { tier: MONITORING_TIER_1, primitive, descriptor: "override-tier1" };
+    }
+    if (raw === "3" || raw.toLowerCase() === "tier3") {
+        return { tier: MONITORING_TIER_3, primitive: null, descriptor: "generic-terminal" };
+    }
+    return null;
+}
+/**
+ * Inline Tier-1 detection aligned with the swarm Phase 3 / review-cycle matrix
+ * (#1877 / #2655). Prefer `task platform:capabilities` when available (#1357);
+ * this probe does not block MVP.
+ */
+export function probeMonitoringTier(environ = process.env) {
+    const override = probeOverride(environ);
+    if (override !== null) {
+        return override;
+    }
+    if (envTruthy(environ, "DEFT_PROBE_START_AGENT") || envTruthy(environ, "DEFT_HAS_START_AGENT")) {
+        return { tier: MONITORING_TIER_1, primitive: "start_agent", descriptor: "warp-orchestrated" };
+    }
+    if (envTruthy(environ, "WARP_IS_WARP_TERMINAL") || envTruthy(environ, "WARP_TERMINAL_SESSION")) {
+        return { tier: MONITORING_TIER_1, primitive: "start_agent", descriptor: "warp-manual" };
+    }
+    if (envTruthy(environ, "CURSOR_COMPOSER")) {
+        return { tier: MONITORING_TIER_1, primitive: "cursor-task", descriptor: "cursor-composer" };
+    }
+    if (envTruthy(environ, "CURSOR_AGENT")) {
+        return {
+            tier: MONITORING_TIER_1,
+            primitive: "cursor-task",
+            descriptor: "cursor-cloud-agent",
+        };
+    }
+    const runtime = (environ.DEFT_AGENT_RUNTIME ?? "").trim().toLowerCase();
+    if (envTruthy(environ, "DEFT_PROBE_GROK_BUILD") ||
+        envTruthy(environ, "GROK_BUILD") ||
+        runtime === "grok-build") {
+        return { tier: MONITORING_TIER_1, primitive: "spawn_subagent", descriptor: "grok-build" };
+    }
+    if (envTruthy(environ, "DEFT_PROBE_SPAWN_SUBAGENT") ||
+        envTruthy(environ, "DEFT_HAS_SPAWN_SUBAGENT")) {
+        return { tier: MONITORING_TIER_1, primitive: "spawn_subagent", descriptor: "grok-build" };
+    }
+    if (envTruthy(environ, "DEFT_MONITOR_TIER2") || envTruthy(environ, "DEFT_HAS_AUTO_REINVOKE")) {
+        return { tier: MONITORING_TIER_2, primitive: null, descriptor: "yield-between-polls" };
+    }
+    return { tier: MONITORING_TIER_3, primitive: null, descriptor: "generic-terminal" };
+}
+export function isTier1(probe) {
+    return probe.tier === MONITORING_TIER_1;
+}
+//# sourceMappingURL=tier-detection.js.map

package/dist/review-monitor/verify.d.ts

@@ -0,0 +1,32 @@
+import { EXIT_CONFIG_ERROR, EXIT_NOT_READY, EXIT_READY, MONITORING_TIER_1, MONITORING_TIER_3 } from "./constants.js";
+import { type ReviewMonitorRecord } from "./record.js";
+import { type MonitoringTierProbe } from "./tier-detection.js";
+export type ReviewMonitorCallSite = "solo" | "swarm-phase5-6" | "swarm-phase6-cascade" | "unspecified";
+export interface VerifyReviewMonitorArgs {
+    readonly pr: number;
+    readonly projectRoot: string;
+    readonly repo?: string | null;
+    readonly headSha?: string | null;
+    readonly callSite?: ReviewMonitorCallSite;
+    readonly approach3?: boolean;
+    readonly approach3Warned?: boolean;
+    readonly staleMinutes?: number;
+    readonly now?: Date;
+    readonly environ?: NodeJS.ProcessEnv;
+}
+export interface VerifyReviewMonitorResult {
+    readonly exitCode: typeof EXIT_READY | typeof EXIT_NOT_READY | typeof EXIT_CONFIG_ERROR;
+    readonly message: string;
+    readonly tier: MonitoringTierProbe;
+    readonly monitorRecord: ReviewMonitorRecord | null;
+    readonly heartbeatActive: boolean;
+    readonly callSite: ReviewMonitorCallSite;
+}
+export declare function hasActivePollingHeartbeat(projectRoot: string, pr: number, options?: {
+    now?: Date;
+    staleMinutes?: number;
+}): boolean;
+export declare function evaluateReviewMonitorGate(args: VerifyReviewMonitorArgs): VerifyReviewMonitorResult;
+export declare function verifyResultToJson(result: VerifyReviewMonitorResult): Record<string, unknown>;
+export { EXIT_CONFIG_ERROR, EXIT_NOT_READY, EXIT_READY, MONITORING_TIER_1, MONITORING_TIER_3 };
+//# sourceMappingURL=verify.d.ts.map

package/dist/review-monitor/verify.js

@@ -0,0 +1,171 @@
+import { existsSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+import { sweepScratchDirs } from "../orchestration/subagent-monitor.js";
+import { EXIT_CONFIG_ERROR, EXIT_NOT_READY, EXIT_READY, MONITORING_TIER_1, MONITORING_TIER_3, } from "./constants.js";
+import { defaultSubagentStatusDir, findActiveMonitorForPr, readReviewMonitorFile, reviewMonitorPath, } from "./record.js";
+import { isTier1, probeMonitoringTier } from "./tier-detection.js";
+function spawnRedirect(probe) {
+    const primitive = probe.primitive ?? "sub-agent";
+    return (`Spawn an Approach 1 review-monitor via ${primitive} (background), include ` +
+        "`templates/agent-prompt-preamble.md` and `templates/swarm-greptile-poller-prompt.md`, " +
+        "then register:\n" +
+        "  task review-monitor:register -- --pr <N> --monitor-agent-id <id> " +
+        `--platform-primitive ${primitive}\n` +
+        "Re-run: task verify:review-monitor -- --pr <N>");
+}
+export function hasActivePollingHeartbeat(projectRoot, pr, options = {}) {
+    const dir = defaultSubagentStatusDir(projectRoot);
+    if (!existsSync(dir)) {
+        return false;
+    }
+    try {
+        if (!statSync(dir).isDirectory()) {
+            return false;
+        }
+    }
+    catch {
+        return false;
+    }
+    const result = sweepScratchDirs([{ readPath: dir, label: dir }], {
+        thresholdMinutes: options.staleMinutes ?? 30,
+        now: options.now,
+    });
+    return result.records.some((rec) => rec.pr_number === pr &&
+        rec.failures.length === 0 &&
+        !rec.is_stale &&
+        !rec.is_terminal &&
+        (rec.phase === "polling" || rec.phase === "starting"));
+}
+export function evaluateReviewMonitorGate(args) {
+    const projectRoot = resolve(args.projectRoot);
+    let isDir = false;
+    try {
+        isDir = statSync(projectRoot).isDirectory();
+    }
+    catch {
+        isDir = false;
+    }
+    if (!isDir) {
+        return {
+            exitCode: EXIT_CONFIG_ERROR,
+            message: `verify_review_monitor: --project-root is not a directory: ${projectRoot}`,
+            tier: probeMonitoringTier(args.environ),
+            monitorRecord: null,
+            heartbeatActive: false,
+            callSite: args.callSite ?? "unspecified",
+        };
+    }
+    const tier = probeMonitoringTier(args.environ);
+    const callSite = args.callSite ?? "unspecified";
+    const staleMinutes = args.staleMinutes ?? 30;
+    const now = args.now ?? new Date();
+    if (args.approach3 === true) {
+        if (isTier1(tier)) {
+            return {
+                exitCode: EXIT_NOT_READY,
+                message: "verify_review_monitor: Approach 3 blocking poll is forbidden when Tier 1 is available (#2655).\n" +
+                    `  Detected tier=${tier.tier} descriptor=${tier.descriptor ?? "unknown"} primitive=${tier.primitive ?? "none"}.\n` +
+                    `  ${spawnRedirect(tier)}`,
+                tier,
+                monitorRecord: null,
+                heartbeatActive: false,
+                callSite,
+            };
+        }
+        if (tier.tier === MONITORING_TIER_3 && args.approach3Warned !== true) {
+            return {
+                exitCode: EXIT_NOT_READY,
+                message: "verify_review_monitor: Approach 3 requires explicit user warning acknowledgment (#2655).\n" +
+                    "  Warn the operator that the conversation pane will lock during polling, then re-run with --approach3-warned.",
+                tier,
+                monitorRecord: null,
+                heartbeatActive: false,
+                callSite,
+            };
+        }
+        return {
+            exitCode: EXIT_READY,
+            message: `verify_review_monitor: Tier 3 Approach 3 path allowed (call-site=${callSite}).`,
+            tier,
+            monitorRecord: null,
+            heartbeatActive: false,
+            callSite,
+        };
+    }
+    if (!isTier1(tier)) {
+        return {
+            exitCode: EXIT_READY,
+            message: `verify_review_monitor: Tier ${tier.tier} (${tier.descriptor ?? "unknown"}) — ` +
+                "no active review-monitor required (#2655).",
+            tier,
+            monitorRecord: null,
+            heartbeatActive: false,
+            callSite,
+        };
+    }
+    const path = reviewMonitorPath(projectRoot);
+    const { data, error } = readReviewMonitorFile(path);
+    if (data === null) {
+        return {
+            exitCode: EXIT_CONFIG_ERROR,
+            message: `verify_review_monitor: ${error ?? "could not read review-monitor state"}`,
+            tier,
+            monitorRecord: null,
+            heartbeatActive: false,
+            callSite,
+        };
+    }
+    const monitorRecord = findActiveMonitorForPr(data, args.pr, {
+        now,
+        staleMinutes,
+        headSha: args.headSha ?? null,
+    });
+    const heartbeatActive = hasActivePollingHeartbeat(projectRoot, args.pr, {
+        now,
+        staleMinutes,
+    });
+    if (monitorRecord !== null || heartbeatActive) {
+        const via = monitorRecord !== null ? "review-monitor record" : "subagent heartbeat";
+        return {
+            exitCode: EXIT_READY,
+            message: `verify_review_monitor: active review-monitor for PR #${args.pr} via ${via} ` +
+                `(call-site=${callSite}, tier=1, descriptor=${tier.descriptor ?? "unknown"}).`,
+            tier,
+            monitorRecord,
+            heartbeatActive,
+            callSite,
+        };
+    }
+    const siteHint = callSite === "swarm-phase5-6"
+        ? "Swarm Phase 5→6 handoff (#1386)"
+        : callSite === "swarm-phase6-cascade"
+            ? "Swarm Phase 6 post force-push (#380)"
+            : "Solo drive-to merge-ready / review-cycle ownership";
+    return {
+        exitCode: EXIT_NOT_READY,
+        message: `verify_review_monitor: Tier 1 available but no active review-monitor for PR #${args.pr} (#2655).\n` +
+            `  Call site: ${siteHint}.\n` +
+            `  Detected descriptor=${tier.descriptor ?? "unknown"} primitive=${tier.primitive ?? "none"}.\n` +
+            `  ${spawnRedirect(tier)}`,
+        tier,
+        monitorRecord: null,
+        heartbeatActive: false,
+        callSite,
+    };
+}
+export function verifyResultToJson(result) {
+    return {
+        call_site: result.callSite,
+        exit_code: result.exitCode,
+        heartbeat_active: result.heartbeatActive,
+        message: result.message,
+        monitor_agent_id: result.monitorRecord?.monitor_agent_id ?? null,
+        monitor_record: result.monitorRecord,
+        ready: result.exitCode === EXIT_READY,
+        tier: result.tier.tier,
+        tier_descriptor: result.tier.descriptor,
+        tier_primitive: result.tier.primitive,
+    };
+}
+export { EXIT_CONFIG_ERROR, EXIT_NOT_READY, EXIT_READY, MONITORING_TIER_1, MONITORING_TIER_3 };
+//# sourceMappingURL=verify.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deftai/directive-core",
-  "version": "0.79.2",
+  "version": "0.79.3",
   "description": "TypeScript engine core for the Directive framework.",
   "type": "module",
   "main": "./dist/index.js",
@@ -242,6 +242,10 @@
       "types": "./dist/swarm/index.d.ts",
       "default": "./dist/swarm/index.js"
     },
+    "./review-monitor": {
+      "types": "./dist/review-monitor/index.d.ts",
+      "default": "./dist/review-monitor/index.js"
+    },
     "./platform": {
       "types": "./dist/platform/index.d.ts",
       "default": "./dist/platform/index.js"
@@ -305,8 +309,8 @@
     "provenance": true
   },
   "dependencies": {
-    "@deftai/directive-content": "^0.79.2",
-    "@deftai/directive-types": "^0.79.2",
+    "@deftai/directive-content": "^0.79.3",
+    "@deftai/directive-types": "^0.79.3",
     "archiver": "^8.0.0"
   },
   "scripts": {