@deftai/directive-core 0.100.0 → 0.101.0

package/dist/product-first-done-gate/evaluate.js

@@ -0,0 +1,255 @@
+/**
+ * evaluate verify:ac — product-first acceptance gate (#3284).
+ *
+ * Runs plan.acceptance.commands (or #3267 literal ledger) via the shared
+ * literal-acceptance runner. Records source_rung in the result message.
+ * Project floor with empty commands is a soft pass (suite gates own the floor
+ * inside full `task check`); standalone done paths still surface the rung.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { basename, resolve } from "node:path";
+import { evaluateLiteralAcceptanceFromPlan, runLiteralAcceptanceCommands, } from "../literal-acceptance/index.js";
+import { maybeBankOnAcPass } from "../session/ac-pass-banking.js";
+import { readPlanAcceptance, validatePlanAcceptance } from "./acceptance.js";
+function asRecord(value) {
+    if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+        return value;
+    }
+    return null;
+}
+/**
+ * Evaluate product AC from an in-memory plan.
+ */
+export function evaluateVerifyAcFromPlan(plan, options = {}) {
+    const acceptance = readPlanAcceptance(plan);
+    const schemaErrors = validatePlanAcceptance(plan.acceptance ?? acceptance);
+    // Only hard-fail schema when an explicit plan.acceptance object exists.
+    if (plan.acceptance !== undefined && schemaErrors.length > 0) {
+        return {
+            ok: false,
+            code: 2,
+            message: `verify:ac config error (#3284): ${schemaErrors.join("; ")}`,
+            commands: [],
+            runs: [],
+            sourceRung: acceptance.source_rung,
+            noneStated: acceptance.none_stated,
+            acceptance,
+        };
+    }
+    const projectRoot = resolve(options.projectRoot ?? process.cwd());
+    // Prefer shared literal-acceptance path so safety / promotion rules stay one place.
+    // Empty plan.acceptance.commands still consults the #3267 rejected ledger
+    // (Greptile P1: rejected stated AC must never soft-pass).
+    // For derived/floor commands already on plan.acceptance, inject as explicit metadata
+    // if the literal ledger is empty of executables.
+    const base = evaluateLiteralAcceptanceFromPlan(plan, {
+        projectRoot,
+        runner: options.runner,
+        captureFromNarratives: options.captureFromNarratives,
+        quiet: options.quiet,
+    });
+    // When literal path had nothing executable but plan.acceptance has derived commands,
+    // run them directly with source=explicit semantics.
+    if (base.ok &&
+        base.runs.length === 0 &&
+        acceptance.commands.length > 0 &&
+        (acceptance.source_rung === "derived" || acceptance.source_rung === "project_floor")) {
+        const runner = options.runner;
+        const direct = runLiteralAcceptanceCommands(acceptance.commands.map((c) => ({
+            command: c.command,
+            cwd: c.cwd ?? null,
+            expectedStdout: c.expectedStdout ?? null,
+            expectedExitCode: c.expectedExitCode ?? 0,
+            source: "explicit",
+            sourceSpan: "plan.acceptance.commands",
+        })), { projectRoot, runner, allowTaskStatement: options.allowTaskStatement });
+        return annotate(direct, acceptance, options.quiet);
+    }
+    // Check composition: mid-story unpromoted capture-only may soft-pass so the
+    // framework graph is not deadlocked before agents promote peers.
+    // Greptile P1 #3284: safety-rejected stated commands NEVER soft-pass — they
+    // block product verification until a safe alternative is promoted.
+    if (options.checkIntegrated === true && !base.ok && base.runs.length === 0) {
+        const hasRejected = (base.rejected?.length ?? 0) > 0;
+        if (hasRejected) {
+            return annotate(base, acceptance, options.quiet);
+        }
+        const unpromoted = /capture-only|task_statement|no matching agent-promoted/i.test(base.message) ||
+            (base.commands.length > 0 && base.commands.every((c) => c.source === "task_statement"));
+        if (unpromoted || base.commands.length === 0) {
+            return {
+                ok: true,
+                code: 0,
+                message: options.quiet
+                    ? ""
+                    : `verify:ac advisory (#3284 check-integrated): no executable AC peers yet ` +
+                        `(capture-only / empty). Done-gate standalone verify:ac still requires promotion. ` +
+                        `[rung=${acceptance.source_rung}]\n` +
+                        base.message,
+                commands: base.commands,
+                runs: [],
+                rejected: base.rejected,
+                sourceRung: acceptance.source_rung,
+                noneStated: acceptance.none_stated,
+                acceptance,
+            };
+        }
+    }
+    return annotate(base, acceptance, options.quiet);
+}
+function annotate(result, acceptance, quiet) {
+    const prefix = result.ok
+        ? `verify:ac passed (#3284) [rung=${acceptance.source_rung}]`
+        : `verify:ac FAILED (#3284) [rung=${acceptance.source_rung}]`;
+    let message = result.message;
+    if (!quiet) {
+        if (message.includes("#3267")) {
+            message = message.replace(/#3267/g, "#3284/#3267");
+        }
+        if (!message.startsWith("verify:ac")) {
+            message = `${prefix}\n${message}`;
+        }
+        else if (!message.includes(`rung=${acceptance.source_rung}`)) {
+            message = `${message} [rung=${acceptance.source_rung}]`;
+        }
+    }
+    else if (result.ok) {
+        message = "";
+    }
+    return {
+        ...result,
+        message,
+        sourceRung: acceptance.source_rung,
+        noneStated: acceptance.none_stated,
+        acceptance,
+    };
+}
+/**
+ * Evaluate from xBRIEF path.
+ */
+export function evaluateVerifyAcFromPath(xbriefPath, options = {}) {
+    const abs = resolve(xbriefPath);
+    if (!existsSync(abs)) {
+        if (options.softMissingXbrief) {
+            return softSkip(`xBRIEF not found: ${abs}`, options.quiet);
+        }
+        return {
+            ok: false,
+            code: 2,
+            message: `verify:ac: xBRIEF not found: ${abs}`,
+            commands: [],
+            runs: [],
+            sourceRung: "project_floor",
+            noneStated: true,
+            acceptance: { commands: [], none_stated: true, source_rung: "project_floor" },
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(abs, "utf8"));
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+            ok: false,
+            code: 2,
+            message: `verify:ac: unreadable xBRIEF (${msg}): ${abs}`,
+            commands: [],
+            runs: [],
+            sourceRung: "project_floor",
+            noneStated: true,
+            acceptance: { commands: [], none_stated: true, source_rung: "project_floor" },
+        };
+    }
+    const data = asRecord(parsed);
+    if (data === null) {
+        return {
+            ok: false,
+            code: 2,
+            message: `verify:ac: xBRIEF top-level is not an object: ${abs}`,
+            commands: [],
+            runs: [],
+            sourceRung: "project_floor",
+            noneStated: true,
+            acceptance: { commands: [], none_stated: true, source_rung: "project_floor" },
+        };
+    }
+    const plan = asRecord(data.plan);
+    if (plan === null) {
+        return {
+            ok: false,
+            code: 2,
+            message: `verify:ac: xBRIEF missing plan object: ${abs}`,
+            commands: [],
+            runs: [],
+            sourceRung: "project_floor",
+            noneStated: true,
+            acceptance: { commands: [], none_stated: true, source_rung: "project_floor" },
+        };
+    }
+    const result = evaluateVerifyAcFromPlan(plan, options);
+    return maybeAttachAcPassBank(result, plan, abs, options);
+}
+/**
+ * After executable AC pass, FINALIZE the banking checkpoint (#3285).
+ * Soft/advisory passes with zero runs do not bank. Fail-open on ledger errors.
+ */
+function maybeAttachAcPassBank(result, plan, xbriefPath, options) {
+    if (options.bankOnPass === false) {
+        return result;
+    }
+    if (!result.ok || result.runs.length === 0) {
+        return result;
+    }
+    const projectRoot = resolve(options.projectRoot ?? process.cwd());
+    const planId = typeof plan.id === "string" && plan.id.trim() ? plan.id.trim() : null;
+    const scopeId = options.bankScopeId?.trim() ||
+        planId ||
+        basename(xbriefPath)
+            .replace(/\.xbrief\.json$/i, "")
+            .replace(/\.vbrief\.json$/i, "");
+    try {
+        const banked = maybeBankOnAcPass({
+            projectRoot,
+            scopeId,
+            executableRuns: result.runs.length,
+            quiet: options.quiet,
+        });
+        if (options.quiet || banked.notes.length === 0) {
+            return result;
+        }
+        const extra = banked.notes.join("\n");
+        return {
+            ...result,
+            message: result.message ? `${result.message}\n${extra}` : extra,
+        };
+    }
+    catch (err) {
+        // Checkpoint is mandatory after executable AC green (#3285 Greptile residual).
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+            ...result,
+            ok: false,
+            code: 1,
+            message: `verify:ac bank checkpoint failed (#3285): ${msg}` +
+                (result.message ? `\n${result.message}` : ""),
+        };
+    }
+}
+function softSkip(detail, quiet) {
+    return {
+        ok: true,
+        code: 0,
+        message: quiet ? "" : `verify:ac skipped (#3284 soft-missing): ${detail}`,
+        commands: [],
+        runs: [],
+        sourceRung: "project_floor",
+        noneStated: true,
+        acceptance: { commands: [], none_stated: true, source_rung: "project_floor" },
+    };
+}
+/** Pure: product AC is required at every ceremony depth (#3284 / #3267 / #3156). */
+export function isVerifyAcRequiredAtCeremonyDepth(_depth) {
+    return true;
+}
+//# sourceMappingURL=evaluate.js.map

package/dist/product-first-done-gate/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Product-first done-gate (#3284).
+ *
+ * acceptance.commands schema, verify:ac evaluation, check-mode composition
+ * (AC-first, hygiene advisory under pressure, rapid=AC-only).
+ */
+export { attachPlanAcceptance, buildAcceptanceFromIntakeCapture, readPlanAcceptance, stampAcceptanceFromLiteralCapture, validatePlanAcceptance, } from "./acceptance.js";
+export { applyProductFirstGateMode, isHygieneGate, isProductAcGate, type ProductFirstCheckModeResolution, type ResolveProductFirstCheckModeInput, resolveProductFirstCheckMode, } from "./check-mode.js";
+export { type EvaluateVerifyAcOptions, evaluateVerifyAcFromPath, evaluateVerifyAcFromPlan, isVerifyAcRequiredAtCeremonyDepth, type VerifyAcResult, } from "./evaluate.js";
+export { type AcceptanceCommand, type AcSourceRung, ENV_CHECK_AC_ONLY, ENV_CHECK_MODE, ENV_HYGIENE_ADVISORY, HYGIENE_GATE_ID_PREFIXES, PLAN_ACCEPTANCE_KEY, type PlanAcceptance, PRODUCT_AC_GATE_ID, type ProductFirstCheckMode, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/product-first-done-gate/index.js

@@ -0,0 +1,11 @@
+/**
+ * Product-first done-gate (#3284).
+ *
+ * acceptance.commands schema, verify:ac evaluation, check-mode composition
+ * (AC-first, hygiene advisory under pressure, rapid=AC-only).
+ */
+export { attachPlanAcceptance, buildAcceptanceFromIntakeCapture, readPlanAcceptance, stampAcceptanceFromLiteralCapture, validatePlanAcceptance, } from "./acceptance.js";
+export { applyProductFirstGateMode, isHygieneGate, isProductAcGate, resolveProductFirstCheckMode, } from "./check-mode.js";
+export { evaluateVerifyAcFromPath, evaluateVerifyAcFromPlan, isVerifyAcRequiredAtCeremonyDepth, } from "./evaluate.js";
+export { ENV_CHECK_AC_ONLY, ENV_CHECK_MODE, ENV_HYGIENE_ADVISORY, HYGIENE_GATE_ID_PREFIXES, PLAN_ACCEPTANCE_KEY, PRODUCT_AC_GATE_ID, } from "./types.js";
+//# sourceMappingURL=index.js.map

package/dist/product-first-done-gate/types.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Product-first done-gate (#3284): stated acceptance criteria run FIRST and are
+ * never skippable; hygiene gates run second and may degrade under pressure.
+ *
+ * Architecture for #3267 (literal acceptance-command mechanism). Composes
+ * #3214 ceremony dial (rapid = AC-only) and #3266 bank-the-pass.
+ */
+/** Three-rung AC-source ladder (probe lock on #3284). */
+export type AcSourceRung = "stated" | "derived" | "project_floor";
+/**
+ * One executable acceptance command (verbatim when source_rung=stated).
+ * Mirrors literal-acceptance command shape for interoperability.
+ */
+export interface AcceptanceCommand {
+    readonly command: string;
+    readonly cwd?: string | null;
+    readonly expectedStdout?: string | null;
+    readonly expectedExitCode?: number;
+}
+/**
+ * Canonical plan.acceptance block (#3284).
+ *
+ * - Empty `commands` is allowed only when `none_stated: true` (absence is a decision).
+ * - `none_stated: true` never means "no AC" — it means AC is derived/floor and flagged.
+ * - `source_rung` records which ladder rung was locked at intake / promote.
+ */
+export interface PlanAcceptance {
+    readonly commands: readonly AcceptanceCommand[];
+    /** Explicit marker when the task statement stated no shell commands. */
+    readonly none_stated: boolean;
+    readonly source_rung: AcSourceRung;
+    /** Why derived/floor was chosen (required for derived when recorded). */
+    readonly derived_reason?: string | null;
+}
+/** How `task check` composes product vs hygiene gates under pressure (#3284). */
+export type ProductFirstCheckMode = 
+/** Full graph: AC first (fail-fast), then hygiene (hard), then suite. */
+"full"
+/**
+ * Budget pressure / degraded env: AC still mandatory; hygiene runs but is
+ * advisory (non-zero does not fail check). Suite still runs after AC when present.
+ */
+ | "pressure"
+/**
+ * Ceremony dial rapid/minimal positive content: only AC verification
+ * (no hygiene, no suite) before declaring done via check.
+ */
+ | "rapid";
+/** Canonical product AC gate id used in check gate lists. */
+export declare const PRODUCT_AC_GATE_ID: "verify:ac";
+/** plan.acceptance object key on the plan root. */
+export declare const PLAN_ACCEPTANCE_KEY: "acceptance";
+/** Env override for check mode (full|pressure|rapid|degraded→pressure). */
+export declare const ENV_CHECK_MODE = "DEFT_CHECK_MODE";
+/** Explicit hygiene-advisory flag (truthy → pressure mode floor). */
+export declare const ENV_HYGIENE_ADVISORY = "DEFT_HYGIENE_ADVISORY";
+/** Explicit rapid AC-only flag (truthy → rapid mode). */
+export declare const ENV_CHECK_AC_ONLY = "DEFT_CHECK_AC_ONLY";
+/**
+ * Hygiene gate ids (framework + consumer). Failures may become advisory under
+ * pressure; AC never does. Suite gates are separate (#3188).
+ */
+export declare const HYGIENE_GATE_ID_PREFIXES: readonly string[];
+//# sourceMappingURL=types.d.ts.map

package/dist/product-first-done-gate/types.js

@@ -0,0 +1,61 @@
+/**
+ * Product-first done-gate (#3284): stated acceptance criteria run FIRST and are
+ * never skippable; hygiene gates run second and may degrade under pressure.
+ *
+ * Architecture for #3267 (literal acceptance-command mechanism). Composes
+ * #3214 ceremony dial (rapid = AC-only) and #3266 bank-the-pass.
+ */
+/** Canonical product AC gate id used in check gate lists. */
+export const PRODUCT_AC_GATE_ID = "verify:ac";
+/** plan.acceptance object key on the plan root. */
+export const PLAN_ACCEPTANCE_KEY = "acceptance";
+/** Env override for check mode (full|pressure|rapid|degraded→pressure). */
+export const ENV_CHECK_MODE = "DEFT_CHECK_MODE";
+/** Explicit hygiene-advisory flag (truthy → pressure mode floor). */
+export const ENV_HYGIENE_ADVISORY = "DEFT_HYGIENE_ADVISORY";
+/** Explicit rapid AC-only flag (truthy → rapid mode). */
+export const ENV_CHECK_AC_ONLY = "DEFT_CHECK_AC_ONLY";
+/**
+ * Hygiene gate ids (framework + consumer). Failures may become advisory under
+ * pressure; AC never does. Suite gates are separate (#3188).
+ */
+export const HYGIENE_GATE_ID_PREFIXES = [
+    "verify:branch",
+    "verify:encoding",
+    "verify:cache-fresh",
+    "verify:orphan-active",
+    "verify:license-sync",
+    "verify:contract-drift",
+    "toolchain:check",
+    "toolchain:check-consumer",
+    "verify:stubs",
+    "verify:links",
+    "verify:rule-ownership",
+    "verify:biome-config",
+    "verify:content-manifest",
+    "verify:skill-external-fetch-gate",
+    "verify:cursor-tier1",
+    "verify:openclaw-tier1",
+    "verify:go-freeze",
+    "verify:bridge-drift",
+    "verify:forward-coverage",
+    "verify:test-boundary",
+    "verify:scope-provenance",
+    "verify:consumer-check-contract",
+    "verify:vbrief-conformance",
+    "verify:destructive-gh-verbs",
+    "verify:scm-boundary",
+    "verify:xbrief-drift",
+    "verify:no-task-runtime",
+    "verify:pack-drift",
+    "verify:wip-cap",
+    "verify:agents-md-budget",
+    "verify:eval-health-relocation",
+    "verify:eval-triggers-relocation",
+    "vbrief:validate",
+    "codebase:validate-structure",
+    "verify:codebase-map-fresh",
+    "verify-strategy-output",
+    "doctor",
+];
+//# sourceMappingURL=types.js.map

package/dist/run-summary/emit.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Fail-open run-summary JSONL emitter (#3282).
+ *
+ * Emission never changes exit codes, never throws to callers, and prints at
+ * most one warning when an *explicit* DEFT_RUN_SUMMARY_PATH write fails.
+ * Symlink destinations are refused (no-follow / containment) — fail-open.
+ */
+import { type ResolveRunSummaryDestinationOptions } from "./path.js";
+import { type CheckInvocationRunSummaryPayload, type DialTransitionRunSummaryPayload, type RunSummaryDestination, type RunSummaryEventKind, type RunSummaryLine, type RunSummaryPayload, type SessionStartRunSummaryPayload } from "./types.js";
+export interface RunSummaryEmitterOptions extends ResolveRunSummaryDestinationOptions {
+    readonly projectRoot: string;
+    readonly sessionId: string;
+    readonly frameworkVersion?: string;
+    /** Clock seam for tests. */
+    readonly now?: () => Date;
+    /** Destination override (tests). */
+    readonly destination?: RunSummaryDestination;
+    /** stdout/stderr seams (tests). */
+    readonly writeStdout?: (line: string) => void;
+    readonly writeStderr?: (line: string) => void;
+}
+export interface EmitRunSummaryResult {
+    readonly emitted: boolean;
+    readonly destination: RunSummaryDestination;
+    readonly line: RunSummaryLine | null;
+    readonly warning: boolean;
+}
+/**
+ * Stateful emitter: one instance per session tracks seq and write-warning once.
+ */
+export declare class RunSummaryEmitter {
+    private seq;
+    private warned;
+    private readonly projectRoot;
+    private readonly sessionId;
+    private readonly frameworkVersion;
+    private readonly now;
+    private readonly destination;
+    private readonly writeStdout;
+    private readonly writeStderr;
+    constructor(options: RunSummaryEmitterOptions);
+    getDestination(): RunSummaryDestination;
+    emit(event: RunSummaryEventKind, payload: RunSummaryPayload): EmitRunSummaryResult;
+    emitSessionStart(payload: SessionStartRunSummaryPayload): EmitRunSummaryResult;
+    emitDialTransition(payload: DialTransitionRunSummaryPayload): EmitRunSummaryResult;
+    emitCheckInvocation(payload: CheckInvocationRunSummaryPayload): EmitRunSummaryResult;
+}
+/**
+ * One-shot helper for call sites that do not hold an emitter (e.g. dial escalate).
+ * Still fail-open; creates a fresh seq=1 emitter unless `seqSeed` is passed via reuse.
+ */
+export declare function emitRunSummaryEvent(options: RunSummaryEmitterOptions & {
+    readonly event: RunSummaryEventKind;
+    readonly payload: RunSummaryPayload;
+}): EmitRunSummaryResult;
+//# sourceMappingURL=emit.d.ts.map

package/dist/run-summary/emit.js

@@ -0,0 +1,171 @@
+/**
+ * Fail-open run-summary JSONL emitter (#3282).
+ *
+ * Emission never changes exit codes, never throws to callers, and prints at
+ * most one warning when an *explicit* DEFT_RUN_SUMMARY_PATH write fails.
+ * Symlink destinations are refused (no-follow / containment) — fail-open.
+ */
+import { mkdirSync, realpathSync } from "node:fs";
+import { basename, dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import { readCorePackageVersion } from "../engine-version.js";
+import { containedWrite } from "../fs/contained-write.js";
+import { assertWriteTargetSafe } from "../fs/projection-containment.js";
+import { resolveRunSummaryDestination } from "./path.js";
+import { RUN_SUMMARY_SCHEMA_VERSION, RUN_SUMMARY_STDOUT_PREFIX, RUN_SUMMARY_WRITE_WARNING, } from "./types.js";
+function sortKeysDeep(value) {
+    if (Array.isArray(value)) {
+        return value.map(sortKeysDeep);
+    }
+    if (value !== null && typeof value === "object") {
+        const sorted = {};
+        for (const key of Object.keys(value).sort()) {
+            sorted[key] = sortKeysDeep(value[key]);
+        }
+        return sorted;
+    }
+    return value;
+}
+function lineToJson(line) {
+    return JSON.stringify(sortKeysDeep(line));
+}
+function isNestedUnder(parent, child) {
+    const rel = relative(resolve(parent), resolve(child));
+    return rel.length > 0 && !rel.startsWith("..") && !isAbsolute(rel);
+}
+/**
+ * Post-write realpath check: refuse parent-component TOCTOU where a parent was
+ * replaced with a symlink between validation and open (#3282 Greptile residual).
+ */
+function assertRealpathStillContained(root, targetAbs) {
+    const realRoot = realpathSync(resolve(root));
+    const realTarget = realpathSync(targetAbs);
+    const prefix = realRoot.endsWith(sep) ? realRoot : `${realRoot}${sep}`;
+    if (realTarget !== realRoot && !realTarget.startsWith(prefix)) {
+        throw new Error(`run-summary write refused: realpath escaped containment (${realTarget} not under ${realRoot})`);
+    }
+    // Re-assert path components are not symlinks after the write.
+    assertWriteTargetSafe(realRoot, realTarget);
+}
+/**
+ * Append (or replace) a run-summary line with symlink refusal + containment.
+ * Mirrors lifecycle/events.ts appendEventLogLine (#2766 / #2951 / #3282 Greptile P1).
+ * Post-write realpath re-check closes parent-replacement TOCTOU window.
+ */
+function writeRunSummaryLine(projectRoot, targetPath, textLine, mode) {
+    const targetAbs = resolve(targetPath);
+    const data = `${textLine}\n`;
+    if (isNestedUnder(projectRoot, targetAbs)) {
+        const rootAbs = resolve(projectRoot);
+        assertWriteTargetSafe(rootAbs, targetAbs);
+        containedWrite({
+            root: rootAbs,
+            target: targetAbs,
+            data,
+            mode,
+        });
+        assertRealpathStillContained(rootAbs, targetAbs);
+        return;
+    }
+    // Explicit path outside project: contain under the log parent (no symlink follow).
+    const parent = dirname(targetAbs);
+    mkdirSync(parent, { recursive: true });
+    const parentAbs = resolve(parent);
+    assertWriteTargetSafe(parentAbs, targetAbs);
+    containedWrite({
+        root: parentAbs,
+        target: basename(targetAbs),
+        data,
+        mode,
+    });
+    assertRealpathStillContained(parentAbs, targetAbs);
+}
+/**
+ * Stateful emitter: one instance per session tracks seq and write-warning once.
+ */
+export class RunSummaryEmitter {
+    seq = 0;
+    warned = false;
+    projectRoot;
+    sessionId;
+    frameworkVersion;
+    now;
+    destination;
+    writeStdout;
+    writeStderr;
+    constructor(options) {
+        this.projectRoot = options.projectRoot;
+        this.sessionId = options.sessionId;
+        this.frameworkVersion = options.frameworkVersion ?? readCorePackageVersion();
+        this.now = options.now ?? (() => new Date());
+        this.destination =
+            options.destination ??
+                resolveRunSummaryDestination(options.projectRoot, {
+                    env: options.env,
+                    gitignoreCovers: options.gitignoreCovers,
+                });
+        this.writeStdout = options.writeStdout ?? ((line) => process.stdout.write(`${line}\n`));
+        this.writeStderr = options.writeStderr ?? ((line) => process.stderr.write(`${line}\n`));
+    }
+    getDestination() {
+        return this.destination;
+    }
+    emit(event, payload) {
+        try {
+            if (this.destination.kind === "silent") {
+                return { emitted: false, destination: this.destination, line: null, warning: false };
+            }
+            this.seq += 1;
+            const line = {
+                schema_version: RUN_SUMMARY_SCHEMA_VERSION,
+                session_id: this.sessionId,
+                framework_version: this.frameworkVersion,
+                seq: this.seq,
+                ts: this.now().toISOString(),
+                event,
+                payload,
+            };
+            const text = lineToJson(line);
+            if (this.destination.kind === "stdout") {
+                this.writeStdout(`${RUN_SUMMARY_STDOUT_PREFIX}${text}`);
+                return { emitted: true, destination: this.destination, line, warning: false };
+            }
+            // file destination — no-follow containment (#3282 Greptile P1 security)
+            const { path, truncateOnSessionStart, explicit } = this.destination;
+            try {
+                const mode = event === "session_start" && truncateOnSessionStart ? "replace" : "append";
+                writeRunSummaryLine(this.projectRoot, path, text, mode);
+                return { emitted: true, destination: this.destination, line, warning: false };
+            }
+            catch {
+                // Symlink / containment refusal and I/O both fail-open.
+                if (explicit && !this.warned) {
+                    this.warned = true;
+                    this.writeStderr(RUN_SUMMARY_WRITE_WARNING);
+                    return { emitted: false, destination: this.destination, line, warning: true };
+                }
+                return { emitted: false, destination: this.destination, line, warning: false };
+            }
+        }
+        catch {
+            return { emitted: false, destination: this.destination, line: null, warning: false };
+        }
+    }
+    emitSessionStart(payload) {
+        return this.emit("session_start", payload);
+    }
+    emitDialTransition(payload) {
+        return this.emit("dial_transition", payload);
+    }
+    emitCheckInvocation(payload) {
+        return this.emit("check_invocation", payload);
+    }
+}
+/**
+ * One-shot helper for call sites that do not hold an emitter (e.g. dial escalate).
+ * Still fail-open; creates a fresh seq=1 emitter unless `seqSeed` is passed via reuse.
+ */
+export function emitRunSummaryEvent(options) {
+    const emitter = new RunSummaryEmitter(options);
+    return emitter.emit(options.event, options.payload);
+}
+//# sourceMappingURL=emit.js.map

package/dist/run-summary/index.d.ts

@@ -0,0 +1,4 @@
+export { type EmitRunSummaryResult, emitRunSummaryEvent, RunSummaryEmitter, type RunSummaryEmitterOptions, } from "./emit.js";
+export { gitignoreCoversRunSummary, type ResolveRunSummaryDestinationOptions, resolveRunSummaryDestination, } from "./path.js";
+export { type CheckGateOutcome, type CheckInvocationRunSummaryPayload, DEFAULT_RUN_SUMMARY_BASENAME, type DialTransitionRunSummaryPayload, ENV_RUN_SUMMARY_PATH, RUN_SUMMARY_EVENT_KINDS, RUN_SUMMARY_SCHEMA_VERSION, RUN_SUMMARY_STDOUT_PREFIX, RUN_SUMMARY_WRITE_WARNING, type RunSummaryBaseFields, type RunSummaryDestination, type RunSummaryEventKind, type RunSummaryLine, type RunSummaryPayload, type SessionStartRunSummaryPayload, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/run-summary/index.js

@@ -0,0 +1,4 @@
+export { emitRunSummaryEvent, RunSummaryEmitter, } from "./emit.js";
+export { gitignoreCoversRunSummary, resolveRunSummaryDestination, } from "./path.js";
+export { DEFAULT_RUN_SUMMARY_BASENAME, ENV_RUN_SUMMARY_PATH, RUN_SUMMARY_EVENT_KINDS, RUN_SUMMARY_SCHEMA_VERSION, RUN_SUMMARY_STDOUT_PREFIX, RUN_SUMMARY_WRITE_WARNING, } from "./types.js";
+//# sourceMappingURL=index.js.map

package/dist/run-summary/path.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Resolve where run-summary JSONL should go (#3282 emission matrix).
+ *
+ * - `DEFT_RUN_SUMMARY_PATH=<path>` → append JSONL there (explicit; warn once on write fail)
+ * - `DEFT_RUN_SUMMARY_PATH=-` → stdout lines prefixed `DEFT-TLM:`
+ * - unset → repo-root `.deft-run-summary.json` only when .gitignore covers it; else silent
+ */
+import { type RunSummaryDestination } from "./types.js";
+export { DEFAULT_RUN_SUMMARY_BASENAME, ENV_RUN_SUMMARY_PATH, RUN_SUMMARY_STDOUT_PREFIX, RUN_SUMMARY_WRITE_WARNING, } from "./types.js";
+/**
+ * True when a .gitignore line covers the default run-summary basename.
+ * Matches exact line or trailing slash variants; ignores comments.
+ */
+export declare function gitignoreCoversRunSummary(projectRoot: string, basename?: string): boolean;
+export interface ResolveRunSummaryDestinationOptions {
+    readonly env?: NodeJS.ProcessEnv;
+    /** Test seam for gitignore coverage. */
+    readonly gitignoreCovers?: (projectRoot: string) => boolean;
+}
+/**
+ * Resolve emission destination for the run-summary matrix (#3282).
+ * Never throws — fail-open consumers treat resolution errors as silent.
+ */
+export declare function resolveRunSummaryDestination(projectRoot: string, options?: ResolveRunSummaryDestinationOptions): RunSummaryDestination;
+//# sourceMappingURL=path.d.ts.map