@deftai/directive-core 0.107.0 → 0.109.0

package/dist/orphan-active/issue-state.js

@@ -0,0 +1,278 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { REPO_RE } from "../cache/constants.js";
+import { defaultRunGh } from "../pr-protected-issues/gh.js";
+import { defaultWhich, resolveBinary } from "../scm/binary.js";
+import { ScmStubError } from "../scm/errors.js";
+import { restIssueListOpenInventory } from "../scm/gh-rest.js";
+import { CACHE_DIR_NAME, CACHE_SOURCE_GITHUB_ISSUE } from "../triage/queue/constants.js";
+/**
+ * A cache hit older than this is no longer evidence (#3767). The measured
+ * defect was a ~12 h old cached `open` suppressing the live read that would
+ * have corrected it; 15 min keeps warm-cache offline runs working while making
+ * an overnight entry non-authoritative.
+ */
+export const ISSUE_CACHE_MAX_AGE_MS = 15 * 60 * 1000;
+/**
+ * Latency budget for scoped `--issue N`: one authoritative issue read plus at
+ * most one linked-PR read. Measured ~0.75 s per `gh api` read; the headroom
+ * covers a slow network or a `ghx` proxy hop.
+ */
+export const SCOPED_LATENCY_BUDGET_MS = 5_000;
+/**
+ * Latency budget for the unscoped aggregate sweep. One complete open-issue
+ * inventory measured 4.2 s constant on deftai/directive (560 open issues),
+ * against 14.2 s and 76.6 s for per-brief reads at the WIP cap of 20 on two
+ * hosts. The budget is sized for the inventory plus a few confirming reads and
+ * keeps the gate inside the fast-preflight tier.
+ */
+export const AGGREGATE_LATENCY_BUDGET_MS = 15_000;
+/** `resolveBinary` view that hides `ghx`, so this gate reads through plain `gh` when it exists. */
+const GH_ONLY_WHICH = (name) => (name === "ghx" ? null : defaultWhich(name));
+/**
+ * Pin plain `gh` for this gate's authoritative reads (#3767). `resolveBinary`
+ * prefers `ghx` — a cached GET proxy — so an unpinned "live" read is itself a
+ * cache. When `gh` is absent we still run, and report the proxy caveat rather
+ * than claiming freshness we cannot deliver. Whether `ghx` should be preferred
+ * at all is #3737.
+ */
+export function makeGateRunner() {
+    let pinned = null;
+    try {
+        pinned = resolveBinary(GH_ONLY_WHICH);
+    }
+    catch {
+        pinned = null;
+    }
+    if (pinned === null) {
+        return { runGh: defaultRunGh, proxied: true };
+    }
+    const binary = pinned;
+    return { runGh: (cmd) => defaultRunGh(cmd, binary), proxied: false };
+}
+function isSafeRepo(repo) {
+    return REPO_RE.test(repo);
+}
+function readJson(path) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)
+            ? parsed
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+function cacheEntryDir(projectRoot, ref) {
+    const [owner, name] = ref.repo.split("/", 2);
+    if (!owner || !name) {
+        return null;
+    }
+    return join(projectRoot, CACHE_DIR_NAME, CACHE_SOURCE_GITHUB_ISSUE, owner, name, String(ref.number));
+}
+function cacheEntryAgeMs(entryDir, rawPath, nowMs) {
+    const meta = readJson(join(entryDir, "meta.json"));
+    const stamp = meta?.fetched_at ?? meta?.cached_at ?? meta?.updated_at;
+    if (typeof stamp === "string") {
+        const parsed = Date.parse(stamp);
+        if (Number.isFinite(parsed)) {
+            return Math.max(0, nowMs - parsed);
+        }
+    }
+    try {
+        return Math.max(0, nowMs - statSync(rawPath).mtimeMs);
+    }
+    catch {
+        return null;
+    }
+}
+const CACHE_MISS = { state: null, ageMs: null };
+/** Read the triage-cache issue state together with the entry's age (#3767). */
+export function readCachedIssue(projectRoot, ref, nowMs) {
+    const entryDir = cacheEntryDir(projectRoot, ref);
+    if (entryDir === null) {
+        return CACHE_MISS;
+    }
+    const rawPath = join(entryDir, "raw.json");
+    if (!existsSync(rawPath)) {
+        return CACHE_MISS;
+    }
+    const raw = readJson(rawPath);
+    if (raw === null) {
+        return CACHE_MISS;
+    }
+    const state = typeof raw.state === "string" ? raw.state.toLowerCase() : "";
+    if (state !== "open" && state !== "closed") {
+        return CACHE_MISS;
+    }
+    return { state, ageMs: cacheEntryAgeMs(entryDir, rawPath, nowMs) };
+}
+/** Authoritative single-issue REST read. Returns `null` on any failure. */
+export function fetchIssueStateLive(ref, runGh) {
+    const result = runGh(["gh", "api", `repos/${ref.repo}/issues/${ref.number}`]);
+    if (result.returncode !== 0) {
+        return null;
+    }
+    try {
+        const payload = JSON.parse(result.stdout);
+        if (payload === null || typeof payload !== "object") {
+            return null;
+        }
+        const state = payload.state;
+        return state === "open" || state === "closed" ? state : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * One complete open-issue inventory per repo per run (#3767, reusing #3752).
+ * `restIssueListOpenInventory` fails closed on command failure, non-array JSON,
+ * malformed rows, buffer exhaustion, and pagination cap — so absence from a
+ * successful inventory really does mean "not open", and a truncated read is an
+ * error rather than a silent "closed".
+ */
+export class OpenIssueInventory {
+    runGh;
+    byRepo = new Map();
+    confirmations = new Map();
+    constructor(runGh) {
+        this.runGh = runGh;
+    }
+    lookup(repo) {
+        const memo = this.byRepo.get(repo);
+        if (memo !== undefined) {
+            return memo;
+        }
+        const resolved = this.fetch(repo);
+        this.byRepo.set(repo, resolved);
+        return resolved;
+    }
+    /**
+     * Confirm an inventory absence with one authoritative read, reused for the
+     * rest of this run when several briefs name the same issue (#3767).
+     */
+    confirm(ref) {
+        const key = `${ref.repo}#${ref.number}`;
+        if (this.confirmations.has(key)) {
+            return this.confirmations.get(key) ?? null;
+        }
+        const confirmed = fetchIssueStateLive(ref, this.runGh);
+        this.confirmations.set(key, confirmed);
+        return confirmed;
+    }
+    fetch(repo) {
+        try {
+            const rows = restIssueListOpenInventory(repo, {
+                runGhApiFn: (args) => this.runGh(["gh", "api", ...args]),
+            });
+            const numbers = new Set();
+            for (const row of rows) {
+                const n = row.number;
+                if (typeof n === "number" && Number.isInteger(n)) {
+                    numbers.add(n);
+                }
+            }
+            return { numbers };
+        }
+        catch (err) {
+            if (err instanceof ScmStubError) {
+                throw err;
+            }
+            const message = err instanceof Error ? err.message : String(err);
+            return { error: message.split("\n")[0] ?? "unknown error" };
+        }
+    }
+}
+function unverified(detail) {
+    return { state: null, basis: "unverified", detail };
+}
+function freshOrNull(cached) {
+    return cached.state !== null && cached.ageMs !== null && cached.ageMs <= ISSUE_CACHE_MAX_AGE_MS
+        ? { state: cached.state, ageMs: cached.ageMs }
+        : null;
+}
+function fromCache(fresh) {
+    return { state: fresh.state, basis: "cache", cacheAgeMs: fresh.ageMs };
+}
+function staleDetail(cached) {
+    const age = cached.ageMs === null ? "unknown age" : formatAge(cached.ageMs);
+    return `cached ${cached.state} is ${age} old (max ${formatAge(ISSUE_CACHE_MAX_AGE_MS)})`;
+}
+/** Human-readable duration for basis reporting: `42s`, `9m`, `12h`, `3d`. */
+export function formatAge(ms) {
+    const seconds = Math.round(ms / 1000);
+    if (seconds < 60) {
+        return `${seconds}s`;
+    }
+    const minutes = Math.round(seconds / 60);
+    if (minutes < 60) {
+        return `${minutes}m`;
+    }
+    const hours = Math.round(minutes / 60);
+    return hours < 48 ? `${hours}h` : `${Math.round(hours / 24)}d`;
+}
+/**
+ * Scoped `--issue N`: a proof obligation before DONE, so read authoritatively
+ * first and accept a cache hit only inside the freshness bound. Unknown stays
+ * fail-closed at the call site.
+ */
+export function resolveIssueStateScoped(ref, ctx) {
+    if (!isSafeRepo(ref.repo)) {
+        return unverified(`reference repo '${ref.repo}' is not a valid owner/repo slug`);
+    }
+    if (!ctx.skipGh) {
+        const live = fetchIssueStateLive(ref, ctx.runGh);
+        if (live !== null) {
+            return { state: live, basis: "live" };
+        }
+    }
+    const cached = readCachedIssue(ctx.projectRoot, ref, ctx.nowMs);
+    const fresh = freshOrNull(cached);
+    if (fresh !== null) {
+        return fromCache(fresh);
+    }
+    if (cached.state !== null) {
+        return unverified(`${staleDetail(cached)} and the authoritative read was unavailable`);
+    }
+    return unverified(ctx.skipGh ? "--skip-gh with no cache entry" : "live issue read failed and no cache entry");
+}
+/**
+ * Unscoped aggregate: resolve every reference from one complete open-issue
+ * inventory rather than a live read per brief. Membership means open. Absence
+ * means "not open", which is the direction that tells an operator to run
+ * `scope:complete`, so it is confirmed by one authoritative read before the
+ * gate acts on it.
+ */
+export function resolveIssueStateAggregate(ref, ctx) {
+    if (!isSafeRepo(ref.repo)) {
+        return unverified(`reference repo '${ref.repo}' is not a valid owner/repo slug`);
+    }
+    const cached = readCachedIssue(ctx.projectRoot, ref, ctx.nowMs);
+    const fresh = freshOrNull(cached);
+    if (ctx.skipGh) {
+        if (fresh !== null) {
+            return fromCache(fresh);
+        }
+        return unverified(cached.state === null
+            ? "--skip-gh with no cache entry"
+            : `--skip-gh and ${staleDetail(cached)}`);
+    }
+    const inventory = ctx.inventory.lookup(ref.repo);
+    if ("error" in inventory) {
+        if (fresh !== null) {
+            return fromCache(fresh);
+        }
+        return unverified(`open-issue inventory unavailable: ${inventory.error}`);
+    }
+    if (inventory.numbers.has(ref.number)) {
+        return { state: "open", basis: "inventory" };
+    }
+    const confirmed = ctx.inventory.confirm(ref);
+    if (confirmed !== null) {
+        return { state: confirmed, basis: "live" };
+    }
+    return unverified("absent from the open-issue inventory but the confirming read failed");
+}
+//# sourceMappingURL=issue-state.js.map

package/dist/platform/cursor-managed-runtime.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Cursor managed-runtime probe and explicit host-gh selection (#3859).
+ *
+ * `CURSOR_AGENT` is set by local desktop Cursor, by Cursor-managed cloud VMs,
+ * and by Windows "My Machines" workers alike, so it cannot decide the runtime on
+ * its own. Two routes were considered and rejected:
+ *
+ *   - Dropping the `CURSOR_AGENT` hop grants host credentials on a managed VM
+ *     by marker *absence*.
+ *   - `process.platform === "win32"` is not an invariant. Cursor runs Windows
+ *     My Machines workers under a cloud agent loop, and "managed VMs are Ubuntu"
+ *     is a versioned fact about a third party's fleet, not a runtime property.
+ *
+ * What remains is a genuine asymmetry:
+ *
+ *   - Cursor-managed VMs serve a local metadata API on `CURSOR_AGENT_SOCKET`
+ *     whose `agent/runtime` is always `managed`. A successful read is a
+ *     *positive* assertion of managed cloud, so it is a sound deny signal.
+ *   - There is no positive local-desktop signal. Absence of the socket means
+ *     "not managed, or unreachable" and MUST NOT select host credentials --
+ *     that is the marker-absence grant this module exists to prevent. Absence
+ *     leaves the runtime ambiguous, and an ambiguous runtime requires an
+ *     explicit operator or dispatcher selection.
+ *
+ * Both probe error directions are safe. A false `managed` denies host
+ * credentials (fail closed). A failed read leaves the runtime ambiguous, which
+ * preserves today's behaviour unless an operator opted in.
+ */
+/** Env var carrying the Cursor managed-runtime metadata socket path. */
+export declare const MANAGED_RUNTIME_SOCKET_ENV = "CURSOR_AGENT_SOCKET";
+/** Metadata API route reporting the runtime kind. */
+export declare const MANAGED_RUNTIME_PATH = "/agent/runtime";
+/** The only `agent/runtime` value Cursor-managed VMs report. */
+export declare const MANAGED_RUNTIME_VALUE = "managed";
+/**
+ * Env var an operator or dispatcher sets to resolve an ambiguous Cursor
+ * runtime. Named for the `github_auth_mode` dispatch-envelope field so a
+ * dispatcher exports the same label it already records.
+ */
+export declare const GITHUB_AUTH_MODE_ENV = "DEFT_GITHUB_AUTH_MODE";
+/** Stable reason ids naming why a runtime mode was chosen (#3859). */
+export declare const RUNTIME_REASON_CI_MARKER = "ci-marker";
+export declare const RUNTIME_REASON_MANAGED_RUNTIME_PROBE = "cursor-managed-runtime-probe";
+export declare const RUNTIME_REASON_CURSOR_SANDBOX_MARKER = "cursor-sandbox-marker";
+export declare const RUNTIME_REASON_CURSOR_MARKER_AMBIGUOUS = "cursor-marker-runtime-ambiguous";
+export declare const RUNTIME_REASON_EXPLICIT_HOST_GH = "explicit-host-gh-selection";
+export declare const RUNTIME_REASON_NO_RUNTIME_MARKER = "no-runtime-marker";
+export type ManagedRuntimeVerdict = "managed" | "not-managed" | "unavailable";
+export interface ManagedRuntimeProbeResult {
+    /** `managed` is the only verdict that may deny host credentials. */
+    readonly verdict: ManagedRuntimeVerdict;
+    readonly socketPath: string | null;
+    /** Short non-secret diagnostic for operator-visible output. */
+    readonly detail: string;
+}
+export type ManagedRuntimeProbe = (environ: Readonly<Record<string, string | undefined>>) => ManagedRuntimeProbeResult;
+/**
+ * True when a metadata body reports the managed runtime.
+ *
+ * Accepts a JSON object carrying a `runtime` (or `agentRuntime` / `agent_runtime`)
+ * field and a bare string body, because the exact response shape is documented
+ * only as "`agent/runtime` is always `managed`". Over-matching here denies host
+ * credentials, which is the safe direction.
+ */
+export declare function bodyReportsManagedRuntime(body: string): boolean;
+/** Shape the reader child writes to stdout. */
+interface ProbeResponse {
+    readonly status?: number;
+    readonly body?: string;
+    readonly error?: string;
+}
+/**
+ * Interpret the reader child's stdout, or null when it is not a usable object.
+ *
+ * Exported for the same reason as `bodyReportsManagedRuntime`: it is the parsing
+ * step and it has to be provably total. `JSON.parse("null")` returns null
+ * without throwing, so a bare try/catch around the parse would still leave the
+ * field reads that follow able to throw -- and a probe that throws aborts
+ * classification instead of failing closed.
+ */
+export declare function parseProbeResponse(stdout: string): ProbeResponse | null;
+/** Clear the probe memo. Test seam only. */
+export declare function resetManagedRuntimeProbeCache(): void;
+/** Default managed-runtime probe. Never throws. */
+export declare const probeManagedRuntime: ManagedRuntimeProbe;
+/**
+ * True when an operator or dispatcher explicitly selected host-gh for this
+ * execution environment. This resolves an *ambiguous* runtime only; it can
+ * never override a positive managed-runtime read.
+ */
+export declare function hasExplicitHostGhSelection(environ: Readonly<Record<string, string | undefined>>): boolean;
+/** Remediation naming the opt-in, for operator-visible not-ready output. */
+export declare const EXPLICIT_SELECTION_REMEDIATION: string;
+export {};
+//# sourceMappingURL=cursor-managed-runtime.d.ts.map

package/dist/platform/cursor-managed-runtime.js

@@ -0,0 +1,241 @@
+/**
+ * Cursor managed-runtime probe and explicit host-gh selection (#3859).
+ *
+ * `CURSOR_AGENT` is set by local desktop Cursor, by Cursor-managed cloud VMs,
+ * and by Windows "My Machines" workers alike, so it cannot decide the runtime on
+ * its own. Two routes were considered and rejected:
+ *
+ *   - Dropping the `CURSOR_AGENT` hop grants host credentials on a managed VM
+ *     by marker *absence*.
+ *   - `process.platform === "win32"` is not an invariant. Cursor runs Windows
+ *     My Machines workers under a cloud agent loop, and "managed VMs are Ubuntu"
+ *     is a versioned fact about a third party's fleet, not a runtime property.
+ *
+ * What remains is a genuine asymmetry:
+ *
+ *   - Cursor-managed VMs serve a local metadata API on `CURSOR_AGENT_SOCKET`
+ *     whose `agent/runtime` is always `managed`. A successful read is a
+ *     *positive* assertion of managed cloud, so it is a sound deny signal.
+ *   - There is no positive local-desktop signal. Absence of the socket means
+ *     "not managed, or unreachable" and MUST NOT select host credentials --
+ *     that is the marker-absence grant this module exists to prevent. Absence
+ *     leaves the runtime ambiguous, and an ambiguous runtime requires an
+ *     explicit operator or dispatcher selection.
+ *
+ * Both probe error directions are safe. A false `managed` denies host
+ * credentials (fail closed). A failed read leaves the runtime ambiguous, which
+ * preserves today's behaviour unless an operator opted in.
+ */
+import { spawnSync } from "node:child_process";
+/**
+ * The `host-gh` auth-mode label. Duplicated from intake/github-auth-modes.ts
+ * rather than imported: that module imports the runtime classifier, which
+ * imports this one.
+ */
+const HOST_GH_SELECTION = "host-gh";
+/** Env var carrying the Cursor managed-runtime metadata socket path. */
+export const MANAGED_RUNTIME_SOCKET_ENV = "CURSOR_AGENT_SOCKET";
+/** Metadata API route reporting the runtime kind. */
+export const MANAGED_RUNTIME_PATH = "/agent/runtime";
+/** The only `agent/runtime` value Cursor-managed VMs report. */
+export const MANAGED_RUNTIME_VALUE = "managed";
+/**
+ * Env var an operator or dispatcher sets to resolve an ambiguous Cursor
+ * runtime. Named for the `github_auth_mode` dispatch-envelope field so a
+ * dispatcher exports the same label it already records.
+ */
+export const GITHUB_AUTH_MODE_ENV = "DEFT_GITHUB_AUTH_MODE";
+/** Stable reason ids naming why a runtime mode was chosen (#3859). */
+export const RUNTIME_REASON_CI_MARKER = "ci-marker";
+export const RUNTIME_REASON_MANAGED_RUNTIME_PROBE = "cursor-managed-runtime-probe";
+export const RUNTIME_REASON_CURSOR_SANDBOX_MARKER = "cursor-sandbox-marker";
+export const RUNTIME_REASON_CURSOR_MARKER_AMBIGUOUS = "cursor-marker-runtime-ambiguous";
+export const RUNTIME_REASON_EXPLICIT_HOST_GH = "explicit-host-gh-selection";
+export const RUNTIME_REASON_NO_RUNTIME_MARKER = "no-runtime-marker";
+/**
+ * Read the metadata API in a child process.
+ *
+ * The readiness and classification paths are synchronous throughout, and Node
+ * cannot read an HTTP-over-unix-socket response synchronously in-process. This
+ * runs only when `CURSOR_AGENT_SOCKET` is set, so the common local case pays
+ * nothing.
+ */
+const READER_SCRIPT = `
+const http = require("node:http");
+const done = (payload) => { process.stdout.write(JSON.stringify(payload)); };
+const req = http.request(
+  {
+    socketPath: process.env.DEFT_PROBE_SOCKET,
+    path: process.env.DEFT_PROBE_PATH,
+    method: "GET",
+    timeout: 2000,
+  },
+  (res) => {
+    let body = "";
+    res.setEncoding("utf8");
+    res.on("data", (chunk) => { body += chunk; if (body.length > 4096) req.destroy(); });
+    res.on("end", () => done({ status: res.statusCode, body }));
+  },
+);
+req.on("timeout", () => { req.destroy(new Error("timeout")); });
+req.on("error", (err) => done({ error: String((err && err.message) || err) }));
+req.end();
+`;
+function unavailable(socketPath, detail) {
+    return { verdict: "unavailable", socketPath, detail };
+}
+/**
+ * True when a metadata body reports the managed runtime.
+ *
+ * Accepts a JSON object carrying a `runtime` (or `agentRuntime` / `agent_runtime`)
+ * field and a bare string body, because the exact response shape is documented
+ * only as "`agent/runtime` is always `managed`". Over-matching here denies host
+ * credentials, which is the safe direction.
+ */
+export function bodyReportsManagedRuntime(body) {
+    const text = body.trim();
+    if (text.length === 0)
+        return false;
+    if (text.toLowerCase() === MANAGED_RUNTIME_VALUE)
+        return true;
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return false;
+    }
+    if (typeof parsed === "string")
+        return parsed.trim().toLowerCase() === MANAGED_RUNTIME_VALUE;
+    if (typeof parsed !== "object" || parsed === null)
+        return false;
+    const record = parsed;
+    for (const key of ["runtime", "agentRuntime", "agent_runtime"]) {
+        const value = record[key];
+        if (typeof value === "string" && value.trim().toLowerCase() === MANAGED_RUNTIME_VALUE) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Interpret the reader child's stdout, or null when it is not a usable object.
+ *
+ * Exported for the same reason as `bodyReportsManagedRuntime`: it is the parsing
+ * step and it has to be provably total. `JSON.parse("null")` returns null
+ * without throwing, so a bare try/catch around the parse would still leave the
+ * field reads that follow able to throw -- and a probe that throws aborts
+ * classification instead of failing closed.
+ */
+export function parseProbeResponse(stdout) {
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+        return null;
+    return parsed;
+}
+/**
+ * Per-process memo of *positive* managed reads, keyed by socket path.
+ *
+ * Only the `managed` verdict is memoized, and that asymmetry is the safety
+ * property. A managed VM cannot stop being managed mid-process, so holding that
+ * deny costs nothing and keeps classification to one child spawn per socket.
+ *
+ * Every other verdict says only that the API did not assert `managed` on that
+ * attempt: the socket may not have been listening yet, or the read may have
+ * failed outright. Memoizing one would let a transient miss suppress a later
+ * deny -- a managed VM whose first probe lost the startup race would stay
+ * ambiguous for the life of the process, and an explicit `host-gh` selection
+ * would then hand it host credentials. Re-probing an ambiguous runtime costs a
+ * child spawn bounded by the timeouts below; caching one is unbounded in the
+ * only direction that matters.
+ */
+const managedVerdictMemo = new Map();
+/** Clear the probe memo. Test seam only. */
+export function resetManagedRuntimeProbeCache() {
+    managedVerdictMemo.clear();
+}
+/** Default managed-runtime probe. Never throws. */
+export const probeManagedRuntime = (environ) => {
+    const socketPath = (environ[MANAGED_RUNTIME_SOCKET_ENV] ?? "").trim();
+    if (socketPath.length === 0) {
+        return unavailable(null, `${MANAGED_RUNTIME_SOCKET_ENV} is not set; runtime not asserted`);
+    }
+    const memoized = managedVerdictMemo.get(socketPath);
+    if (memoized !== undefined)
+        return memoized;
+    const result = readManagedRuntime(socketPath);
+    if (result.verdict === "managed")
+        managedVerdictMemo.set(socketPath, result);
+    return result;
+};
+function readManagedRuntime(socketPath) {
+    let result;
+    try {
+        result = spawnSync(process.execPath, ["-e", READER_SCRIPT], {
+            env: {
+                ...process.env,
+                DEFT_PROBE_SOCKET: socketPath,
+                DEFT_PROBE_PATH: MANAGED_RUNTIME_PATH,
+            },
+            encoding: "utf8",
+            timeout: 3000,
+            stdio: ["ignore", "pipe", "pipe"],
+            windowsHide: true,
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return unavailable(socketPath, `metadata probe failed to start: ${message}`);
+    }
+    const stdout = typeof result.stdout === "string" ? result.stdout : "";
+    if (stdout.trim().length === 0) {
+        return unavailable(socketPath, `${MANAGED_RUNTIME_PATH} returned no response`);
+    }
+    const payload = parseProbeResponse(stdout);
+    if (payload === null) {
+        return unavailable(socketPath, `${MANAGED_RUNTIME_PATH} response was unparseable`);
+    }
+    if (typeof payload.error === "string") {
+        return unavailable(socketPath, `${MANAGED_RUNTIME_PATH} unreachable: ${payload.error}`);
+    }
+    if (payload.status !== 200) {
+        return unavailable(socketPath, `${MANAGED_RUNTIME_PATH} returned status ${payload.status}`);
+    }
+    if (bodyReportsManagedRuntime(payload.body ?? "")) {
+        return {
+            verdict: "managed",
+            socketPath,
+            detail: `${MANAGED_RUNTIME_PATH} reported ${MANAGED_RUNTIME_VALUE}`,
+        };
+    }
+    return {
+        verdict: "not-managed",
+        socketPath,
+        detail: `${MANAGED_RUNTIME_PATH} did not report ${MANAGED_RUNTIME_VALUE}`,
+    };
+}
+/**
+ * True when an operator or dispatcher explicitly selected host-gh for this
+ * execution environment. This resolves an *ambiguous* runtime only; it can
+ * never override a positive managed-runtime read.
+ */
+export function hasExplicitHostGhSelection(environ) {
+    return (environ[GITHUB_AUTH_MODE_ENV] ?? "").trim().toLowerCase() === HOST_GH_SELECTION;
+}
+/** Remediation naming the opt-in, for operator-visible not-ready output. */
+export const EXPLICIT_SELECTION_REMEDIATION = `Remediation for an ambiguous Cursor runtime (#3859):\n` +
+    `  - CURSOR_AGENT is set but the ${MANAGED_RUNTIME_SOCKET_ENV} metadata API did not report\n` +
+    `    "${MANAGED_RUNTIME_VALUE}", so this runtime could be local desktop, a self-hosted\n` +
+    `    worker, or an unreachable managed VM. Deft will not guess from the OS.\n` +
+    `  - On a machine you control, where the host gh credential store is the right\n` +
+    `    credential, opt in explicitly: set ${GITHUB_AUTH_MODE_ENV}=${HOST_GH_SELECTION}\n` +
+    `  - Dispatchers should export the same github_auth_mode label they record in the\n` +
+    `    dispatch envelope\n` +
+    `  - A positive managed-runtime read always wins; this opt-in cannot override it`;
+//# sourceMappingURL=cursor-managed-runtime.js.map

package/dist/platform/index.d.ts

@@ -1,6 +1,7 @@
 export * from "./agents-consumer-header.js";
 export * from "./agents-md.js";
 export * from "./constants.js";
+export * from "./cursor-managed-runtime.js";
 export * from "./host-content-surface.js";
 export * from "./ip-risk.js";
 export * from "./linear-scan.js";

package/dist/platform/index.js

@@ -1,6 +1,7 @@
 export * from "./agents-consumer-header.js";
 export * from "./agents-md.js";
 export * from "./constants.js";
+export * from "./cursor-managed-runtime.js";
 export * from "./host-content-surface.js";
 export * from "./ip-risk.js";
 export * from "./linear-scan.js";

package/dist/platform/platform-capabilities.d.ts

@@ -1,3 +1,4 @@
+import { type ManagedRuntimeProbe } from "./cursor-managed-runtime.js";
 import { type ShellContext } from "./shell-context.js";
 export interface UidMapEntry {
     readonly insideId: number;
@@ -14,6 +15,8 @@ export interface RuntimeCapabilityReport {
     readonly hostPlatform: NodeJS.Platform;
     readonly shell: ShellContext;
     readonly runtimeMode: string;
+    /** Stable id naming why `runtimeMode` was chosen (#3859). */
+    readonly runtimeModeReason: string;
     readonly identityKind: string;
     readonly effectiveUid: number | null;
     readonly effectiveUsername: string | null;
@@ -33,7 +36,24 @@ export declare function classifyIdentityKind(options: {
     effectiveUid: number | null;
     sandboxUidRemap: boolean;
 }): string;
-export declare function classifyRuntimeMode(environ: Readonly<Record<string, string>>, sandboxUidRemap: boolean): string;
+export interface RuntimeClassification {
+    readonly mode: string;
+    readonly reason: string;
+}
+/**
+ * Classify runtime mode and name the reason for the verdict (#3859).
+ *
+ * Ordering matches intake/platform-capabilities.ts: CI markers, then a positive
+ * managed-runtime read, then sandbox, then the ambiguous Cursor hop. The Cursor
+ * hop previously ran first here; it now runs last so neither a CI marker nor a
+ * managed read can be overridden by an explicit host-gh selection.
+ */
+export declare function classifyRuntime(environ: Readonly<Record<string, string>>, sandboxUidRemap: boolean, options?: {
+    managedRuntimeProbe?: ManagedRuntimeProbe;
+}): RuntimeClassification;
+export declare function classifyRuntimeMode(environ: Readonly<Record<string, string>>, sandboxUidRemap: boolean, options?: {
+    managedRuntimeProbe?: ManagedRuntimeProbe;
+}): string;
 export interface ProbeRuntimeOptions {
     readonly environ?: Readonly<Record<string, string>>;
     readonly platform?: NodeJS.Platform;
@@ -43,6 +63,8 @@ export interface ProbeRuntimeOptions {
     readonly effectiveUidOverride?: number | null;
     readonly effectiveUsername?: string | null;
     readonly getuid?: () => number;
+    /** Injectable managed-runtime probe (#3859). Defaults to the metadata read. */
+    readonly managedRuntimeProbe?: ManagedRuntimeProbe;
 }
 export declare function probeRuntimeCapabilities(options?: ProbeRuntimeOptions): RuntimeCapabilityReport;
 export declare function getPlatformCapabilities(options?: ProbeRuntimeOptions): RuntimeCapabilityReport;