@codyswann/lisa 4.21.4 → 4.21.6

package/dist/cli/doctor-nightly-e2e-guard-job.js

@@ -0,0 +1,156 @@
+/**
+ * @file doctor-nightly-e2e-guard-job.ts
+ * @description Executable-field parsing for one reachable workflow job
+ * @module cli/doctor-nightly-e2e-guard-job
+ */
+import { NIGHTLY_GUARD_CANONICAL_TARGET, nightlyGuardObject, nightlyGuardText, normalizeNightlyGuardTarget, } from "./doctor-nightly-e2e-guard-contract.js";
+import { bypassBearingMapping, hasAnyNightlyGuardBypassEvidence, inspectNightlyGuardJobEvidence, } from "./doctor-nightly-e2e-guard-evidence.js";
+const OFFICIAL_PREFIX = "CodySwannGT/lisa/.github/workflows/nightly-e2e-health.yml@";
+const OFFICIAL_REF = /^[^\s${}]+$/u;
+const LOCAL = /^\.\/\.github\/workflows\/([A-Za-z0-9._-]+\.ya?ml)$/u;
+const failure = (workflow, reason) => ({ workflow: workflow.file, reason });
+const indirectReusableBypassEvidence = (evidence) => evidence.inheritedEnvironment || evidence.stepEnvironment || evidence.run;
+const inspectOfficial = (workflow, jobId, job, evidence) => {
+    const uses = nightlyGuardText(job.uses);
+    if (!uses.startsWith(OFFICIAL_PREFIX))
+        return undefined;
+    if (evidence.condition) {
+        return {
+            failure: failure(workflow, `${jobId}: executable if bypass-label logic can skip the guard and is unsupported`),
+        };
+    }
+    if (indirectReusableBypassEvidence(evidence)) {
+        return {
+            failure: failure(workflow, `${jobId}: indirect bypass environment or run logic around the official reusable is unsupported`),
+        };
+    }
+    const reference = uses.slice(OFFICIAL_PREFIX.length);
+    if (!OFFICIAL_REF.test(reference)) {
+        return {
+            failure: failure(workflow, `${jobId}: official reusable reference is not a static literal`),
+        };
+    }
+    const input = nightlyGuardObject(job.with)?.guard_script;
+    const candidate = input === undefined
+        ? NIGHTLY_GUARD_CANONICAL_TARGET
+        : nightlyGuardText(input);
+    const target = normalizeNightlyGuardTarget(candidate);
+    return target
+        ? { caller: { kind: "official-reusable", target } }
+        : {
+            failure: failure(workflow, `${jobId}: with.guard_script must be one literal contained relative ASCII JavaScript path`),
+        };
+};
+const conditionalFailure = (workflow, jobId, evidence) => evidence.condition &&
+    (evidence.hasNode ||
+        evidence.inheritedEnvironment ||
+        evidence.stepEnvironment)
+    ? failure(workflow, `${jobId}: executable if bypass-label logic can skip the guard and is unsupported`)
+    : undefined;
+const runBypassFailure = (workflow, jobId, evidence) => {
+    if (!evidence.run || !evidence.hasNode)
+        return undefined;
+    const guard = evidence.analyses.findIndex(analysis => analysis.target);
+    const bypassAnalysis = evidence.analyses.find((analysis, index) => analysis.bypassEvidence &&
+        !(guard >= 0 &&
+            index > guard &&
+            (analysis.commandFileWrites?.length ?? 0) > 0));
+    if (!bypassAnalysis)
+        return undefined;
+    return failure(workflow, bypassAnalysis.bypassWiring === "GITHUB_ENV"
+        ? `${jobId}: indirect GITHUB_ENV bypass wiring is unsupported; use a literal YAML env mapping`
+        : `${jobId}: executable run bypass wiring is unsupported; use a literal YAML env mapping`);
+};
+const commandFileFailure = (workflow, jobId, evidence) => {
+    const guard = evidence.analyses.findIndex(analysis => analysis.target);
+    if (guard < 0)
+        return undefined;
+    const write = evidence.analyses
+        .slice(0, guard)
+        .flatMap(analysis => analysis.commandFileWrites ?? [])
+        .find(candidate => candidate.safety !== "safe");
+    return write
+        ? failure(workflow, write.file === "GITHUB_PATH"
+            ? `${jobId}: ${write.safety} GITHUB_PATH write can change command resolution before guard execution`
+            : `${jobId}: ${write.safety} GITHUB_ENV write cannot prove a safe environment before guard execution`)
+        : undefined;
+};
+const directResult = (workflow, jobId, relevant) => {
+    const refused = relevant.find(item => item.reason)?.reason;
+    if (refused)
+        return { failure: failure(workflow, `${jobId}: ${refused}`) };
+    const targets = relevant.flatMap(item => (item.target ? [item.target] : []));
+    if (targets.length === 1) {
+        return { caller: { kind: "direct", target: targets[0] ?? "" } };
+    }
+    if (targets.length === 0 && relevant.every(step => step.reportingOnly)) {
+        return {};
+    }
+    return {
+        failure: failure(workflow, targets.length === 0
+            ? `${jobId}: bypass-bearing job has no supported literal Node guard target`
+            : `${jobId}: multiple Node guard targets are ambiguous`),
+    };
+};
+const inspectDirect = (workflow, jobId, evidence) => {
+    const condition = conditionalFailure(workflow, jobId, evidence);
+    if (condition)
+        return { failure: condition };
+    if (evidence.withMapping && evidence.hasNode) {
+        return {
+            failure: failure(workflow, `${jobId}: bypass-bearing with inputs on a direct job are unsupported`),
+        };
+    }
+    const commandFile = commandFileFailure(workflow, jobId, evidence);
+    if (commandFile)
+        return { failure: commandFile };
+    const runBypass = runBypassFailure(workflow, jobId, evidence);
+    if (runBypass)
+        return { failure: runBypass };
+    const relevant = evidence.analyses.filter((_analysis, index) => evidence.inheritedEnvironment ||
+        bypassBearingMapping(evidence.steps[index]?.env));
+    return relevant.length === 0 ? {} : directResult(workflow, jobId, relevant);
+};
+const inspectLocal = (workflow, jobId, uses, evidence) => {
+    if (evidence.condition ||
+        evidence.withMapping ||
+        indirectReusableBypassEvidence(evidence)) {
+        return {
+            failure: failure(workflow, evidence.condition
+                ? `${jobId}: executable if bypass logic around a local reusable is unsupported`
+                : `${jobId}: indirect bypass logic around a local reusable is unsupported`),
+        };
+    }
+    const local = LOCAL.exec(uses)?.[1];
+    return local
+        ? { local }
+        : {
+            failure: failure(workflow, `${jobId}: local reusable path is unsupported or escapes .github/workflows`),
+        };
+};
+/**
+ * Interpret one reachable executable job without scanning prose or comments.
+ * @param workflow - Parsed workflow containing the job
+ * @param jobId - Stable job mapping key
+ * @param job - Parsed job mapping
+ * @returns Direct caller, local edge, or an explicit refusal
+ */
+export function inspectNightlyGuardJob(workflow, jobId, job) {
+    const evidence = inspectNightlyGuardJobEvidence(workflow, job);
+    const official = inspectOfficial(workflow, jobId, job, evidence);
+    if (official)
+        return official;
+    const uses = nightlyGuardText(job.uses);
+    if (uses.startsWith("./")) {
+        return inspectLocal(workflow, jobId, uses, evidence);
+    }
+    if (uses.length > 0) {
+        return hasAnyNightlyGuardBypassEvidence(evidence)
+            ? {
+                failure: failure(workflow, `${jobId}: bypass evidence on an unsupported remote reusable is unavailable`),
+            }
+            : {};
+    }
+    return inspectDirect(workflow, jobId, evidence);
+}
+//# sourceMappingURL=doctor-nightly-e2e-guard-job.js.map

package/dist/cli/doctor-nightly-e2e-guard-job.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor-nightly-e2e-guard-job.js","sourceRoot":"","sources":["../../src/cli/doctor-nightly-e2e-guard-job.ts"],"names":[],"mappings":"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"}

package/dist/cli/doctor-nightly-e2e-guard-proof.d.ts

@@ -0,0 +1,42 @@
+import type { HashLedger } from "../core/lisa-owned-provenance.js";
+import { type NightlyGuardProbeResult } from "./doctor-nightly-e2e-guard-contract.js";
+import { type NightlyGuardDeadline } from "./doctor-nightly-e2e-guard-deadline.js";
+/** One digest whose actual Lisa package handler passed the behavior suite. */
+export interface NightlyGuardBehaviorCertificate {
+    /** Major-1 contract emitted by the behavior-proven handler. */
+    readonly contractVersion: string;
+}
+/** Exact digest lookup; target paths never broaden certificate authority. */
+export type NightlyGuardBehaviorCertificates = Readonly<Record<string, NightlyGuardBehaviorCertificate>>;
+/** Optional proof collaborators for ledger and deadline bite controls. */
+export interface NightlyGuardProofDependencies {
+    /** Behavior-proven exact digests; tests may inject a precise certificate. */
+    readonly certificates?: NightlyGuardBehaviorCertificates;
+    /** Legacy compatibility seam; generic ownership hashes grant no authority. */
+    readonly ledger?: HashLedger;
+    /** Whole-operation deadline, narrowed to the target ceiling here. */
+    readonly deadline?: NightlyGuardDeadline;
+    /** Standalone target ceiling override for deterministic tests. */
+    readonly timeoutMs?: number;
+    /** Monotonic clock for standalone proof tests. */
+    readonly now?: () => number;
+}
+/**
+ * Lower-case sha256 used as non-executing shipped provenance.
+ * @param bytes - Safely captured target bytes
+ * @returns Lower-case SHA-256 hex digest
+ */
+export declare const digestNightlyGuardBytes: (bytes: Buffer) => string;
+/**
+ * Prove a target by bounded no-follow hash and an exact behavior certificate.
+ *
+ * The target is deliberately never imported, spawned, or evaluated. A caller
+ * can therefore retain direct invocation while doctor itself grants untrusted
+ * bytes no filesystem, process, environment, or network capability.
+ * @param projectRoot - Project root forming the containment boundary
+ * @param target - Literal project-relative JavaScript file
+ * @param dependencies - Optional ledger/deadline collaborators
+ * @returns Compatible major-1 version, or an explicit failed proof
+ */
+export declare function proveNightlyE2eGuardTarget(projectRoot: string, target: string, dependencies?: NightlyGuardProofDependencies): Promise<NightlyGuardProbeResult>;
+//# sourceMappingURL=doctor-nightly-e2e-guard-proof.d.ts.map

package/dist/cli/doctor-nightly-e2e-guard-proof.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor-nightly-e2e-guard-proof.d.ts","sourceRoot":"","sources":["../../src/cli/doctor-nightly-e2e-guard-proof.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kCAAkC,CAAC;AACnE,OAAO,EAGL,KAAK,uBAAuB,EAC7B,MAAM,wCAAwC,CAAC;AAChD,OAAO,EAIL,KAAK,oBAAoB,EAC1B,MAAM,wCAAwC,CAAC;AAKhD,8EAA8E;AAC9E,MAAM,WAAW,+BAA+B;IAC9C,+DAA+D;IAC/D,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC;AAED,6EAA6E;AAC7E,MAAM,MAAM,gCAAgC,GAAG,QAAQ,CACrD,MAAM,CAAC,MAAM,EAAE,+BAA+B,CAAC,CAChD,CAAC;AAEF,0EAA0E;AAC1E,MAAM,WAAW,6BAA6B;IAC5C,6EAA6E;IAC7E,QAAQ,CAAC,YAAY,CAAC,EAAE,gCAAgC,CAAC;IACzD,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC;IAC7B,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,CAAC,EAAE,oBAAoB,CAAC;IACzC,kEAAkE;IAClE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,kDAAkD;IAClD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7B;AAED;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,GAAI,OAAO,MAAM,KAAG,MACN,CAAC;AAEnD;;;;;;;;;;GAUG;AACH,wBAAsB,0BAA0B,CAC9C,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,EACd,YAAY,GAAE,6BAAkC,GAC/C,OAAO,CAAC,uBAAuB,CAAC,CA8ClC"}

package/dist/cli/doctor-nightly-e2e-guard-proof.js

@@ -0,0 +1,57 @@
+/**
+ * @file doctor-nightly-e2e-guard-proof.ts
+ * @description Non-executing provenance and contract proof for active targets
+ * @module cli/doctor-nightly-e2e-guard-proof
+ */
+import { createHash } from "node:crypto";
+import { NIGHTLY_E2E_GUARD_BEHAVIOR_CERTIFICATES, NIGHTLY_E2E_GUARD_CERTIFICATE_SCHEMA_VERSION, } from "../core/nightly-e2e-guard-behavior-certificate.js";
+import { MAX_NIGHTLY_GUARD_FILE_BYTES, NIGHTLY_GUARD_TARGET_TIMEOUT_MS, } from "./doctor-nightly-e2e-guard-contract.js";
+import { createNightlyGuardDeadline, limitNightlyGuardDeadline, nightlyGuardTargetDeadlineReason, } from "./doctor-nightly-e2e-guard-deadline.js";
+import { readNightlyGuardFile } from "./doctor-nightly-e2e-guard-io.js";
+const VERSION = /^1\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/u;
+/**
+ * Lower-case sha256 used as non-executing shipped provenance.
+ * @param bytes - Safely captured target bytes
+ * @returns Lower-case SHA-256 hex digest
+ */
+export const digestNightlyGuardBytes = (bytes) => createHash("sha256").update(bytes).digest("hex");
+/**
+ * Prove a target by bounded no-follow hash and an exact behavior certificate.
+ *
+ * The target is deliberately never imported, spawned, or evaluated. A caller
+ * can therefore retain direct invocation while doctor itself grants untrusted
+ * bytes no filesystem, process, environment, or network capability.
+ * @param projectRoot - Project root forming the containment boundary
+ * @param target - Literal project-relative JavaScript file
+ * @param dependencies - Optional ledger/deadline collaborators
+ * @returns Compatible major-1 version, or an explicit failed proof
+ */
+export async function proveNightlyE2eGuardTarget(projectRoot, target, dependencies = {}) {
+    const outer = dependencies.deadline ??
+        createNightlyGuardDeadline(dependencies.now, dependencies.timeoutMs ?? NIGHTLY_GUARD_TARGET_TIMEOUT_MS, nightlyGuardTargetDeadlineReason(dependencies.timeoutMs ?? NIGHTLY_GUARD_TARGET_TIMEOUT_MS));
+    const deadline = dependencies.deadline
+        ? limitNightlyGuardDeadline(outer, dependencies.timeoutMs ?? NIGHTLY_GUARD_TARGET_TIMEOUT_MS)
+        : outer;
+    const read = await readNightlyGuardFile(projectRoot, target, MAX_NIGHTLY_GUARD_FILE_BYTES, deadline);
+    if (read.state !== "ok") {
+        return { state: "failure", reason: read.reason };
+    }
+    const digest = digestNightlyGuardBytes(read.bytes);
+    const certificates = dependencies.certificates ?? NIGHTLY_E2E_GUARD_BEHAVIOR_CERTIFICATES;
+    const certificate = certificates[digest];
+    if (certificate === undefined) {
+        return {
+            state: "failure",
+            reason: "target bytes are not in Lisa's nightly guard behavior certificate; doctor refuses to execute untrusted JavaScript—upgrade Lisa and apply its exact guard",
+        };
+    }
+    if (NIGHTLY_E2E_GUARD_CERTIFICATE_SCHEMA_VERSION !== 1 ||
+        !VERSION.test(certificate.contractVersion)) {
+        return {
+            state: "failure",
+            reason: "nightly guard behavior certificate is malformed or incompatible",
+        };
+    }
+    return { state: "compatible", version: certificate.contractVersion };
+}
+//# sourceMappingURL=doctor-nightly-e2e-guard-proof.js.map

package/dist/cli/doctor-nightly-e2e-guard-proof.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor-nightly-e2e-guard-proof.js","sourceRoot":"","sources":["../../src/cli/doctor-nightly-e2e-guard-proof.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,EACL,uCAAuC,EACvC,4CAA4C,GAC7C,MAAM,mDAAmD,CAAC;AAE3D,OAAO,EACL,4BAA4B,EAC5B,+BAA+B,GAEhC,MAAM,wCAAwC,CAAC;AAChD,OAAO,EACL,0BAA0B,EAC1B,yBAAyB,EACzB,gCAAgC,GAEjC,MAAM,wCAAwC,CAAC;AAChD,OAAO,EAAE,oBAAoB,EAAE,MAAM,kCAAkC,CAAC;AAExE,MAAM,OAAO,GAAG,kCAAkC,CAAC;AA2BnD;;;;GAIG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,KAAa,EAAU,EAAE,CAC/D,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAEnD;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAC9C,WAAmB,EACnB,MAAc,EACd,eAA8C,EAAE;IAEhD,MAAM,KAAK,GACT,YAAY,CAAC,QAAQ;QACrB,0BAA0B,CACxB,YAAY,CAAC,GAAG,EAChB,YAAY,CAAC,SAAS,IAAI,+BAA+B,EACzD,gCAAgC,CAC9B,YAAY,CAAC,SAAS,IAAI,+BAA+B,CAC1D,CACF,CAAC;IACJ,MAAM,QAAQ,GAAG,YAAY,CAAC,QAAQ;QACpC,CAAC,CAAC,yBAAyB,CACvB,KAAK,EACL,YAAY,CAAC,SAAS,IAAI,+BAA+B,CAC1D;QACH,CAAC,CAAC,KAAK,CAAC;IACV,MAAM,IAAI,GAAG,MAAM,oBAAoB,CACrC,WAAW,EACX,MAAM,EACN,4BAA4B,EAC5B,QAAQ,CACT,CAAC;IACF,IAAI,IAAI,CAAC,KAAK,KAAK,IAAI,EAAE,CAAC;QACxB,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC;IACnD,CAAC;IACD,MAAM,MAAM,GAAG,uBAAuB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACnD,MAAM,YAAY,GAChB,YAAY,CAAC,YAAY,IAAI,uCAAuC,CAAC;IACvE,MAAM,WAAW,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;IACzC,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;QAC9B,OAAO;YACL,KAAK,EAAE,SAAS;YAChB,MAAM,EACJ,0JAA0J;SAC7J,CAAC;IACJ,CAAC;IACD,IACE,4CAA4C,KAAK,CAAC;QAClD,CAAC,OAAO,CAAC,IAAI,CAAC,WAAW,CAAC,eAAe,CAAC,EAC1C,CAAC;QACD,OAAO;YACL,KAAK,EAAE,SAAS;YAChB,MAAM,EAAE,iEAAiE;SAC1E,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,WAAW,CAAC,eAAe,EAAE,CAAC;AACvE,CAAC"}

package/dist/cli/doctor-nightly-e2e-guard-remediation.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @file doctor-nightly-e2e-guard-remediation.ts
+ * @description Provenance-aware repair guidance for nightly guard findings
+ * @module cli/doctor-nightly-e2e-guard-remediation
+ */
+import { type HashLedger } from "../core/lisa-owned-provenance.js";
+import { type NightlyGuardCaller } from "./doctor-nightly-e2e-guard-contract.js";
+import type { NightlyGuardDeadline } from "./doctor-nightly-e2e-guard-deadline.js";
+import { type NightlyGuardBehaviorCertificates } from "./doctor-nightly-e2e-guard-proof.js";
+/** Inputs shared by every caller-specific remediation decision. */
+export interface NightlyGuardRemediationInput {
+    /** Host project under inspection. */
+    readonly projectRoot: string;
+    /** Installed Lisa package root. */
+    readonly lisaRoot: string;
+    /** Active caller whose target failed proof. */
+    readonly caller: NightlyGuardCaller;
+    /** Shared whole-operation deadline. */
+    readonly deadline: NightlyGuardDeadline;
+    /** Optional shipped provenance fixture. */
+    readonly ledger?: HashLedger;
+    /** Optional exact behavior-certificate fixture. */
+    readonly certificates?: NightlyGuardBehaviorCertificates;
+}
+/**
+ * Produce exact repair guidance without collapsing missing, unreadable, stale,
+ * and deliberately modified files into the same destructive instruction.
+ * @param input - Caller, package, provenance, and deadline context
+ * @returns One bounded operator-readable remediation
+ */
+export declare function nightlyGuardRemediation(input: NightlyGuardRemediationInput): Promise<string>;
+//# sourceMappingURL=doctor-nightly-e2e-guard-remediation.d.ts.map

package/dist/cli/doctor-nightly-e2e-guard-remediation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor-nightly-e2e-guard-remediation.d.ts","sourceRoot":"","sources":["../../src/cli/doctor-nightly-e2e-guard-remediation.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAEL,KAAK,UAAU,EAChB,MAAM,kCAAkC,CAAC;AAG1C,OAAO,EAIL,KAAK,kBAAkB,EACxB,MAAM,wCAAwC,CAAC;AAChD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wCAAwC,CAAC;AAEnF,OAAO,EAEL,KAAK,gCAAgC,EACtC,MAAM,qCAAqC,CAAC;AAO7C,mEAAmE;AACnE,MAAM,WAAW,4BAA4B;IAC3C,qCAAqC;IACrC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,mCAAmC;IACnC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,+CAA+C;IAC/C,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;IACpC,uCAAuC;IACvC,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAC;IACxC,2CAA2C;IAC3C,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC;IAC7B,mDAAmD;IACnD,QAAQ,CAAC,YAAY,CAAC,EAAE,gCAAgC,CAAC;CAC1D;AAOD;;;;;GAKG;AACH,wBAAsB,uBAAuB,CAC3C,KAAK,EAAE,4BAA4B,GAClC,OAAO,CAAC,MAAM,CAAC,CAmDjB"}

package/dist/cli/doctor-nightly-e2e-guard-remediation.js

@@ -0,0 +1,55 @@
+/**
+ * @file doctor-nightly-e2e-guard-remediation.ts
+ * @description Provenance-aware repair guidance for nightly guard findings
+ * @module cli/doctor-nightly-e2e-guard-remediation
+ */
+import { classifyHostCopy, } from "../core/lisa-owned-provenance.js";
+import { LISA_OWNED_HASH_LEDGER } from "../core/lisa-owned-hash-ledger.js";
+import { NIGHTLY_E2E_GUARD_BEHAVIOR_CERTIFICATES } from "../core/nightly-e2e-guard-behavior-certificate.js";
+import { MAX_NIGHTLY_GUARD_FILE_BYTES, NIGHTLY_GUARD_CANONICAL_TARGET, NIGHTLY_GUARD_SHIPPED_TARGET, } from "./doctor-nightly-e2e-guard-contract.js";
+import { readNightlyGuardFile } from "./doctor-nightly-e2e-guard-io.js";
+import { digestNightlyGuardBytes, } from "./doctor-nightly-e2e-guard-proof.js";
+const exactProbe = (target) => `node ${target} --contract-version`;
+const preserveContext = "preserve the workflow/job names and required-check context unless a coordinated ruleset migration is planned";
+const packageUnavailable = (reason) => `repair or reinstall Lisa first: its packaged guard is unreadable or corrupt (${reason}); then run \`lisa apply .\` and \`${exactProbe(NIGHTLY_GUARD_CANONICAL_TARGET)}\``;
+const packageUncertified = (reason) => `upgrade or reinstall Lisa first: its packaged guard is not behavior-certified (${reason}); then run \`lisa apply .\` and \`${exactProbe(NIGHTLY_GUARD_CANONICAL_TARGET)}\``;
+/**
+ * Produce exact repair guidance without collapsing missing, unreadable, stale,
+ * and deliberately modified files into the same destructive instruction.
+ * @param input - Caller, package, provenance, and deadline context
+ * @returns One bounded operator-readable remediation
+ */
+export async function nightlyGuardRemediation(input) {
+    const shipped = await readNightlyGuardFile(input.lisaRoot, NIGHTLY_GUARD_SHIPPED_TARGET, MAX_NIGHTLY_GUARD_FILE_BYTES, input.deadline);
+    if (shipped.state === "missing") {
+        return `upgrade first: install Lisa 2.353.0+ on 2.x or, preferably, the current release; then run \`lisa apply .\` and \`${exactProbe(NIGHTLY_GUARD_CANONICAL_TARGET)}\``;
+    }
+    if (shipped.state === "unavailable") {
+        return packageUnavailable(shipped.reason);
+    }
+    const shippedDigest = digestNightlyGuardBytes(shipped.bytes);
+    const certificates = input.certificates ?? NIGHTLY_E2E_GUARD_BEHAVIOR_CERTIFICATES;
+    if (certificates[shippedDigest] === undefined) {
+        return packageUncertified("its exact bytes are absent from this release's nightly guard behavior certificate; a generic ownership hash is insufficient");
+    }
+    const ledger = input.ledger ?? LISA_OWNED_HASH_LEDGER;
+    if (input.caller.target !== NIGHTLY_GUARD_CANONICAL_TARGET) {
+        return `install ${NIGHTLY_GUARD_CANONICAL_TARGET} with \`lisa apply .\`, repoint this job to it, retire ${input.caller.target}, then run \`${exactProbe(NIGHTLY_GUARD_CANONICAL_TARGET)}\`; ${preserveContext}`;
+    }
+    const host = await readNightlyGuardFile(input.projectRoot, NIGHTLY_GUARD_CANONICAL_TARGET, MAX_NIGHTLY_GUARD_FILE_BYTES, input.deadline);
+    if (host.state === "missing") {
+        return `run \`lisa apply .\` to install ${NIGHTLY_GUARD_CANONICAL_TARGET}, then run \`${exactProbe(NIGHTLY_GUARD_CANONICAL_TARGET)}\``;
+    }
+    if (host.state === "unavailable") {
+        return `repair the canonical host path before applying: ${host.reason}; no file was replaced`;
+    }
+    const verdict = classifyHostCopy(NIGHTLY_GUARD_CANONICAL_TARGET, host.bytes, shipped.bytes, ledger);
+    if (verdict.kind === "identical") {
+        return `the failing target is the byte-identical packaged copy; repair, reinstall, or upgrade Lisa, re-run \`lisa apply .\`, then run \`${exactProbe(NIGHTLY_GUARD_CANONICAL_TARGET)}\``;
+    }
+    if (verdict.kind === "provably-stale") {
+        return `this canonical copy is provably stale; run \`lisa apply .\`, then run \`${exactProbe(NIGHTLY_GUARD_CANONICAL_TARGET)}\``;
+    }
+    return `review the preserved modified canonical guard, then take Lisa's exact copy with \`lisa apply . --refresh-templates=${NIGHTLY_GUARD_CANONICAL_TARGET}\` and run \`${exactProbe(NIGHTLY_GUARD_CANONICAL_TARGET)}\``;
+}
+//# sourceMappingURL=doctor-nightly-e2e-guard-remediation.js.map

package/dist/cli/doctor-nightly-e2e-guard-remediation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor-nightly-e2e-guard-remediation.js","sourceRoot":"","sources":["../../src/cli/doctor-nightly-e2e-guard-remediation.ts"],"names":[],"mappings":"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"}

package/dist/cli/doctor-nightly-e2e-guard-runtime.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @file doctor-nightly-e2e-guard-runtime.ts
+ * @description Proven shell and environment constraints for static guard calls
+ * @module cli/doctor-nightly-e2e-guard-runtime
+ */
+/** Metadata whose exact values decide whether POSIX parsing is sound. */
+export interface NightlyGuardRuntimeContext {
+    /** Highest-precedence workflow/job/step shell declaration, when present. */
+    readonly shell: unknown;
+    /** Job runner label used only when no shell is explicitly declared. */
+    readonly runsOn: unknown;
+    /** Fully merged workflow/job/step environment visible to the command. */
+    readonly environment: Readonly<Record<string, unknown>>;
+}
+/**
+ * Identify environment controls that can replace or alter Node/shell execution.
+ * @param name - Case-sensitive process environment name from YAML or shell
+ * @returns Whether the name can change how the certified bytes are executed
+ */
+export declare const isExecutionChangingEnvironmentName: (name: string) => boolean;
+/**
+ * Refuse an effective environment that can turn exact bytes into false proof.
+ * @param environment - Merged environment after YAML precedence is applied
+ * @returns A bounded refusal naming the first dangerous control, when present
+ */
+export declare const nightlyGuardEnvironmentFailure: (environment: Readonly<Record<string, unknown>>) => string | undefined;
+/**
+ * Require either a finite safe shell template or an exact hosted runner label.
+ * @param run - YAML-decoded command; empty steps need no shell inference
+ * @param context - Effective shell, runner, and merged environment metadata
+ * @returns Why static POSIX execution is unproved, or undefined when proved
+ */
+export declare const nightlyGuardPosixContextFailure: (run: string, context: NightlyGuardRuntimeContext) => string | undefined;
+//# sourceMappingURL=doctor-nightly-e2e-guard-runtime.d.ts.map

package/dist/cli/doctor-nightly-e2e-guard-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor-nightly-e2e-guard-runtime.d.ts","sourceRoot":"","sources":["../../src/cli/doctor-nightly-e2e-guard-runtime.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAmDH,yEAAyE;AACzE,MAAM,WAAW,0BAA0B;IACzC,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,uEAAuE;IACvE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,yEAAyE;IACzE,QAAQ,CAAC,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACzD;AAED;;;;GAIG;AACH,eAAO,MAAM,kCAAkC,GAAI,MAAM,MAAM,KAAG,OAEM,CAAC;AAEzE;;;;GAIG;AACH,eAAO,MAAM,8BAA8B,GACzC,aAAa,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,KAC7C,MAAM,GAAG,SAOX,CAAC;AAKF;;;;;GAKG;AACH,eAAO,MAAM,+BAA+B,GAC1C,KAAK,MAAM,EACX,SAAS,0BAA0B,KAClC,MAAM,GAAG,SAeX,CAAC"}

package/dist/cli/doctor-nightly-e2e-guard-runtime.js

@@ -0,0 +1,93 @@
+/**
+ * @file doctor-nightly-e2e-guard-runtime.ts
+ * @description Proven shell and environment constraints for static guard calls
+ * @module cli/doctor-nightly-e2e-guard-runtime
+ */
+const EXECUTION_ENVIRONMENT_NAMES = new Set([
+    "BASHOPTS",
+    "BASH_ENV",
+    "CDPATH",
+    "ENV",
+    "GLOBIGNORE",
+    "IFS",
+    "PATH",
+    "POSIXLY_CORRECT",
+    "SHELLOPTS",
+]);
+const EXECUTION_ENVIRONMENT_PREFIXES = [
+    "BASH_FUNC_",
+    "DYLD_",
+    "LD_",
+    "NIX_LD",
+    "NODE_",
+];
+const GITHUB_HOSTED_POSIX_RUNNER = /^(?:ubuntu-(?:latest|24\.04|22\.04|20\.04)|macos-(?:latest|15|14|13))$/u;
+const EXECUTION_PRESERVING_SHELLS = new Set([
+    "bash",
+    "bash {0}",
+    "bash -e {0}",
+    "bash -eo pipefail {0}",
+    "bash --noprofile --norc -eo pipefail {0}",
+    "sh",
+    "sh {0}",
+    "sh -e {0}",
+    "/bin/bash",
+    "/bin/bash {0}",
+    "/bin/bash -e {0}",
+    "/bin/bash -eo pipefail {0}",
+    "/bin/bash --noprofile --norc -eo pipefail {0}",
+    "/usr/bin/bash",
+    "/usr/bin/bash {0}",
+    "/usr/bin/bash -e {0}",
+    "/usr/bin/bash -eo pipefail {0}",
+    "/usr/bin/bash --noprofile --norc -eo pipefail {0}",
+    "/bin/sh",
+    "/bin/sh {0}",
+    "/bin/sh -e {0}",
+    "/usr/bin/sh",
+    "/usr/bin/sh {0}",
+    "/usr/bin/sh -e {0}",
+]);
+/**
+ * Identify environment controls that can replace or alter Node/shell execution.
+ * @param name - Case-sensitive process environment name from YAML or shell
+ * @returns Whether the name can change how the certified bytes are executed
+ */
+export const isExecutionChangingEnvironmentName = (name) => EXECUTION_ENVIRONMENT_NAMES.has(name) ||
+    EXECUTION_ENVIRONMENT_PREFIXES.some(prefix => name.startsWith(prefix));
+/**
+ * Refuse an effective environment that can turn exact bytes into false proof.
+ * @param environment - Merged environment after YAML precedence is applied
+ * @returns A bounded refusal naming the first dangerous control, when present
+ */
+export const nightlyGuardEnvironmentFailure = (environment) => {
+    const unsafe = Object.keys(environment)
+        .sort((left, right) => left.localeCompare(right))
+        .find(isExecutionChangingEnvironmentName);
+    return unsafe
+        ? `${unsafe} environment control can change or replace certified guard execution`
+        : undefined;
+};
+const normalizedShell = (shell) => shell.trim().split(/\s+/u).join(" ");
+/**
+ * Require either a finite safe shell template or an exact hosted runner label.
+ * @param run - YAML-decoded command; empty steps need no shell inference
+ * @param context - Effective shell, runner, and merged environment metadata
+ * @returns Why static POSIX execution is unproved, or undefined when proved
+ */
+export const nightlyGuardPosixContextFailure = (run, context) => {
+    if (run.trim().length === 0)
+        return undefined;
+    if (context.shell !== undefined) {
+        return typeof context.shell === "string" &&
+            EXECUTION_PRESERVING_SHELLS.has(normalizedShell(context.shell))
+            ? undefined
+            : "step shell is unknown, non-POSIX, or not an execution-preserving bash/sh template";
+    }
+    if (typeof context.runsOn !== "string" ||
+        !GITHUB_HOSTED_POSIX_RUNNER.test(context.runsOn)) {
+        return "runner is self-hosted, array-valued, custom, dynamic, or unknown; an explicit supported POSIX shell is required";
+    }
+    return undefined;
+};
+//# sourceMappingURL=doctor-nightly-e2e-guard-runtime.js.map

package/dist/cli/doctor-nightly-e2e-guard-runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor-nightly-e2e-guard-runtime.js","sourceRoot":"","sources":["../../src/cli/doctor-nightly-e2e-guard-runtime.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,2BAA2B,GAAG,IAAI,GAAG,CAAC;IAC1C,UAAU;IACV,UAAU;IACV,QAAQ;IACR,KAAK;IACL,YAAY;IACZ,KAAK;IACL,MAAM;IACN,iBAAiB;IACjB,WAAW;CACZ,CAAC,CAAC;AACH,MAAM,8BAA8B,GAAG;IACrC,YAAY;IACZ,OAAO;IACP,KAAK;IACL,QAAQ;IACR,OAAO;CACR,CAAC;AAEF,MAAM,0BAA0B,GAC9B,yEAAyE,CAAC;AAE5E,MAAM,2BAA2B,GAAG,IAAI,GAAG,CAAC;IAC1C,MAAM;IACN,UAAU;IACV,aAAa;IACb,uBAAuB;IACvB,0CAA0C;IAC1C,IAAI;IACJ,QAAQ;IACR,WAAW;IACX,WAAW;IACX,eAAe;IACf,kBAAkB;IAClB,4BAA4B;IAC5B,+CAA+C;IAC/C,eAAe;IACf,mBAAmB;IACnB,sBAAsB;IACtB,gCAAgC;IAChC,mDAAmD;IACnD,SAAS;IACT,aAAa;IACb,gBAAgB;IAChB,aAAa;IACb,iBAAiB;IACjB,oBAAoB;CACrB,CAAC,CAAC;AAYH;;;;GAIG;AACH,MAAM,CAAC,MAAM,kCAAkC,GAAG,CAAC,IAAY,EAAW,EAAE,CAC1E,2BAA2B,CAAC,GAAG,CAAC,IAAI,CAAC;IACrC,8BAA8B,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;AAEzE;;;;GAIG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAG,CAC5C,WAA8C,EAC1B,EAAE;IACtB,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC;SACpC,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;SAChD,IAAI,CAAC,kCAAkC,CAAC,CAAC;IAC5C,OAAO,MAAM;QACX,CAAC,CAAC,GAAG,MAAM,sEAAsE;QACjF,CAAC,CAAC,SAAS,CAAC;AAChB,CAAC,CAAC;AAEF,MAAM,eAAe,GAAG,CAAC,KAAa,EAAU,EAAE,CAChD,KAAK,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAEvC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAAG,CAC7C,GAAW,EACX,OAAmC,EACf,EAAE;IACtB,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAC9C,IAAI,OAAO,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAChC,OAAO,OAAO,OAAO,CAAC,KAAK,KAAK,QAAQ;YACtC,2BAA2B,CAAC,GAAG,CAAC,eAAe,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;YAC/D,CAAC,CAAC,SAAS;YACX,CAAC,CAAC,mFAAmF,CAAC;IAC1F,CAAC;IACD,IACE,OAAO,OAAO,CAAC,MAAM,KAAK,QAAQ;QAClC,CAAC,0BAA0B,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,EAChD,CAAC;QACD,OAAO,iHAAiH,CAAC;IAC3H,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC,CAAC"}

package/dist/cli/doctor-nightly-e2e-guard-scan.d.ts

@@ -0,0 +1,17 @@
+import { MAX_NIGHTLY_GUARD_CALLERS, MAX_NIGHTLY_GUARD_FILES, MAX_NIGHTLY_GUARD_TARGETS, type NightlyGuardScanResult } from "./doctor-nightly-e2e-guard-contract.js";
+import { type NightlyGuardDeadline } from "./doctor-nightly-e2e-guard-deadline.js";
+export { MAX_NIGHTLY_GUARD_CALLERS, MAX_NIGHTLY_GUARD_FILES, MAX_NIGHTLY_GUARD_TARGETS, };
+export type { NightlyGuardCaller, NightlyGuardScanFailure, NightlyGuardScanResult, } from "./doctor-nightly-e2e-guard-contract.js";
+/** Optional shared deadline used by the top-level doctor operation. */
+export interface NightlyGuardScanDependencies {
+    /** Deadline started before discovery; standalone scans receive their own. */
+    readonly deadline?: NightlyGuardDeadline;
+}
+/**
+ * Discover every bypass-bearing guard caller reachable from repository events.
+ * @param projectRoot - Project root whose workflow tree is inspected
+ * @param dependencies - Shared deadline when called by doctor
+ * @returns Deterministic callers, or an explicit unavailable refusal
+ */
+export declare function scanNightlyE2eGuardCallers(projectRoot: string, dependencies?: NightlyGuardScanDependencies): Promise<NightlyGuardScanResult>;
+//# sourceMappingURL=doctor-nightly-e2e-guard-scan.d.ts.map

package/dist/cli/doctor-nightly-e2e-guard-scan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor-nightly-e2e-guard-scan.d.ts","sourceRoot":"","sources":["../../src/cli/doctor-nightly-e2e-guard-scan.ts"],"names":[],"mappings":"AAMA,OAAO,EACL,yBAAyB,EAEzB,uBAAuB,EACvB,yBAAyB,EAKzB,KAAK,sBAAsB,EAI5B,MAAM,wCAAwC,CAAC;AAChD,OAAO,EAEL,KAAK,oBAAoB,EAC1B,MAAM,wCAAwC,CAAC;AAOhD,OAAO,EACL,yBAAyB,EACzB,uBAAuB,EACvB,yBAAyB,GAC1B,CAAC;AACF,YAAY,EACV,kBAAkB,EAClB,uBAAuB,EACvB,sBAAsB,GACvB,MAAM,wCAAwC,CAAC;AAEhD,uEAAuE;AACvE,MAAM,WAAW,4BAA4B;IAC3C,6EAA6E;IAC7E,QAAQ,CAAC,QAAQ,CAAC,EAAE,oBAAoB,CAAC;CAC1C;AA6GD;;;;;GAKG;AACH,wBAAsB,0BAA0B,CAC9C,WAAW,EAAE,MAAM,EACnB,YAAY,GAAE,4BAAiC,GAC9C,OAAO,CAAC,sBAAsB,CAAC,CAQjC"}

package/dist/cli/doctor-nightly-e2e-guard-scan.js

@@ -0,0 +1,86 @@
+/**
+ * @file doctor-nightly-e2e-guard-scan.ts
+ * @description Bounded executable-YAML discovery for nightly bypass callers
+ * @module cli/doctor-nightly-e2e-guard-scan
+ */
+import { loadYaml } from "../utils/yaml.js";
+import { MAX_NIGHTLY_GUARD_CALLERS, MAX_NIGHTLY_GUARD_FILE_BYTES, MAX_NIGHTLY_GUARD_FILES, MAX_NIGHTLY_GUARD_TARGETS, MAX_NIGHTLY_GUARD_TOTAL_BYTES, MAX_NIGHTLY_GUARD_WORKFLOW_ID_BYTES, NIGHTLY_GUARD_OPERATION_TIMEOUT_MS, NIGHTLY_GUARD_WORKFLOWS, nightlyGuardObject, orderNightlyGuardStrings, } from "./doctor-nightly-e2e-guard-contract.js";
+import { createNightlyGuardDeadline, } from "./doctor-nightly-e2e-guard-deadline.js";
+import { traceNightlyGuardCallers } from "./doctor-nightly-e2e-guard-graph.js";
+import { readNightlyGuardDirectory, readNightlyGuardFile, } from "./doctor-nightly-e2e-guard-io.js";
+export { MAX_NIGHTLY_GUARD_CALLERS, MAX_NIGHTLY_GUARD_FILES, MAX_NIGHTLY_GUARD_TARGETS, };
+const unavailable = (workflow, reason) => ({
+    state: "unavailable",
+    failures: [{ workflow, reason }],
+});
+const parseWorkflow = (file, name, source) => {
+    try {
+        const document = nightlyGuardObject(loadYaml(source.toString("utf8")));
+        return document
+            ? { file, name, document }
+            : unavailable(file, "workflow YAML root is not a mapping");
+    }
+    catch (error) {
+        return unavailable(file, `workflow is unreadable or malformed (${error instanceof Error ? error.message : String(error)})`);
+    }
+};
+const isScanResult = (value) => "state" in value;
+const hasControlCharacter = (value) => [...value].some(character => {
+    const codePoint = character.codePointAt(0) ?? 0;
+    return codePoint <= 31 || codePoint === 127;
+});
+/**
+ * Read the bounded workflow inventory without following path components.
+ * @param projectRoot - Project containment root
+ * @param deadline - Whole-operation deadline already started by doctor
+ * @returns Parsed inventory or an explicit availability refusal
+ */
+async function readWorkflowRecords(projectRoot, deadline) {
+    const directory = await readNightlyGuardDirectory(projectRoot, NIGHTLY_GUARD_WORKFLOWS, deadline);
+    if (directory.state === "missing")
+        return [];
+    if (directory.state === "unavailable") {
+        return unavailable(NIGHTLY_GUARD_WORKFLOWS, directory.reason);
+    }
+    const names = orderNightlyGuardStrings(directory.names.filter(name => /\.ya?ml$/u.test(name)));
+    if (names.some(name => Buffer.byteLength(name) > MAX_NIGHTLY_GUARD_WORKFLOW_ID_BYTES ||
+        hasControlCharacter(name))) {
+        return unavailable(NIGHTLY_GUARD_WORKFLOWS, `workflow identifier exceeds the ${MAX_NIGHTLY_GUARD_WORKFLOW_ID_BYTES}-byte/control-character limit`);
+    }
+    if (names.length > MAX_NIGHTLY_GUARD_FILES) {
+        return unavailable(NIGHTLY_GUARD_WORKFLOWS, `workflow file limit ${MAX_NIGHTLY_GUARD_FILES} exceeded`);
+    }
+    const readNext = async (index, totalBytes, records) => {
+        const name = names[index];
+        if (name === undefined)
+            return records;
+        const file = `${NIGHTLY_GUARD_WORKFLOWS}/${name}`;
+        const read = await readNightlyGuardFile(projectRoot, file, MAX_NIGHTLY_GUARD_FILE_BYTES, deadline);
+        if (read.state !== "ok")
+            return unavailable(file, read.reason);
+        const nextTotal = totalBytes + read.bytes.length;
+        if (nextTotal > MAX_NIGHTLY_GUARD_TOTAL_BYTES) {
+            return unavailable(file, "workflow scan exceeds the 8 MiB total limit");
+        }
+        const parsed = parseWorkflow(file, name, read.bytes);
+        return isScanResult(parsed)
+            ? parsed
+            : await readNext(index + 1, nextTotal, [...records, parsed]);
+    };
+    return await readNext(0, 0, []);
+}
+/**
+ * Discover every bypass-bearing guard caller reachable from repository events.
+ * @param projectRoot - Project root whose workflow tree is inspected
+ * @param dependencies - Shared deadline when called by doctor
+ * @returns Deterministic callers, or an explicit unavailable refusal
+ */
+export async function scanNightlyE2eGuardCallers(projectRoot, dependencies = {}) {
+    const deadline = dependencies.deadline ??
+        createNightlyGuardDeadline(undefined, NIGHTLY_GUARD_OPERATION_TIMEOUT_MS);
+    const records = await readWorkflowRecords(projectRoot, deadline);
+    return Array.isArray(records)
+        ? traceNightlyGuardCallers(records)
+        : records;
+}
+//# sourceMappingURL=doctor-nightly-e2e-guard-scan.js.map