@deftai/directive-core 0.104.0 → 0.105.0

package/dist/release/build-dist.js

@@ -1,32 +1,43 @@
-import { createWriteStream, existsSync, mkdirSync, readdirSync, statSync, unlinkSync, } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { createReadStream, createWriteStream, existsSync, lstatSync, mkdirSync, readdirSync, realpathSync, statSync, unlinkSync, } from "node:fs";
 import { createRequire } from "node:module";
 import { platform } from "node:os";
-import { dirname, join, relative, resolve } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { NON_PRODUCT_DIRS } from "../fs/non-product-dirs.js";
+import { SUBPROCESS_MAX_BUFFER } from "../subprocess/max-buffer.js";
 const { ZipArchive, TarArchive } = createRequire(import.meta.url)("archiver");
-export const DEFAULT_EXCLUDES = new Set([
-    ".git",
-    "dist",
-    "backup",
-    "node_modules",
-    "__pycache__",
-    ".venv",
-    "htmlcov",
-    ".pytest_cache",
-    ".mypy_cache",
-    ".ruff_cache",
-    ".coverage",
-    "coverage",
-    // Scratch worktrees are never shippable framework content (#2953).
-    ".deft-scratch",
-    "swarm-worktrees",
-]);
+/**
+ * Shared "not product source" core (#3487) plus the coverage artifacts only the
+ * release archive names. Scratch and agent worktrees are never shippable
+ * framework content (#2953). The archive set is git-tracked files (#3490); this
+ * denylist is defence in depth, including for a tracked path under a core name.
+ *
+ * Callers may still widen this per run via `extraExcludes` / `--exclude-extra`.
+ */
+export const DEFAULT_EXCLUDES = new Set([...NON_PRODUCT_DIRS, "htmlcov", ".coverage", "coverage"]);
 export const DEFAULT_EXCLUDED_PATH_PREFIXES = [
     "history/archive",
     "vbrief/completed",
     "vbrief/cancelled",
 ];
+/**
+ * Generated outputs that may be packed even when untracked. Empty by default:
+ * the release archive is a source distribution, so extra outputs must be named
+ * explicitly (#3490).
+ */
+export const DEFAULT_GENERATED_ALLOWLIST = [];
 export const ARCHIVE_ROOT = "deft";
 export const CONTENT_PREFIX = "content/";
+/** Raised when the resolved archive set contains an untracked surprise (#3490). */
+export class UntrackedArchiveEntryError extends Error {
+    paths;
+    constructor(paths) {
+        const listed = paths.join(", ");
+        super(`build-dist: refusing to pack untracked files not on the generated-output allowlist: ${listed}`);
+        this.name = "UntrackedArchiveEntryError";
+        this.paths = paths;
+    }
+}
 const VENDORED_TS_TEST_RE = /\.(test|spec)\.(c|m)?[jt]sx?$/i;
 function flattenContentPrefix(relPosix) {
     if (relPosix === "content")
@@ -46,6 +57,362 @@ function isVendoredTsTest(relPosix) {
     const basename = relPosix.split("/").pop() ?? "";
     return VENDORED_TS_TEST_RE.test(basename);
 }
+function pathHasExcludedComponent(relPosix, excludes) {
+    return relPosix.split("/").some((part) => excludes.has(part));
+}
+function shouldSkipRel(relPosix, excludes, excludedPrefixes) {
+    return (pathHasExcludedComponent(relPosix, excludes) ||
+        matchesExcludedPrefix(relPosix, excludedPrefixes) ||
+        isVendoredTsTest(relPosix));
+}
+/** Private-use mark so archiver's string `name` can carry raw member bytes. */
+export const ARCHIVE_BINARY_NAME_MARK = "\uF000";
+export function flattenContentPrefixBytes(relBytes) {
+    const contentDir = Buffer.from("content", "utf8");
+    if (relBytes.equals(contentDir))
+        return Buffer.from(relBytes);
+    const prefix = Buffer.from(CONTENT_PREFIX, "utf8");
+    if (relBytes.length >= prefix.length && relBytes.subarray(0, prefix.length).equals(prefix)) {
+        return Buffer.from(relBytes.subarray(prefix.length));
+    }
+    return Buffer.from(relBytes);
+}
+export function isValidUtf8Buffer(buf) {
+    return Buffer.from(buf.toString("utf8"), "utf8").equals(buf);
+}
+export function archiveMemberBytes(archiveRelBytes) {
+    return Buffer.concat([Buffer.from(`${ARCHIVE_ROOT}/`, "utf8"), archiveRelBytes]);
+}
+/** Archiver `file()`/`append` name: UTF-8 text, or marked latin1 of raw bytes. */
+export function archiverEntryName(memberBytes) {
+    if (isValidUtf8Buffer(memberBytes))
+        return memberBytes.toString("utf8");
+    return `${ARCHIVE_BINARY_NAME_MARK}${memberBytes.toString("latin1")}`;
+}
+function paxRawRecord(key, value) {
+    const keyword = Buffer.from(` ${key}=`, "utf8");
+    const nl = Buffer.from("\n", "utf8");
+    let digits = 1;
+    for (;;) {
+        const total = digits + keyword.length + value.length + nl.length;
+        const lenStr = String(total);
+        if (lenStr.length === digits) {
+            return Buffer.concat([Buffer.from(lenStr, "utf8"), keyword, value, nl]);
+        }
+        digits = lenStr.length;
+    }
+}
+function loadZipArchiveEntry() {
+    const archiverReq = createRequire(import.meta.url);
+    const zipReq = createRequire(archiverReq.resolve("archiver"));
+    const commons = createRequire(zipReq.resolve("zip-stream"))("compress-commons");
+    const cls = commons.ZipArchiveEntry ?? commons.default?.ZipArchiveEntry;
+    if (cls?.prototype?.setName)
+        return cls;
+    throw new Error("build-dist: cannot load ZipArchiveEntry for byte-preserving member names");
+}
+function loadTarHeaders() {
+    const archiverReq = createRequire(import.meta.url);
+    const zipReq = createRequire(archiverReq.resolve("archiver"));
+    const tarMain = zipReq.resolve("tar-stream");
+    const loaded = createRequire(tarMain)("./headers.js");
+    if (typeof loaded.encodePax !== "function") {
+        throw new Error("build-dist: cannot load tar-stream headers.encodePax");
+    }
+    return loaded;
+}
+/**
+ * Archiver only accepts a string `name` and UTF-8-encodes it. For invalid
+ * git path bytes we mark a latin1 string and write those bytes where
+ * zip-stream / tar-stream already copy a Buffer (`setName` / PAX path).
+ */
+function installBytePreservingMemberNames() {
+    const ZipArchiveEntry = loadZipArchiveEntry();
+    const origSetName = ZipArchiveEntry.prototype.setName;
+    ZipArchiveEntry.prototype.setName = function (name, prependSlash = false) {
+        if (typeof name === "string" && name.charCodeAt(0) === ARCHIVE_BINARY_NAME_MARK.charCodeAt(0)) {
+            // Raw bytes, not UTF-8: leave the ZIP language-encoding flag off so
+            // extractors do not decode 0xFF-class names as UTF-8.
+            this.name = Buffer.from(name.slice(ARCHIVE_BINARY_NAME_MARK.length), "latin1");
+            return;
+        }
+        return origSetName.call(this, name, prependSlash);
+    };
+    const headers = loadTarHeaders();
+    const origEncodePax = headers.encodePax.bind(headers);
+    headers.encodePax = (opts) => {
+        if (typeof opts.name === "string" &&
+            opts.name.charCodeAt(0) === ARCHIVE_BINARY_NAME_MARK.charCodeAt(0)) {
+            const pathRec = paxRawRecord("path", Buffer.from(opts.name.slice(ARCHIVE_BINARY_NAME_MARK.length), "latin1"));
+            const rest = origEncodePax({ ...opts, name: undefined });
+            return Buffer.concat([pathRec, rest]);
+        }
+        return origEncodePax(opts);
+    };
+    return () => {
+        ZipArchiveEntry.prototype.setName = origSetName;
+        headers.encodePax = origEncodePax;
+    };
+}
+function addArchiveFile(archive, absPath, name) {
+    if (Buffer.isBuffer(absPath)) {
+        archive.append(createReadStream(absPath), { name });
+        return;
+    }
+    archive.file(absPath, { name });
+}
+const defaultArchiveFs = {
+    realpathSync: (path, options) => {
+        if (options?.encoding === "buffer") {
+            return realpathSync(path, { encoding: "buffer" });
+        }
+        return realpathSync(path);
+    },
+    lstatSync: (path) => lstatSync(path),
+};
+/** `-z` stdout is a NUL-separated byte stream; never UTF-8-decode it whole. */
+export const GIT_LS_FILES_Z_ENCODING = null;
+/** Decode one `ls-files -z` segment; keep non-UTF-8 bytes as latin1. */
+export function decodeGitLsFilesPath(segment) {
+    const utf8 = segment.toString("utf8");
+    if (Buffer.from(utf8, "utf8").equals(segment))
+        return utf8;
+    return segment.toString("latin1");
+}
+/** Split a raw `git ls-files -z` Buffer on 0x00, keeping original path bytes. */
+export function splitGitLsFilesZRecords(stdout) {
+    const paths = [];
+    let start = 0;
+    for (let i = 0; i < stdout.length; i += 1) {
+        if (stdout[i] === 0) {
+            if (i > start) {
+                const bytes = Buffer.from(stdout.subarray(start, i));
+                paths.push({ relPosix: decodeGitLsFilesPath(bytes), bytes });
+            }
+            start = i + 1;
+        }
+    }
+    if (start < stdout.length) {
+        const bytes = Buffer.from(stdout.subarray(start));
+        paths.push({ relPosix: decodeGitLsFilesPath(bytes), bytes });
+    }
+    return paths;
+}
+/** Split a raw `git ls-files -z` Buffer on 0x00, then decode each path. */
+export function splitGitLsFilesZ(stdout) {
+    return splitGitLsFilesZRecords(stdout).map((p) => p.relPosix);
+}
+function spawnTextFromMaybeBuffer(value) {
+    if (Buffer.isBuffer(value))
+        return value.toString("utf8");
+    return typeof value === "string" ? value : "";
+}
+function bufferFromSpawnStdout(value) {
+    if (Buffer.isBuffer(value))
+        return value;
+    if (typeof value === "string")
+        return Buffer.from(value, "utf8");
+    return Buffer.alloc(0);
+}
+/**
+ * Return `git ls-files -z` paths with original bytes. Fail closed when git
+ * cannot enumerate tracked files -- a walk would pack host-local untracked
+ * state (#3490).
+ */
+export function listGitTrackedPathRecords(root, spawn = spawnSync) {
+    // Pin to root/.git so a nested --root cannot walk up and pack a parent repo.
+    const result = spawn("git", ["-C", root, "--git-dir=.git", "--work-tree=.", "ls-files", "-z"], {
+        encoding: GIT_LS_FILES_Z_ENCODING,
+        timeout: 30_000,
+        maxBuffer: SUBPROCESS_MAX_BUFFER,
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    if (result.status !== 0 || result.error) {
+        const detail = spawnTextFromMaybeBuffer(result.stderr).trim() ||
+            spawnTextFromMaybeBuffer(result.stdout).trim() ||
+            result.error?.message ||
+            "unknown error";
+        throw new Error(`git ls-files failed in ${root}: ${detail}`);
+    }
+    return splitGitLsFilesZRecords(bufferFromSpawnStdout(result.stdout));
+}
+/** Return `git ls-files -z` paths in POSIX form. */
+export function listGitTrackedFiles(root, spawn = spawnSync) {
+    return listGitTrackedPathRecords(root, spawn).map((p) => p.relPosix);
+}
+/**
+ * Fail closed when any resolved archive path is untracked and not on the
+ * generated-output allowlist (#3490).
+ */
+export function assertArchiveEntriesTrackedOrGenerated(root, rels, generatedAllowlist = DEFAULT_GENERATED_ALLOWLIST, spawn = spawnSync) {
+    const tracked = new Set(listGitTrackedFiles(root, spawn));
+    const allowed = new Set(generatedAllowlist);
+    const surprise = rels.filter((rel) => !tracked.has(rel) && !allowed.has(rel));
+    if (surprise.length > 0) {
+        throw new UntrackedArchiveEntryError(surprise);
+    }
+}
+function isInsideRoot(root, absPath) {
+    const rel = relative(resolve(root), absPath);
+    return !rel.startsWith("..") && !isAbsolute(rel);
+}
+/** Canonicalize the supplied archive root once per resolve (#3490 review). */
+function canonicalArchiveRoot(root, fs) {
+    try {
+        const real = fs.realpathSync(root, { encoding: "buffer" });
+        if (Buffer.isBuffer(real)) {
+            return { text: real.toString("utf8"), bytes: real };
+        }
+        return { text: real, bytes: Buffer.from(real, "utf8") };
+    }
+    catch {
+        throw new Error(`build-dist: cannot resolve archive root: ${root}`);
+    }
+}
+/** Join canonical root bytes with original git path bytes; convert POSIX `/` to OS sep. */
+export function joinRootAndRelBytes(rootBytes, relBytes) {
+    const sepByte = sep.charCodeAt(0);
+    const converted = Buffer.from(relBytes);
+    if (sep !== "/") {
+        for (let i = 0; i < converted.length; i += 1) {
+            if (converted[i] === 0x2f)
+                converted[i] = sepByte;
+        }
+    }
+    if (converted.length === 0)
+        return rootBytes;
+    const rootEndsSep = rootBytes.length > 0 && rootBytes[rootBytes.length - 1] === sepByte;
+    const relStartsSep = converted[0] === sepByte;
+    if (rootEndsSep && relStartsSep)
+        return Buffer.concat([rootBytes, converted.subarray(1)]);
+    if (rootEndsSep || relStartsSep)
+        return Buffer.concat([rootBytes, converted]);
+    return Buffer.concat([rootBytes, Buffer.from([sepByte]), converted]);
+}
+/**
+ * String path when the `-z` segment is valid UTF-8; otherwise a Buffer that
+ * keeps the original filename bytes for fs lookup (#3490 residual).
+ */
+export function fsLookupPath(root, relPosix, bytes, rootBytes) {
+    const contained = containedAbsPath(root, relPosix);
+    if (contained === null)
+        return null;
+    if (Buffer.from(relPosix, "utf8").equals(bytes))
+        return contained;
+    return joinRootAndRelBytes(rootBytes ?? Buffer.from(resolve(root), "utf8"), bytes);
+}
+function isInsideResolved(canonicalRoot, canonicalBytes, real) {
+    if (typeof real === "string")
+        return isInsideRoot(canonicalRoot, real);
+    const sepByte = sep.charCodeAt(0);
+    if (real.equals(canonicalBytes))
+        return true;
+    const prefix = canonicalBytes.length > 0 && canonicalBytes[canonicalBytes.length - 1] === sepByte
+        ? canonicalBytes
+        : Buffer.concat([canonicalBytes, Buffer.from([sepByte])]);
+    if (real.length < prefix.length)
+        return false;
+    if (real.subarray(0, prefix.length).equals(prefix))
+        return true;
+    if (process.platform === "win32") {
+        return (real.subarray(0, prefix.length).toString("utf8").toLowerCase() ===
+            prefix.toString("utf8").toLowerCase());
+    }
+    return false;
+}
+/** Resolve a POSIX rel path under root, or null if it escapes (#3490 review). */
+export function containedAbsPath(root, relPosix) {
+    if (relPosix.includes("\0"))
+        return null;
+    // Git index paths are POSIX (`/` only). A literal `\` is a filename byte
+    // (gitglossary "path"); splitting on `\` would pack `foo\bar` as nested
+    // path segments and could escape the root. Node resolve still fail-closes
+    // OS-separator `..\` via isInsideRoot.
+    const parts = relPosix.split("/");
+    if (parts.some((part) => part === ".."))
+        return null;
+    const absPath = resolve(root, ...parts.filter((part) => part.length > 0 && part !== "."));
+    if (!isInsideRoot(root, absPath))
+        return null;
+    return absPath;
+}
+function toArchiveEntry(root, canonicalRoot, relPosix, bytes, fs) {
+    const lookup = fsLookupPath(root, relPosix, bytes, canonicalRoot.bytes);
+    if (lookup === null)
+        return null;
+    let real;
+    try {
+        // realpath resolves leaf and ancestor symlinks before the file-type check.
+        // Buffer lookup keeps invalid filename bytes; a string would re-encode UTF-8.
+        real = Buffer.isBuffer(lookup)
+            ? fs.realpathSync(lookup, { encoding: "buffer" })
+            : fs.realpathSync(lookup);
+    }
+    catch {
+        return null;
+    }
+    // Compare against the canonical root so a symlink *to* the checkout is
+    // inside, while a symlink *out of* the tree still throws.
+    if (!isInsideResolved(canonicalRoot.text, canonicalRoot.bytes, real)) {
+        throw new Error(`build-dist: path resolves outside the archive root: ${relPosix}`);
+    }
+    let st;
+    try {
+        st = fs.lstatSync(real);
+    }
+    catch {
+        return null;
+    }
+    if (st == null || !st.isFile())
+        return null;
+    return {
+        absPath: real,
+        archiveRel: flattenContentPrefix(relPosix),
+        archiveRelBytes: flattenContentPrefixBytes(bytes),
+    };
+}
+/**
+ * Derive the archive file set from git-tracked paths plus an explicit
+ * generated-output allowlist. The basename denylist remains defence in depth.
+ */
+export function resolveArchiveEntries(root, options = {}) {
+    const excludes = new Set([...DEFAULT_EXCLUDES, ...(options.extraExcludes ?? [])]);
+    const excludedPrefixes = options.excludedPrefixes ?? DEFAULT_EXCLUDED_PATH_PREFIXES;
+    const generatedAllowlist = options.generatedAllowlist ?? DEFAULT_GENERATED_ALLOWLIST;
+    const spawn = options.spawn ?? spawnSync;
+    const fs = options.fs ?? defaultArchiveFs;
+    const canonicalRoot = canonicalArchiveRoot(root, fs);
+    const tracked = listGitTrackedPathRecords(root, spawn);
+    const entries = [];
+    const sourceRels = [];
+    const seen = new Set();
+    for (const { relPosix, bytes } of tracked) {
+        if (shouldSkipRel(relPosix, excludes, excludedPrefixes))
+            continue;
+        const entry = toArchiveEntry(root, canonicalRoot, relPosix, bytes, fs);
+        if (entry === null)
+            continue;
+        entries.push(entry);
+        sourceRels.push(relPosix);
+        seen.add(relPosix);
+    }
+    for (const relPosix of generatedAllowlist) {
+        if (seen.has(relPosix))
+            continue;
+        if (containedAbsPath(root, relPosix) === null) {
+            throw new Error(`build-dist: generated allowlist path escapes the archive root: ${relPosix}`);
+        }
+        const entry = toArchiveEntry(root, canonicalRoot, relPosix, Buffer.from(relPosix, "utf8"), fs);
+        if (entry === null)
+            continue;
+        entries.push(entry);
+        sourceRels.push(relPosix);
+        seen.add(relPosix);
+    }
+    assertArchiveEntriesTrackedOrGenerated(root, sourceRels, generatedAllowlist, spawn);
+    entries.sort((a, b) => a.archiveRel.localeCompare(b.archiveRel));
+    return entries;
+}
 export function iterSourceFiles(root, excludes = DEFAULT_EXCLUDES, excludedPrefixes = DEFAULT_EXCLUDED_PATH_PREFIXES) {
     const entries = [];
     const walk = (dir) => {
@@ -121,48 +488,63 @@ function isExtraExcludesList(options) {
 function resolveBuildOptions(options = {}) {
     // Backward-compatible: 4th arg may be a bare extra-excludes array (pre-#2953).
     if (isExtraExcludesList(options)) {
-        return { extraExcludes: options, onProgress: () => { } };
+        return {
+            extraExcludes: options,
+            generatedAllowlist: DEFAULT_GENERATED_ALLOWLIST,
+            onProgress: () => { },
+            spawn: undefined,
+            fs: undefined,
+        };
     }
     return {
         extraExcludes: options.extraExcludes ?? [],
+        generatedAllowlist: options.generatedAllowlist ?? DEFAULT_GENERATED_ALLOWLIST,
         onProgress: options.onProgress ?? (() => { }),
+        spawn: options.spawn,
+        fs: options.fs,
     };
 }
 export async function buildArchive(root, version, fmt, options = {}) {
-    const { extraExcludes, onProgress } = resolveBuildOptions(options);
-    const excludes = new Set([...DEFAULT_EXCLUDES, ...extraExcludes]);
+    const { extraExcludes, generatedAllowlist, onProgress, spawn, fs } = resolveBuildOptions(options);
     const output = outputPath(root, version, fmt);
     mkdirSync(dirname(output), { recursive: true });
     if (existsSync(output)) {
         unlinkSync(output);
     }
-    onProgress({ stage: "scan", detail: "enumerating source files" });
-    const entries = iterSourceFiles(root, excludes);
+    onProgress({ stage: "scan", detail: "enumerating tracked source files" });
+    const entries = resolveArchiveEntries(root, { extraExcludes, generatedAllowlist, spawn, fs });
     const total = entries.length;
     onProgress({ stage: "scan", detail: `found ${total} files`, current: total, total });
-    await new Promise((resolvePromise, reject) => {
-        const out = createWriteStream(output);
-        const archive = fmt === "zip"
-            ? new ZipArchive({ zlib: { level: 9 } })
-            : new TarArchive({ gzip: true, gzipOptions: { level: 9 } });
-        out.on("close", () => resolvePromise());
-        out.on("error", (err) => reject(err));
-        archive.on("error", (err) => reject(err));
-        archive.pipe(out);
-        onProgress({ stage: "pack", detail: `format=${fmt}`, current: 0, total });
-        // Progress ticks every ~5% (or every 250 files) so long packs do not look hung.
-        const tickEvery = Math.max(1, Math.min(250, Math.ceil(total / 20)));
-        let i = 0;
-        for (const { absPath, archiveRel } of entries) {
-            archive.file(absPath, { name: `${ARCHIVE_ROOT}/${archiveRel}` });
-            i += 1;
-            if (i === total || i % tickEvery === 0) {
-                onProgress({ stage: "pack", current: i, total });
+    const uninstallNameHook = installBytePreservingMemberNames();
+    try {
+        await new Promise((resolvePromise, reject) => {
+            const out = createWriteStream(output);
+            const archive = fmt === "zip"
+                ? new ZipArchive({ zlib: { level: 9 } })
+                : new TarArchive({ gzip: true, gzipOptions: { level: 9 } });
+            out.on("close", () => resolvePromise());
+            out.on("error", (err) => reject(err));
+            archive.on("error", (err) => reject(err));
+            archive.pipe(out);
+            onProgress({ stage: "pack", detail: `format=${fmt}`, current: 0, total });
+            // Progress ticks every ~5% (or every 250 files) so long packs do not look hung.
+            const tickEvery = Math.max(1, Math.min(250, Math.ceil(total / 20)));
+            let i = 0;
+            for (const { absPath, archiveRel, archiveRelBytes } of entries) {
+                const memberBytes = archiveMemberBytes(archiveRelBytes ?? Buffer.from(archiveRel, "utf8"));
+                addArchiveFile(archive, absPath, archiverEntryName(memberBytes));
+                i += 1;
+                if (i === total || i % tickEvery === 0) {
+                    onProgress({ stage: "pack", current: i, total });
+                }
             }
-        }
-        onProgress({ stage: "finalize", detail: output });
-        void archive.finalize();
-    });
+            onProgress({ stage: "finalize", detail: output });
+            void archive.finalize();
+        });
+    }
+    finally {
+        uninstallNameHook();
+    }
     onProgress({ stage: "done", detail: output, current: total, total });
     return output;
 }

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

@@ -6,10 +6,12 @@
  * Symlink destinations are refused (no-follow / containment) — fail-open.
  */
 import { type ResolveRunSummaryDestinationOptions } from "./path.js";
-import { type AcceptanceRunSummaryPayload, type AcceptanceStampRunSummaryPayload, type CheckInvocationRunSummaryPayload, type DialEscalationEvaluationRunSummaryPayload, type DialTransitionRunSummaryPayload, type RunSummaryDestination, type RunSummaryEventKind, type RunSummaryLine, type RunSummaryPayload, type SessionStartRunSummaryPayload, type ToolTurnDenominatorRunSummaryPayload, type VerificationRunSummaryPayload } from "./types.js";
+import { type AcceptanceRunSummaryPayload, type AcceptanceStampRunSummaryPayload, type AcPassBankRunSummaryPayload, type CheckInvocationRunSummaryPayload, type DialEscalationEvaluationRunSummaryPayload, type DialTransitionRunSummaryPayload, type RunSummaryDestination, type RunSummaryEventKind, type RunSummaryLine, type RunSummaryPayload, type SessionStartRunSummaryPayload, type ToolTurnDenominatorRunSummaryPayload, type ToolTurnDenominatorSource, type VerificationRunSummaryPayload } from "./types.js";
 export interface RunSummaryEmitterOptions extends ResolveRunSummaryDestinationOptions {
     readonly projectRoot: string;
-    readonly sessionId: string;
+    readonly sessionId?: string | null;
+    /** Optional envelope label; not a closed union (#3399). */
+    readonly component?: string;
     readonly frameworkVersion?: string;
     /** Clock seam for tests. */
     readonly now?: () => Date;
@@ -52,6 +54,7 @@ export declare class RunSummaryEmitter {
     private warned;
     private readonly projectRoot;
     private readonly sessionId;
+    private readonly component?;
     private readonly frameworkVersion;
     private readonly now;
     private readonly destination;
@@ -70,12 +73,13 @@ export declare class RunSummaryEmitter {
     emitVerification(payload: VerificationRunSummaryPayload): EmitRunSummaryResult;
     emitAcceptance(payload: AcceptanceRunSummaryPayload): EmitRunSummaryResult;
     emitAcceptanceStamp(payload: AcceptanceStampRunSummaryPayload): EmitRunSummaryResult;
+    emitAcPassBank(payload: AcPassBankRunSummaryPayload): EmitRunSummaryResult;
     /** Emit the harness-supplied denominator when DEFT_TOTAL_TOOL_TURNS is set. */
     emitKnownToolTurnDenominator(): EmitRunSummaryResult;
     /**
-     * Always emit a session denominator when the destination is live (#3356).
+     * Emit a session denominator only when a host/harness value is known (#3399).
      * `emitKnownToolTurnDenominator` stays silent unless DEFT_TOTAL_TOOL_TURNS is
-     * set; this caller records host planned turns or the session:start CLI floor.
+     * set; this caller also records DEFT_MAX_TURNS / host maxTurns.
      */
     emitSessionToolTurnDenominator(hostMaxTurns?: number | null): EmitRunSummaryResult;
 }
@@ -83,16 +87,18 @@ export declare class RunSummaryEmitter {
 export declare function readEnvToolTurnDenominator(env: NodeJS.ProcessEnv): number | undefined;
 /** Canonical host planned-turn budget recorded at session:start (#3356). */
 export declare const ENV_MAX_TURNS_DENOMINATOR = "DEFT_MAX_TURNS";
-/** session:start is one CLI invocation when no host/harness count is known (#3356). */
-export declare const SESSION_START_CLI_INVOCATION_DENOMINATOR: 1;
+export interface ResolvedSessionToolTurnDenominator {
+    readonly total_tool_turns: number;
+    readonly denominator_source: ToolTurnDenominatorSource;
+}
 /**
- * Resolve the session tool/turn denominator (#3356).
+ * Resolve the session tool/turn denominator (#3399).
  *
  * Prefer harness actuals (`DEFT_TOTAL_TOOL_TURNS`), then a host planned-turn
- * budget (`DEFT_MAX_TURNS` or `hostMaxTurns` from the session:start descriptor),
- * else this CLI invocation (1). An emitted proxy beats a perfect unused kind.
+ * budget (`DEFT_MAX_TURNS` or `hostMaxTurns`). Unset → undefined (no event).
+ * Share is unevaluable without a host/harness value.
  */
-export declare function resolveSessionToolTurnDenominator(env: NodeJS.ProcessEnv, hostMaxTurns?: number | null): number;
+export declare function resolveSessionToolTurnDenominator(env: NodeJS.ProcessEnv, hostMaxTurns?: number | null): ResolvedSessionToolTurnDenominator | undefined;
 /**
  * One-shot helper for call sites that do not hold an emitter (e.g. dial escalate).
  * Still fail-open. File destinations seed seq from the existing JSONL line