@deftai/directive-core 0.106.0 → 0.107.0

package/dist/session/verify-session-ritual.js

@@ -10,9 +10,10 @@ import { pythonJsonDump } from "./json.js";
 import { ENV_SESSION_POSTURE, readOnlyPostureMessage, resolveSessionPosture, ritualStateIsPostureAuthority, } from "./posture.js";
 import { defaultRitualRunner } from "./ritual-entrypoint.js";
 import { readRitualState, ritualStateMarksRearmNeeded, ritualStatePath, ritualStep, writeRitualState, } from "./ritual-sentinel.js";
-import { formatSessionStartRecoveryCommand, GATED_STEPS, QUICK_STEPS, } from "./session-start.js";
+import { formatSessionStartRecoveryCommand, GATED_STEPS, QUICK_STEPS, WRITE_GATED_EXECUTE_STEPS, WRITE_GATED_REQUIRED_STEPS, } from "./session-start.js";
 import { resolveSessionRitualStalenessHours } from "./staleness.js";
 export { formatCacheFetchAllRecoveryCommand, recoveryHintForStaleFailure, } from "./cache-recovery.js";
+export { WRITE_GATED_EXECUTE_STEPS, WRITE_GATED_REQUIRED_STEPS };
 export const ENV_SKIP = "DEFT_SESSION_RITUAL_SKIP";
 export { ENTRYPOINT_TIMEOUT_EXIT_CODE, ENTRYPOINT_TIMEOUT_SECONDS, } from "./ritual-entrypoint.js";
 export const GATED_ENTRYPOINT_COMMANDS = {
@@ -244,7 +245,8 @@ function evaluateLoadedState(projectRoot, state, input) {
         }
     }
     if (input.tier === "gated") {
-        for (const stepName of GATED_STEPS) {
+        const requiredGated = input.requiredGatedSteps ?? GATED_STEPS;
+        for (const stepName of requiredGated) {
             const step = state.gatedSteps[stepName];
             if (!stepPasses(step)) {
                 return {
@@ -261,12 +263,31 @@ function evaluateLoadedState(projectRoot, state, input) {
         recoveryTier: null,
     };
 }
+/**
+ * Options for the write/spawn mutation verifier (#3738).
+ * Required set omits `cache_fresh`; execution authority is `agent_hooks` only.
+ */
+export function writeGateRitualOptions(extras = {}) {
+    return {
+        ...extras,
+        tier: "gated",
+        posture: extras.posture ?? "mutation",
+        requiredGatedSteps: WRITE_GATED_REQUIRED_STEPS,
+        executeGatedSteps: WRITE_GATED_EXECUTE_STEPS,
+        // Write dispatch already refuses skip (dispatcher passes bypass: false).
+        // Default the same here so CI DEFT_SESSION_RITUAL_SKIP=1 cannot empty
+        // the execute loop in tests that use this helper (#3738).
+        bypass: extras.bypass ?? false,
+        envSkip: extras.envSkip ?? "",
+    };
+}
 /**
  * Read-only ritual-state inspection for host hooks.
  *
  * Unlike {@link verifySessionRitual}, this never runs missing gated entrypoints
- * and never rewrites `.deft/ritual-state.json`. A PreToolUse decision must be a
- * probe, not a hidden `doctor` / cache-refresh mutation boundary.
+ * and never rewrites `.deft/ritual-state.json`. Write dispatch does **not** use
+ * this function: it must still execute `agent_hooks` (#3738). A PreToolUse
+ * decision must not become a hidden `doctor` / cache-refresh mutation boundary.
  */
 export function inspectSessionRitual(projectRoot, options = {}) {
     const tier = options.tier ?? "quick";
@@ -442,7 +463,10 @@ export function verifySessionRitual(projectRoot, options = {}) {
         const runCmd = options.runner ?? defaultRitualRunner;
         const forced = new Set(options.forceGatedSteps ?? []);
         const detect = options.detectWorkSelection ?? detectWorkSelection;
+        const executable = new Set(options.executeGatedSteps ?? [...GATED_STEPS]);
         for (const stepName of GATED_STEPS) {
+            if (!executable.has(stepName))
+                continue;
             const step = gated[stepName];
             if (step?.deferred_reason && stepName !== "agent_hooks")
                 continue;
@@ -519,6 +543,7 @@ export function verifySessionRitual(projectRoot, options = {}) {
         now: instant,
         runGit: options.runGit,
         rebindForwardHead: true,
+        requiredGatedSteps: options.requiredGatedSteps,
     });
     if (isBypassed) {
         return {

package/dist/swarm/launch.d.ts

@@ -1,3 +1,4 @@
+import { type ExpectedGithubWorkerPrincipal, type GhRunner, GITHUB_AUTH_MODE_HOST_GH, GITHUB_AUTH_MODE_INJECTED_TOKEN } from "../intake/github-auth-modes.js";
 import { EXIT_CONFIG_ERROR, EXIT_GATE_FAILED, EXIT_OK } from "./constants.js";
 import { type WorktreeRecord } from "./worktrees.js";
 export interface ResolvedStory {
@@ -21,6 +22,70 @@ export type RuntimeAuthProbeFn = () => [string, string];
 export declare const defaultPreflightGate: PreflightGateFn;
 export declare const defaultReadinessGate: ReadinessGateFn;
 export declare const defaultRuntimeAuthProbe: RuntimeAuthProbeFn;
+export type WorkerCredentialDispatchPath = "grok-build" | "local-hybrid";
+/**
+ * Dispatch-envelope half of the runtime / GitHub auth-mode contract (#1557 / #1351).
+ * Policy labels only — never a token value.
+ */
+export declare function formatDispatchAuthEnvelope(fields: {
+    runtimeMode: string;
+    githubAuthMode: string;
+    expectedGithubLogin?: string | null;
+}): string;
+export interface WorkerCredentialInjectionRequest {
+    environ?: NodeJS.ProcessEnv;
+    githubAuthMode: string;
+    runtimeMode?: string | null;
+    dispatchPath?: WorkerCredentialDispatchPath;
+    expectedPrincipal?: ExpectedGithubWorkerPrincipal | null;
+    repo?: string;
+    runGh?: GhRunner;
+    cwd?: string;
+}
+export type WorkerCredentialInjectionResult = {
+    ok: true;
+    injected: true;
+    githubAuthMode: typeof GITHUB_AUTH_MODE_INJECTED_TOKEN;
+    runtimeMode: string | null;
+    expectedLogin: string;
+    spawnEnv: {
+        GH_TOKEN: string;
+        GITHUB_TOKEN: string;
+        GH_ENTERPRISE_TOKEN: string;
+        DEFT_EXPECTED_GITHUB_LOGIN: string;
+    };
+    envelopeSection: string;
+} | {
+    ok: true;
+    injected: false;
+    githubAuthMode: typeof GITHUB_AUTH_MODE_HOST_GH;
+    runtimeMode: string | null;
+    expectedLogin: string | null;
+    spawnEnv: Record<string, never>;
+    envelopeSection: string;
+} | {
+    ok: false;
+    blocked: true;
+    githubAuthMode: string;
+    runtimeMode: string | null;
+    missingCredential: string;
+    remedy: string;
+    detail: string;
+    failureKind: string | null;
+    envelopeSection: string;
+};
+/**
+ * Validate a held user-bearing worker credential and prepare spawn-time injection (#1351).
+ *
+ * Comparison is opt-in on the validator. This path always stamps
+ * `DEFT_EXPECTED_GITHUB_LOGIN` after a successful user-principal check so the
+ * worker envelope does not inherit "any user token is approved."
+ *
+ * Installation credentials fail closed via the existing validator (#3693).
+ * Token values belong only in the returned `spawnEnv` — never in prompts,
+ * transcripts, or manifest entries.
+ */
+export declare function prepareWorkerCredentialInjection(request: WorkerCredentialInjectionRequest): WorkerCredentialInjectionResult;
 /**
  * True when a brief in `xbrief/completed/` (or the legacy `vbrief/completed/`)
  * references the given issue number in its `references[]` / `Traces`. Used by
@@ -74,6 +139,7 @@ export declare function buildManifest(resolved: readonly ResolvedStory[], option
     modelSource?: string | null;
     runtimeMode?: string | null;
     githubAuthMode?: string | null;
+    expectedGithubLogin?: string | null;
     occupancySessionId?: string | null;
 }): Record<string, unknown>[];
 export declare function orderCohort(resolved: readonly ResolvedStory[], _projectRoot: string): ResolvedStory[];
@@ -103,6 +169,9 @@ export interface LaunchArgs {
      * Defaults to `process.env` when unset.
      */
     environ?: NodeJS.ProcessEnv;
+    /** Optional gh runner for identity-bound credential injection (#1351). */
+    runGh?: GhRunner;
+    expectedPrincipal?: ExpectedGithubWorkerPrincipal | null;
 }
 export declare function swarmLaunch(args: LaunchArgs): {
     exitCode: number;

package/dist/swarm/launch.js

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 import { containedWrite } from "../fs/contained-write.js";
-import { inferGithubAuthMode } from "../intake/github-auth-modes.js";
+import { ENV_EXPECTED_GITHUB_LOGIN, FAILURE_INSTALLATION_IDENTITY_UNVERIFIABLE, FAILURE_MISSING_INJECTED_TOKEN, findInjectedToken, GITHUB_AUTH_MODE_HOST_GH, GITHUB_AUTH_MODE_INJECTED_TOKEN, inferGithubAuthMode, validateGithubAuthForWorker, } from "../intake/github-auth-modes.js";
 import { getPlatformCapabilities } from "../intake/platform-capabilities.js";
 import { hasArtifactSuffix, resolveLifecycleFolder, stripArtifactSuffix, } from "../layout/resolve.js";
 import { evaluate as preflightEvaluate } from "../preflight/evaluate.js";
@@ -25,6 +25,164 @@ export const defaultRuntimeAuthProbe = () => {
     const report = getPlatformCapabilities();
     return [report.runtimeMode, inferGithubAuthMode(report)];
 };
+const CREDENTIAL_VALUE_PATTERN = /^(ghp_|gho_|ghu_|ghs_|github_pat_)/i;
+const INJECTION_MISSING_CREDENTIAL = "GH_TOKEN (or GITHUB_TOKEN / GH_ENTERPRISE_TOKEN)";
+const INJECTION_DISPATCHER_REMEDY = "Dispatcher-side remedy: load an approved user-bearing worker credential into the dispatcher environment, then call prepareWorkerCredentialInjection before spawn. Do not fall back to the host gh token or continue under the maintainer identity. Installation credentials are not injectable; see #3693.";
+const HELD_WORKER_TOKEN_VARS = [
+    "GH_TOKEN",
+    "GITHUB_TOKEN",
+    "GH_ENTERPRISE_TOKEN",
+    "GITHUB_ENTERPRISE_TOKEN",
+];
+function looksLikeCredentialValue(value) {
+    return CREDENTIAL_VALUE_PATTERN.test(value.trim());
+}
+function assertNoCredentialValue(value, label) {
+    if (looksLikeCredentialValue(value)) {
+        throw new Error(`${label} must not contain a credential value`);
+    }
+}
+function sanitizeEnvelopeField(value, label) {
+    const cleaned = value.replace(/\r?\n/g, " ").trim();
+    assertNoCredentialValue(cleaned, label);
+    return cleaned;
+}
+/**
+ * Bind validation to the selected token. Stamp it into every gh token slot and
+ * drop GH_CONFIG_DIR so a host/enterprise config cannot authenticate as someone
+ * else. GH_HOST stays: it selects the API host, not the secret.
+ */
+function isolateHeldWorkerToken(environ, token) {
+    const isolated = { ...environ };
+    for (const name of HELD_WORKER_TOKEN_VARS) {
+        isolated[name] = token;
+    }
+    delete isolated.GH_CONFIG_DIR;
+    return isolated;
+}
+function boundWorkerSpawnEnv(token, expectedLogin) {
+    return {
+        GH_TOKEN: token,
+        GITHUB_TOKEN: token,
+        GH_ENTERPRISE_TOKEN: token,
+        [ENV_EXPECTED_GITHUB_LOGIN]: expectedLogin,
+    };
+}
+/**
+ * Dispatch-envelope half of the runtime / GitHub auth-mode contract (#1557 / #1351).
+ * Policy labels only — never a token value.
+ */
+export function formatDispatchAuthEnvelope(fields) {
+    const runtimeMode = sanitizeEnvelopeField(fields.runtimeMode, "runtime_mode");
+    const githubAuthMode = sanitizeEnvelopeField(fields.githubAuthMode, "github_auth_mode");
+    const lines = [
+        "## Runtime and GitHub auth mode",
+        "",
+        `- runtime_mode: ${runtimeMode}`,
+        `- github_auth_mode: ${githubAuthMode}`,
+    ];
+    if (fields.expectedGithubLogin !== undefined && fields.expectedGithubLogin !== null) {
+        const login = sanitizeEnvelopeField(fields.expectedGithubLogin, "expected_github_login");
+        if (login.length > 0) {
+            lines.push(`- expected_github_login: ${login}`);
+        }
+    }
+    return `${lines.join("\n")}\n`;
+}
+function blockedInjection(fields) {
+    const detail = fields.detail.startsWith("BLOCKED") ? fields.detail : `BLOCKED: ${fields.detail}`;
+    return {
+        ok: false,
+        blocked: true,
+        githubAuthMode: fields.githubAuthMode,
+        runtimeMode: fields.runtimeMode,
+        missingCredential: fields.missingCredential ?? INJECTION_MISSING_CREDENTIAL,
+        remedy: INJECTION_DISPATCHER_REMEDY,
+        detail,
+        failureKind: fields.failureKind,
+        envelopeSection: formatDispatchAuthEnvelope({
+            runtimeMode: fields.runtimeMode ?? "unknown",
+            githubAuthMode: fields.githubAuthMode,
+        }),
+    };
+}
+/**
+ * Validate a held user-bearing worker credential and prepare spawn-time injection (#1351).
+ *
+ * Comparison is opt-in on the validator. This path always stamps
+ * `DEFT_EXPECTED_GITHUB_LOGIN` after a successful user-principal check so the
+ * worker envelope does not inherit "any user token is approved."
+ *
+ * Installation credentials fail closed via the existing validator (#3693).
+ * Token values belong only in the returned `spawnEnv` — never in prompts,
+ * transcripts, or manifest entries.
+ */
+export function prepareWorkerCredentialInjection(request) {
+    const environ = request.environ ?? process.env;
+    const runtimeMode = request.runtimeMode ?? null;
+    const token = findInjectedToken(environ);
+    const grokBuild = request.dispatchPath === "grok-build";
+    const effectiveMode = grokBuild || token !== null ? GITHUB_AUTH_MODE_INJECTED_TOKEN : request.githubAuthMode;
+    if (effectiveMode === GITHUB_AUTH_MODE_HOST_GH && token === null) {
+        return {
+            ok: true,
+            injected: false,
+            githubAuthMode: GITHUB_AUTH_MODE_HOST_GH,
+            runtimeMode,
+            expectedLogin: null,
+            spawnEnv: {},
+            envelopeSection: formatDispatchAuthEnvelope({
+                runtimeMode: runtimeMode ?? "local-unsandboxed",
+                githubAuthMode: GITHUB_AUTH_MODE_HOST_GH,
+            }),
+        };
+    }
+    if (token === null) {
+        return blockedInjection({
+            githubAuthMode: GITHUB_AUTH_MODE_INJECTED_TOKEN,
+            runtimeMode,
+            failureKind: FAILURE_MISSING_INJECTED_TOKEN,
+            missingCredential: INJECTION_MISSING_CREDENTIAL,
+            detail: "missing worker credential GH_TOKEN (or GITHUB_TOKEN / GH_ENTERPRISE_TOKEN) for a write-requiring injected-token dispatch",
+        });
+    }
+    const isolatedEnviron = isolateHeldWorkerToken(environ, token);
+    const validated = validateGithubAuthForWorker(GITHUB_AUTH_MODE_INJECTED_TOKEN, {
+        environ: isolatedEnviron,
+        runtimeReport: { runtimeMode: runtimeMode ?? "cloud-headless" },
+        repo: request.repo,
+        runGh: request.runGh,
+        expectedPrincipal: request.expectedPrincipal,
+        cwd: request.cwd,
+    });
+    if (!validated.ok || validated.login === null || validated.login.trim().length === 0) {
+        const installation = validated.failureKind === FAILURE_INSTALLATION_IDENTITY_UNVERIFIABLE;
+        return blockedInjection({
+            githubAuthMode: GITHUB_AUTH_MODE_INJECTED_TOKEN,
+            runtimeMode,
+            failureKind: validated.failureKind,
+            detail: installation
+                ? `${validated.detail} Installation credentials are not injectable (#3693).`
+                : validated.detail,
+        });
+    }
+    const expectedLogin = validated.login.trim();
+    assertNoCredentialValue(expectedLogin, "expected_github_login");
+    const spawnEnv = boundWorkerSpawnEnv(token, expectedLogin);
+    return {
+        ok: true,
+        injected: true,
+        githubAuthMode: GITHUB_AUTH_MODE_INJECTED_TOKEN,
+        runtimeMode,
+        expectedLogin,
+        spawnEnv,
+        envelopeSection: formatDispatchAuthEnvelope({
+            runtimeMode: runtimeMode ?? "cloud-headless",
+            githubAuthMode: GITHUB_AUTH_MODE_INJECTED_TOKEN,
+            expectedGithubLogin: expectedLogin,
+        }),
+    };
+}
 function loadJson(path) {
     try {
         const data = JSON.parse(readFileSync(path, "utf8"));
@@ -498,6 +656,10 @@ export function buildManifest(resolved, options) {
         if (options.githubAuthMode !== undefined && options.githubAuthMode !== null) {
             entry.github_auth_mode = options.githubAuthMode;
         }
+        if (options.expectedGithubLogin !== undefined && options.expectedGithubLogin !== null) {
+            assertNoCredentialValue(options.expectedGithubLogin, "expected_github_login");
+            entry.expected_github_login = options.expectedGithubLogin;
+        }
         manifest.push(entry);
     }
     return manifest;
@@ -692,6 +854,33 @@ export function swarmLaunch(args) {
             stderr: `${occupancy.message}\n`,
         };
     }
+    const launchEnviron = args.environ ?? process.env;
+    let expectedGithubLogin = null;
+    // Only the injected-token launch path auto-validates (and fail-closes on a
+    // missing token). An ambient GH_TOKEN on a host-gh probe is often the
+    // maintainer workaround, not a worker credential; local-hybrid injection is
+    // the explicit prepareWorkerCredentialInjection call.
+    if (githubAuthMode === GITHUB_AUTH_MODE_INJECTED_TOKEN) {
+        const injection = prepareWorkerCredentialInjection({
+            environ: launchEnviron,
+            githubAuthMode,
+            runtimeMode,
+            dispatchPath: "grok-build",
+            runGh: args.runGh,
+            expectedPrincipal: args.expectedPrincipal,
+            cwd: projectRoot,
+        });
+        if (!injection.ok) {
+            return {
+                exitCode: EXIT_GATE_FAILED,
+                stdout: "",
+                stderr: `${injection.detail}\n${injection.remedy}\n`,
+            };
+        }
+        if (injection.injected) {
+            expectedGithubLogin = injection.expectedLogin;
+        }
+    }
     const manifest = buildManifest(ordered, {
         projectRoot,
         group: args.group ?? null,
@@ -708,6 +897,7 @@ export function swarmLaunch(args) {
         modelSource,
         runtimeMode,
         githubAuthMode,
+        expectedGithubLogin,
         occupancySessionId: occupancy.sessionId,
     });
     const rendered = `${JSON.stringify(manifest, null, 2)}\n`;

package/dist/triage/actions/index.d.ts

@@ -38,6 +38,10 @@ export declare function reset(issueNumber: number, repo: string, deps: TriageAct
     actor?: string | null;
     projectRoot?: string;
 }): string;
+/** Success line for ``triage:accept``, plus the optional design-critique affordance (#3708). */
+export declare function formatAcceptOutput(issueNumber: number, repo: string, decisionId: string, options?: {
+    autoPromote?: boolean;
+}): string;
 /** Format a decision entry for CLI ``status`` / ``history`` output. */
 export declare function formatDecision(entry: AuditEntry | null): string;
 //# sourceMappingURL=index.d.ts.map

package/dist/triage/actions/index.js

@@ -407,6 +407,12 @@ export function reset(issueNumber, repo, deps, options = {}) {
     });
     return deps.candidatesLog.append(entry, { path: logPath });
 }
+/** Success line for ``triage:accept``, plus the optional design-critique affordance (#3708). */
+export function formatAcceptOutput(issueNumber, repo, decisionId, options = {}) {
+    const promoteNote = options.autoPromote === true ? " + auto-promote" : "";
+    return (`accept #${issueNumber} (${repo}) -> ${decisionId}${promoteNote}\n` +
+        "optional: deft-directive-design-critique (declining writes nothing)");
+}
 /** Format a decision entry for CLI ``status`` / ``history`` output. */
 export function formatDecision(entry) {
     if (entry === null) {

package/dist/triage/evaluate/evaluate.d.ts

@@ -0,0 +1,11 @@
+import { type EvaluateOptions, type EvaluateResult } from "./types.js";
+export declare class EvaluateError extends Error {
+    name: string;
+}
+/**
+ * Stage A parent: WIP census + GitHub REST + worktree fan-out + sink write.
+ * Evaluators never receive the WIP census.
+ */
+export declare function evaluateIssues(options: EvaluateOptions): Promise<EvaluateResult>;
+export declare function renderEvaluateText(result: EvaluateResult): string;
+//# sourceMappingURL=evaluate.d.ts.map

package/dist/triage/evaluate/evaluate.js

@@ -0,0 +1,169 @@
+import { randomUUID } from "node:crypto";
+import { runText } from "../../swarm/subprocess.js";
+import { defaultGitRunner } from "../../swarm/worktrees.js";
+import { defaultGithubReader, pullsMentioning } from "./github.js";
+import { sha12Of, sinkDir } from "./paths.js";
+import { gcStaleSha12Dirs, writeInvocationSink } from "./sink.js";
+import { DEFAULT_CONCURRENCY, ORIGIN_MASTER, } from "./types.js";
+import { evaluateValidity, joinValidityWithGithub } from "./validity.js";
+import { buildValueAdvice } from "./value.js";
+import { collectWipCensus, wipHitsForIssue } from "./wip-census.js";
+import { addEvaluatorWorktree, removeEvaluatorWorktree } from "./worktrees.js";
+export class EvaluateError extends Error {
+    name = "EvaluateError";
+}
+function resolveOriginSha(projectRoot, git) {
+    const proc = git(["rev-parse", ORIGIN_MASTER], projectRoot);
+    if (proc.returncode !== 0) {
+        throw new EvaluateError(`could not resolve ${ORIGIN_MASTER}: ${proc.stderr.trim() || "<no stderr>"}`);
+    }
+    return proc.stdout.trim();
+}
+function defaultSessionStart(worktreePath) {
+    const proc = runText(["deft", "session:start", "--read-only"], { cwd: worktreePath });
+    if (proc.returncode !== 0) {
+        throw new EvaluateError(`session:start --read-only failed in ${worktreePath}: ${proc.stderr.trim() || "<no stderr>"}`);
+    }
+}
+async function mapPool(items, limit, fn) {
+    const results = new Array(items.length);
+    let next = 0;
+    const worker = async () => {
+        while (true) {
+            const index = next;
+            next += 1;
+            if (index >= items.length) {
+                return;
+            }
+            results[index] = await fn(items[index], index);
+        }
+    };
+    const n = Math.max(1, Math.min(limit, Math.max(items.length, 1)));
+    await Promise.all(Array.from({ length: n }, () => worker()));
+    return results;
+}
+function collectGithubForRepo(repo, issues, reader) {
+    const views = issues.map((n) => reader.viewIssue(repo, n));
+    const openPulls = reader.listOpenPulls(repo);
+    reader.listOpenIssues(repo);
+    return { issues: views, openPulls };
+}
+/**
+ * Stage A parent: WIP census + GitHub REST + worktree fan-out + sink write.
+ * Evaluators never receive the WIP census.
+ */
+export async function evaluateIssues(options) {
+    const issues = [...new Set(options.issues)].filter((n) => Number.isInteger(n) && n > 0);
+    if (issues.length === 0) {
+        throw new EvaluateError("triage:evaluate requires one or more issue numbers");
+    }
+    const concurrency = options.concurrency ?? DEFAULT_CONCURRENCY;
+    if (!Number.isInteger(concurrency) || concurrency < 1) {
+        throw new EvaluateError("--concurrency must be a positive integer");
+    }
+    const git = options.git ?? defaultGitRunner;
+    const sessionStart = options.sessionStart ?? defaultSessionStart;
+    const github = options.github ?? defaultGithubReader();
+    const originSha = resolveOriginSha(options.projectRoot, git);
+    const sha12 = sha12Of(originSha);
+    const invocationId = options.invocationId ?? randomUUID();
+    const wip = collectWipCensus(options.projectRoot, issues);
+    const githubViews = collectGithubForRepo(options.repo, issues, github);
+    const viewByIssue = new Map(githubViews.issues.map((snap) => [snap.number, snap]));
+    const runOne = async (issue) => {
+        let worktreePath = null;
+        let teardownError = null;
+        const snap = viewByIssue.get(issue) ?? null;
+        const pulls = pullsMentioning(githubViews.openPulls, issue);
+        let verdict;
+        try {
+            worktreePath = addEvaluatorWorktree(options.projectRoot, issue, invocationId, originSha, git);
+            sessionStart(worktreePath);
+            const validity = evaluateValidity(worktreePath, issue);
+            const joined = joinValidityWithGithub(validity, snap?.state ?? null);
+            const duplicates = snap?.duplicateOf !== null && snap?.duplicateOf !== undefined ? [snap.duplicateOf] : [];
+            verdict = {
+                issue,
+                sha12,
+                invocationId,
+                validity: joined,
+                wip: wipHitsForIssue(wip, issue),
+                github: snap,
+                openPulls: pulls,
+                duplicates,
+                value: buildValueAdvice(snap),
+                error: null,
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            verdict = {
+                issue,
+                sha12,
+                invocationId,
+                validity: null,
+                wip: wipHitsForIssue(wip, issue),
+                github: snap,
+                openPulls: pulls,
+                duplicates: [],
+                value: buildValueAdvice(snap),
+                error: message,
+            };
+        }
+        finally {
+            if (worktreePath !== null) {
+                try {
+                    removeEvaluatorWorktree(options.projectRoot, worktreePath, git);
+                }
+                catch (teardownErr) {
+                    teardownError = teardownErr instanceof Error ? teardownErr.message : String(teardownErr);
+                }
+            }
+        }
+        if (teardownError !== null) {
+            verdict = {
+                ...verdict,
+                error: verdict.error !== null ? `${verdict.error}; teardown: ${teardownError}` : teardownError,
+            };
+        }
+        return verdict;
+    };
+    try {
+        const verdicts = await mapPool(issues, concurrency, (issue) => runOne(issue));
+        const result = {
+            sha12,
+            invocationId,
+            originSha,
+            sinkDir: sinkDir(options.projectRoot, sha12, invocationId),
+            concurrency,
+            verdicts,
+        };
+        writeInvocationSink(options.projectRoot, result);
+        gcStaleSha12Dirs(options.projectRoot, sha12);
+        return result;
+    }
+    catch (err) {
+        gcStaleSha12Dirs(options.projectRoot, sha12);
+        throw err;
+    }
+}
+export function renderEvaluateText(result) {
+    const lines = [
+        `triage:evaluate sha12=${result.sha12} invocation=${result.invocationId} concurrency=${result.concurrency}`,
+        `sink: ${result.sinkDir}`,
+    ];
+    for (const verdict of result.verdicts) {
+        const state = verdict.validity?.state ?? "error";
+        const evidence = verdict.validity?.evidence ?? verdict.error ?? "";
+        const wip = verdict.wip.length > 0 ? ` wip=${verdict.wip.length}` : " wip=0";
+        lines.push(`#${verdict.issue} validity=${state}${wip} critique-recommend: ${verdict.value["critique-recommend"]}`);
+        if (evidence.length > 0) {
+            lines.push(`  ${evidence}`);
+        }
+        if (verdict.error !== null) {
+            lines.push(`  error: ${verdict.error}`);
+        }
+    }
+    return `${lines.join("\n")}\n`;
+}
+//# sourceMappingURL=evaluate.js.map

package/dist/triage/evaluate/github.d.ts

@@ -0,0 +1,16 @@
+import { type RunGhApiFn } from "../../scm/gh-rest.js";
+import type { GithubCensus, GithubIssueSnapshot, GithubPullSnapshot } from "./types.js";
+export declare function snapshotFromIssuePayload(raw: Record<string, unknown>): GithubIssueSnapshot;
+export declare function snapshotFromPullPayload(raw: Record<string, unknown>): GithubPullSnapshot;
+export interface GithubSeams {
+    readonly runGhApiFn?: RunGhApiFn;
+}
+/** GET-only GitHub census. Parent-owned. Never POST/PATCH/PUT/DELETE. */
+export declare function collectGithubCensus(repo: string, issues: readonly number[], seams?: GithubSeams): GithubCensus;
+export declare function defaultGithubReader(seams?: GithubSeams): {
+    viewIssue: (repo: string, n: number) => GithubIssueSnapshot;
+    listOpenIssues: (repo: string) => GithubIssueSnapshot[];
+    listOpenPulls: (repo: string) => GithubPullSnapshot[];
+};
+export declare function pullsMentioning(pulls: readonly GithubPullSnapshot[], issue: number): GithubPullSnapshot[];
+//# sourceMappingURL=github.d.ts.map