auditor-lambda 0.6.12 → 0.8.0

package/README.md

@@ -215,26 +215,6 @@ Optional backend config:
 - use `provider: "auto"` only when you want best-effort routing across installed backends
 - treat explicit provider bridges as compatibility fallback, not as the intended owner of semantic review
 
-## Current Development Focus
-
-The next implementation work is tracked in:
-
-- `docs/product.md`
-- `docs/development.md`
-- `docs/handoff.md`
-
-The short version is:
-
-- keep the packet dispatch workflow verified in real host environments
-- make graph-informed packetization observable before adding more ecosystem-specific parsers
-- consolidate graph extraction and exercise generic ownership hints for analyzer-supplied module roots
-- add deterministic Python import, package, and test/source graph support as a core language path
-- use semantic/NLP-style affinity only as low-authority context unless deterministic graph evidence supports it
-- keep generated Codex, Claude Desktop, OpenCode, VS Code, and Antigravity guidance aligned with real host behavior
-- tighten the repo-local MCP-first bootstrap where host smoke tests expose friction
-- polish provider-assisted continuation and failure guidance
-- keep schema contracts and examples easy for workers and host integrations to validate
-
 ## Build And Test
 
 ```bash
@@ -253,6 +233,5 @@ For GitHub Actions publication and npm Trusted Publishing setup, see `docs/relea
 - `docs/contracts.md`
 - `docs/release.md`
 - `docs/development.md`
-- `docs/handoff.md`
 - `docs/history.md`
 - `skills/audit-code/SKILL.md`

package/audit-code-wrapper-lib.mjs

@@ -2,7 +2,7 @@ import { access, cp, mkdir, open, readFile, readdir, stat, unlink, writeFile } f
 import { constants } from 'node:fs';
 import { spawn } from 'node:child_process';
 import { createRequire } from 'node:module';
-import { dirname, join, relative, resolve } from 'node:path';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const repoRoot = dirname(fileURLToPath(import.meta.url));
@@ -247,11 +247,54 @@ async function acquireBuildLock() {
   }
 }
 
+// Pure, testable core of the build preflight. `sharedManifestPath` is the
+// resolved path of @audit-tools/shared's package.json (or null if it could not
+// be resolved at all); `checkoutRoot` is the root this wrapper belongs to.
+export function assertWorkspaceInstalled({ checkoutRoot, sharedManifestPath }) {
+  if (!sharedManifestPath) {
+    throw new Error(
+      'Dependencies are not installed for this checkout. Run `npm install` from ' +
+        'the repository root, then retry — building from source needs node_modules ' +
+        '(including the @audit-tools/shared workspace link).',
+    );
+  }
+
+  const relToCheckout = relative(checkoutRoot, sharedManifestPath);
+  if (relToCheckout.startsWith('..') || isAbsolute(relToCheckout)) {
+    throw new Error(
+      `@audit-tools/shared resolved to ${sharedManifestPath}, outside this ` +
+        `checkout (${checkoutRoot}). node_modules was never installed here — ` +
+        'common in a fresh git worktree — so building would typecheck against ' +
+        "another checkout's stale dist and report phantom \"missing export\" " +
+        "errors. Run `npm install` from this checkout's root.",
+    );
+  }
+}
+
+// Catches the common fresh-checkout trap before `npm run build` runs: with no
+// local node_modules, Node/tsc resolve @audit-tools/shared against a different
+// checkout (e.g. the main repo when running inside a git worktree).
+async function preflightWorkspace() {
+  const requireFromHere = createRequire(import.meta.url);
+  let sharedManifestPath = null;
+  try {
+    sharedManifestPath = requireFromHere.resolve('@audit-tools/shared/package.json');
+  } catch {
+    sharedManifestPath = null;
+  }
+  assertWorkspaceInstalled({
+    checkoutRoot: resolve(repoRoot, '..', '..'),
+    sharedManifestPath,
+  });
+}
+
 async function ensureBuilt() {
   if (!(await shouldBuildDist())) {
     return;
   }
 
+  await preflightWorkspace();
+
   const lockHandle = await acquireBuildLock();
   if (!lockHandle) {
     return;

package/dist/cli/args.d.ts

@@ -35,6 +35,7 @@ export declare function summarizeLaunchExit(result: {
     error?: string;
 }): string | null;
 export declare function taskResultPath(taskResultsDir: string, taskId: string): string;
+export declare function isCanonicalResultFilename(filename: string): boolean;
 export declare function packetPromptPath(taskResultsDir: string, packetId: string): string;
 export declare function readStdinText(): Promise<string>;
 export declare function normalizePositiveInteger(value: unknown): number | undefined;

package/dist/cli/args.js

@@ -101,6 +101,14 @@ export function summarizeLaunchExit(result) {
 export function taskResultPath(taskResultsDir, taskId) {
     return join(taskResultsDir, artifactNameForId(taskId, "json"));
 }
+const CANONICAL_RESULT_FILENAME = /_[0-9a-f]{12}\.json$/i;
+// True when `filename` matches the canonical per-task result naming produced by
+// artifactNameForId (stem + "_" + 12-hex sha256 digest + ".json"). Lets
+// merge-and-ingest tell legitimate prior-round results apart from genuinely
+// stray files (e.g. packet-23-results.json) left in task-results/.
+export function isCanonicalResultFilename(filename) {
+    return CANONICAL_RESULT_FILENAME.test(filename);
+}
 export function packetPromptPath(taskResultsDir, packetId) {
     return join(taskResultsDir, artifactNameForId(packetId, "prompt.md"));
 }

package/dist/cli/auditStep.js

@@ -84,7 +84,13 @@ export async function runAuditStep(options) {
         opentoken: options.opentoken,
         runLogger,
     });
-    await writeCoreArtifacts(options.artifactsDir, result.updated_bundle);
+    // Prune: result.updated_bundle is the full accumulated bundle, so an artifact
+    // an executor cleared to `undefined` must be removed from disk (not left to
+    // reload as a stale "present" artifact). Safe only because this is the
+    // authoritative per-step persist.
+    await writeCoreArtifacts(options.artifactsDir, result.updated_bundle, {
+        prune: true,
+    });
     const archivedPendingResults = await maybeArchiveLegacyPendingResults(options.auditResultsPath);
     if (archivedPendingResults) {
         result.progress_summary +=

package/dist/cli/dispatch.js

@@ -8,7 +8,7 @@ import { orderTasksForPacketReview, buildReviewPackets, sizeIndexFromManifest, }
 import { buildFileAnchorSummary } from "../orchestrator/fileAnchors.js";
 import { resolveFreshSessionProviderName } from "../providers/index.js";
 import { loadSessionConfig } from "../supervisor/sessionConfig.js";
-import { scheduleWave, buildProviderModelKey, readQuotaState, resolveHostActiveSubagentLimit, lookupDiscoveredLimits, mergeDiscoveredLimits, } from "../quota/index.js";
+import { scheduleWave, buildProviderModelKey, resolveHostModel, readQuotaState, resolveHostActiveSubagentLimit, lookupDiscoveredLimits, mergeDiscoveredLimits, } from "../quota/index.js";
 import { taskResultPath, packetPromptPath, artifactNameForId, toBase64Url, fromBase64Url, getFlag, } from "./args.js";
 export const LARGE_FILE_PACKET_TARGET_LINES = 2500;
 export const SMALL_MODEL_HINT_MAX_LINES = 500;
@@ -391,7 +391,9 @@ export async function prepareDispatchArtifacts(params) {
             ...taskSections,
             "## Output",
             "Do not write files directly. Do not use a Write tool, create temp files, edit source files,",
-            "remediate findings, create extra task results, or run unrelated audits.",
+            "remediate findings, run unrelated audits, or write any result file yourself (e.g.",
+            "packet-*-result.json / audit_result_*.json) — the submit-packet command below is the only",
+            "way to record results, and it writes them inside the artifacts directory for you.",
             "Produce one JSON array containing exactly one AuditResult object for each listed task.",
             "",
             "Required AuditResult fields:",
@@ -453,9 +455,18 @@ export async function prepareDispatchArtifacts(params) {
         run_id: runId,
         entries: resultMapEntries,
     });
-    const hostModel = params.hostModel ?? null;
     const perPacketTokens = plan.map((p) => p.complexity.estimated_tokens);
     const quotaProviderName = resolveFreshSessionProviderName(undefined, sessionConfig);
+    // Resolve the host model (explicit/CLI override → block_quota.host_model → env
+    // → per-provider default) so per-model quota detection engages with realistic
+    // limits instead of the conservative unknown-model floor. params.hostModel
+    // carries any caller/CLI override.
+    const hostModel = resolveHostModel({
+        providerName: quotaProviderName,
+        sessionConfig,
+        explicitModel: params.hostModel,
+        envVar: "AUDIT_CODE_HOST_MODEL",
+    });
     const quotaProviderKey = buildProviderModelKey(quotaProviderName, hostModel);
     const quotaState = await readQuotaState().catch(() => ({ version: 2, entries: {} }));
     const quotaStateEntry = quotaState.entries[quotaProviderKey] ?? null;

package/dist/cli/nextStepCommand.js

@@ -3,6 +3,7 @@ import { join, resolve } from "node:path";
 import { isFileMissingError, readJsonFile, writeJsonFile, } from "@audit-tools/shared";
 import { loadArtifactBundle, promoteFinalAuditReport, writeCoreArtifacts, AUDIT_REPORT_FILENAME, } from "../io/artifacts.js";
 import { advanceAudit } from "../orchestrator/advance.js";
+import { computeArtifactStateSignature } from "../orchestrator/artifactMetadata.js";
 import { decideNextStep } from "../orchestrator/nextStep.js";
 import { deriveAuditState } from "../orchestrator/state.js";
 import { checkFileIntegrity } from "../orchestrator/fileIntegrity.js";
@@ -25,6 +26,15 @@ import { getArtifactsDir, getFlag, getHostMaxActiveSubagents, getMaxRuns, getOpt
 async function runDeterministicForNextStep(params) {
     let lastSummary = "";
     let analyzers = params.analyzers;
+    // Finalization thrashing guard. A converging run produces a (mostly) new
+    // artifact state each iteration, so the iteration count tracks the number of
+    // distinct states closely (a few idempotent passes are normal). When
+    // iterations outrun distinct states by this tolerance, deterministic executors
+    // are revisiting states (a staleness ping-pong, e.g. runtime_validation <->
+    // synthesis) rather than progressing — stop instead of spinning to maxRuns.
+    const FINALIZATION_CYCLE_TOLERANCE = 16;
+    const seenStateSignatures = new Set();
+    const obligationTrail = [];
     for (let index = 0; index < params.maxRuns; index++) {
         const bundle = await loadArtifactBundle(params.artifactsDir);
         const decision = decideNextStep(bundle);
@@ -286,6 +296,33 @@ async function runDeterministicForNextStep(params) {
                 reason: result.progress_summary,
             };
         }
+        // Finalization cycle guard. If this iteration returned the audit to an
+        // artifact state already produced this run, the deterministic loop is
+        // thrashing (no net progress) rather than converging. The canonical outputs
+        // are already rendered, so stop and surface the cycling obligations instead
+        // of spinning to maxRuns and crashing.
+        obligationTrail.push(decision.selected_obligation ?? "unknown");
+        seenStateSignatures.add(computeArtifactStateSignature(result.updated_bundle));
+        if (index + 1 - seenStateSignatures.size >= FINALIZATION_CYCLE_TOLERANCE) {
+            const cycle = Array.from(new Set(obligationTrail.slice(-FINALIZATION_CYCLE_TOLERANCE)));
+            await writeJsonFile(join(params.artifactsDir, "steps", "deterministic-progress.json"), {
+                iteration: index + 1,
+                max_runs: params.maxRuns,
+                cycle_detected: true,
+                cycling_obligations: cycle,
+                summary: "Finalization kept revisiting prior artifact states without net " +
+                    `progress; stopping. Cycling obligations: ${cycle.join(" -> ")}.`,
+                timestamp: new Date().toISOString(),
+            });
+            return {
+                kind: "blocked",
+                state: result.audit_state,
+                bundle: result.updated_bundle,
+                reason: "Finalization is not converging: deterministic executors kept revisiting " +
+                    `prior artifact states (${cycle.join(" -> ")}). The report has been ` +
+                    "rendered; review whether these obligations are erroneously invalidating each other.",
+            };
+        }
     }
     const bundle = await loadArtifactBundle(params.artifactsDir);
     const state = deriveAuditState(bundle);

package/dist/cli/prompts.js

@@ -68,6 +68,8 @@ export function renderDispatchReviewPrompt(params) {
             "`host_concurrency_limit` records any detected hard host cap that contributed to `wave_size`.",
             "",
             "For each wave: use the `task` tool (or equivalent subagent dispatch) to launch up to `wave_size` subagents in parallel (one per entry), wait for all to finish, then start the next wave.",
+            "",
+            'If a subagent reports a host session/usage limit (e.g. "hit your session limit · resets <time>") instead of submitting its result, do not immediately re-dispatch it: run merge-and-ingest with the results you did get, then wait until the stated reset time before running next-step to re-dispatch the remaining packets. Re-dispatching into an active limit just loses the wave.',
         ]
         : [
             "Read this generated dispatch plan:",

package/dist/cli.d.ts

@@ -1,4 +1,3 @@
-export { resolveHostDispatchCapability, DIRECT_CLI_DEFAULTS, getFlag, hasFlag, getOptionalBooleanFlag, getArtifactsDir, getRootDir, getBatchResultsDir, getMaxRuns, getAgentBatchSize, getParallelWorkers, getTimeoutMs, chunkArray, getUiMode, looksLikeCliFlag, countLines, warnIfNotGitRepo, } from "./cli/args.js";
 import { getFlag, hasFlag, getArtifactsDir, getRootDir, warnIfNotGitRepo, getBatchResultsDir, getMaxRuns, getAgentBatchSize, getParallelWorkers, getTimeoutMs, chunkArray, getUiMode, looksLikeCliFlag, countLines } from "./cli/args.js";
 export declare const cliTestUtils: {
     defaults: {

package/dist/cli.js

@@ -24,9 +24,7 @@ import { getSessionConfigPath, loadSessionConfig, readSessionConfigFile, } from
 import { clearDispatchFiles, ensureSupervisorDirs, } from "./io/runArtifacts.js";
 import { runAuditCodeMcpServer } from "./mcp/server.js";
 import { scheduleWave, buildProviderModelKey, readQuotaState, resolveLimits, resolveHostActiveSubagentLimit, probeProvider, computeMaxSafeConcurrency, getQuotaStatePath, lookupDiscoveredLimits, setQuotaStateDir, } from "./quota/index.js";
-// Re-exports from extracted modules
-export { resolveHostDispatchCapability, DIRECT_CLI_DEFAULTS, getFlag, hasFlag, getOptionalBooleanFlag, getArtifactsDir, getRootDir, getBatchResultsDir, getMaxRuns, getAgentBatchSize, getParallelWorkers, getTimeoutMs, chunkArray, getUiMode, looksLikeCliFlag, countLines, warnIfNotGitRepo, } from "./cli/args.js";
-import { DIRECT_CLI_DEFAULTS, getFlag, hasFlag, fromBase64Url, taskResultPath, readStdinText, getArtifactsDir, getRootDir, warnIfNotGitRepo, getBatchResultsDir, getMaxRuns, getAgentBatchSize, getParallelWorkers, getTimeoutMs, getExplicitProvider, getHostModel, getHostMaxActiveSubagents, getQuotaProbeMode, resolveRunProviderName, chunkArray, getUiMode, looksLikeCliFlag, countLines, } from "./cli/args.js";
+import { DIRECT_CLI_DEFAULTS, getFlag, hasFlag, fromBase64Url, taskResultPath, isCanonicalResultFilename, readStdinText, getArtifactsDir, getRootDir, warnIfNotGitRepo, getBatchResultsDir, getMaxRuns, getAgentBatchSize, getParallelWorkers, getTimeoutMs, getExplicitProvider, getHostModel, getHostMaxActiveSubagents, getQuotaProbeMode, resolveRunProviderName, chunkArray, getUiMode, looksLikeCliFlag, countLines, } from "./cli/args.js";
 import { WORKER_RESULT_CONTRACT_VERSION, buildWorkerResult, formatAuditResultValidationError, } from "./cli/workerResult.js";
 import { DISPATCH_RESULT_MAP_FILENAME, ACTIVE_DISPATCH_FILENAME, resolveRunScopedArg, loadDispatchResultMap, entriesByTaskId, buildPendingAuditTasks, prepareDispatchArtifacts, } from "./cli/dispatch.js";
 import { buildLineIndex, buildLineIndexForPaths, addFileLineCountHints, } from "./cli/lineIndex.js";
@@ -510,20 +508,29 @@ async function cmdMergeAndIngest(argv) {
     const fallbackByTaskId = new Map();
     for (const filename of files) {
         const filePath = resolve(join(taskResultsDir, filename));
-        if (!expectedPaths.has(filePath)) {
-            spuriousFileCount++;
-            try {
-                const raw = await readFile(filePath, "utf8");
-                const parsed = JSON.parse(raw);
-                if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-                    const tid = typeof parsed.task_id === "string"
-                        ? String(parsed.task_id) : undefined;
-                    if (tid && !fallbackByTaskId.has(tid)) {
-                        fallbackByTaskId.set(tid, parsed);
-                    }
+        if (expectedPaths.has(filePath))
+            continue;
+        // Not part of this round's plan. Still read it so a current task can be
+        // recovered by task_id (e.g. a subagent wrote a valid result under a
+        // non-assigned name).
+        try {
+            const raw = await readFile(filePath, "utf8");
+            const parsed = JSON.parse(raw);
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                const tid = typeof parsed.task_id === "string"
+                    ? String(parsed.task_id) : undefined;
+                if (tid && !fallbackByTaskId.has(tid)) {
+                    fallbackByTaskId.set(tid, parsed);
                 }
             }
-            catch { /* not parseable — skip */ }
+        }
+        catch { /* not parseable — skip */ }
+        // Only genuinely stray files are "spurious". Canonical per-task result files
+        // (<stem>_<digest>.json) left by prior deepening rounds in the same
+        // task-results/ dir are legitimate and must not inflate the count or bury
+        // the real stray-file signal (3 -> 191 over a run before this fix).
+        if (!isCanonicalResultFilename(filename)) {
+            spuriousFileCount++;
             process.stderr.write(`[merge-and-ingest] Warning: unexpected file in task-results/: ${filename}\n`);
         }
     }

package/dist/extractors/fileInventory.js

@@ -1,10 +1,23 @@
 import { normalizeExtractorPath } from "./pathPatterns.js";
 import { LANGUAGE_BY_EXTENSION } from "./languageMap.generated.js";
+// The generated linguist map resolves a few common extensions to obscure
+// languages that outrank the everyday one (".md" -> GCC machine description,
+// ".yml"/".yaml" -> MiniYAML). These overrides win over the generated map so the
+// file inventory does not mislabel ordinary docs/config. Keep this list small
+// and limited to extensions whose generated mapping is demonstrably wrong.
+const EXTENSION_LANGUAGE_OVERRIDES = {
+    md: "markdown",
+    markdown: "markdown",
+    yaml: "yaml",
+    yml: "yaml",
+};
 function inferLanguage(path) {
     const normalized = normalizeExtractorPath(path);
     const base = normalized.split("/").pop() ?? normalized;
-    const extension = base.includes(".") ? base.split(".").pop() ?? "" : "";
-    return LANGUAGE_BY_EXTENSION[extension] ?? "unknown";
+    const extension = (base.includes(".") ? base.split(".").pop() ?? "" : "").toLowerCase();
+    return (EXTENSION_LANGUAGE_OVERRIDES[extension] ??
+        LANGUAGE_BY_EXTENSION[extension] ??
+        "unknown");
 }
 export function buildRepoManifest(repositoryName, files) {
     return {

package/dist/extractors/graph.js

@@ -262,6 +262,7 @@ export async function buildGraphBundleFromFs(repoManifest, root, disposition, op
     const rootPath = resolve(root);
     const dispositionMap = buildDispositionMap(disposition);
     const fileContents = {};
+    const skippedFiles = [];
     await Promise.all(repoManifest.files.map(async (file) => {
         const status = dispositionMap.get(file.path);
         if ((status && isAuditExcludedStatus(status)) ||
@@ -277,10 +278,19 @@ export async function buildGraphBundleFromFs(repoManifest, root, disposition, op
         try {
             fileContents[file.path] = await readFile(absolutePath, "utf8");
         }
-        catch {
-            // Best-effort graph extraction should not block structure planning.
+        catch (e) {
+            // Best-effort graph extraction should not block structure planning,
+            // but record the skip so a coverage gap is observable to operators.
+            skippedFiles.push({ path: file.path, error: e.code ?? String(e) });
         }
     }));
+    if (skippedFiles.length > 0) {
+        process.stderr.write("[audit-code] graph: skipped " +
+            skippedFiles.length +
+            " unreadable file(s): " +
+            skippedFiles.map((s) => s.path + " (" + s.error + ")").join(", ") +
+            "\n");
+    }
     return buildGraphBundle(repoManifest, disposition, { ...options, fileContents });
 }
 export function buildGraphBundle(repoManifest, disposition, options = {}) {

package/dist/io/artifacts.d.ts

@@ -89,7 +89,9 @@ export declare const ARTIFACT_DEFINITIONS: {
 export declare const ARTIFACT_FILE_TO_BUNDLE_KEY: Record<string, ArtifactBundleKey>;
 export declare function getArtifactValue(bundle: ArtifactBundle, artifactName: string): unknown;
 export declare function loadArtifactBundle(root: string): Promise<ArtifactBundle>;
-export declare function writeCoreArtifacts(root: string, bundle: ArtifactBundle): Promise<void>;
+export declare function writeCoreArtifacts(root: string, bundle: ArtifactBundle, options?: {
+    prune?: boolean;
+}): Promise<void>;
 export declare function cleanupIntermediateArtifacts(root: string): Promise<string[]>;
 export declare function promoteFinalAuditReport(params: {
     artifactsDir: string;

package/dist/io/artifacts.js

@@ -79,13 +79,29 @@ export async function loadArtifactBundle(root) {
     bundle.tooling_manifest = await buildToolingManifest();
     return bundle;
 }
-export async function writeCoreArtifacts(root, bundle) {
+export async function writeCoreArtifacts(root, bundle, options = {}) {
     const bundleRecord = bundle;
     for (const entry of ARTIFACT_ENTRIES) {
         const [key, definition] = entry;
         const value = bundleRecord[key];
+        const path = join(root, definition.fileName);
         if (value !== undefined) {
-            await definition.write(join(root, definition.fileName), value);
+            await definition.write(path, value);
+        }
+        else if (options.prune) {
+            // The bundle is authoritative. An executor that clears an artifact to
+            // `undefined` (to force a downstream rebuild — e.g. planning/ingestion
+            // reset audit_report) intends the file gone; if it lingers it reloads as a
+            // stale "present" artifact with no metadata entry, which deriveAuditState
+            // reads as satisfied — masking the invalidation and stranding a stale
+            // report. Only callers passing the full accumulated bundle may prune.
+            try {
+                await unlink(path);
+            }
+            catch (error) {
+                if (!isFileMissingError(error))
+                    throw error;
+            }
         }
     }
 }

package/dist/orchestrator/advance.js

@@ -1,7 +1,8 @@
 import { decideNextStep, findObligation } from "./nextStep.js";
 import { deriveAuditState } from "./state.js";
 import { computeArtifactMetadata } from "./artifactMetadata.js";
-import { runIntakeExecutor, runStructureExecutor, runPlanningExecutor, runResultIngestionExecutor, runRuntimeValidationExecutor, runRuntimeValidationUpdateExecutor, runSynthesisExecutor, runSynthesisNarrativeExecutor, runDesignAssessmentExecutor, runDesignReviewAutoComplete, runExternalAnalyzerImportExecutor, } from "./internalExecutors.js";
+import { runIntakeExecutor, runStructureExecutor, runPlanningExecutor, runResultIngestionExecutor, runRuntimeValidationExecutor, runRuntimeValidationUpdateExecutor, runDesignAssessmentExecutor, runDesignReviewAutoComplete, runExternalAnalyzerImportExecutor, } from "./internalExecutors.js";
+import { runSynthesisExecutor, runSynthesisNarrativeExecutor, } from "./synthesisExecutors.js";
 import { runAutoFixExecutor } from "./autoFixExecutor.js";
 import { runSyntaxResolutionExecutor } from "./syntaxResolutionExecutor.js";
 import { runGraphEnrichmentExecutor } from "./graphEnrichmentExecutor.js";

package/dist/orchestrator/artifactFreshness.js

@@ -15,9 +15,19 @@ export function stableStringify(value) {
         .sort(([a], [b]) => a.localeCompare(b));
     return `{${entries.map(([key, item]) => `${JSON.stringify(key)}:${stableStringify(item)}`).join(",")}}`;
 }
+// Artifacts that stamp a wall-clock `generated_at` on every (re)build. The
+// timestamp is provenance, not content: two rebuilds with identical data but
+// different timestamps must hash equal, or the artifact's revision churns every
+// rebuild and perpetually re-stales its downstreams (e.g. audit-report.md
+// depends on design_assessment) — a finalization-oscillation hazard.
+const GENERATED_AT_STRIPPED_ARTIFACTS = new Set([
+    "repo_manifest.json",
+    "tooling_manifest.json",
+    "audit_plan_metrics.json",
+    "design_assessment.json",
+]);
 export function normalizeForMetadataHash(artifactName, value) {
-    if ((artifactName === "repo_manifest.json" ||
-        artifactName === "tooling_manifest.json") &&
+    if (GENERATED_AT_STRIPPED_ARTIFACTS.has(artifactName) &&
         value &&
         typeof value === "object" &&
         !Array.isArray(value)) {

package/dist/orchestrator/artifactMetadata.d.ts

@@ -1,4 +1,5 @@
 import type { ArtifactMetadataManifest } from "../types/artifactMetadata.js";
 import type { ArtifactBundle } from "../io/artifacts.js";
 export declare function present(bundle: ArtifactBundle, artifactName: string): boolean;
+export declare function computeArtifactStateSignature(bundle: ArtifactBundle): string;
 export declare function computeArtifactMetadata(bundle: ArtifactBundle, previous?: ArtifactMetadataManifest, updatedArtifacts?: Iterable<string>): ArtifactMetadataManifest;

package/dist/orchestrator/artifactMetadata.js

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { getArtifactValue } from "../io/artifacts.js";
 import { buildReverseDependencyMap, hashArtifactValue, stableStringify, } from "./artifactFreshness.js";
 const REVERSE_DEPENDENCY_MAP = buildReverseDependencyMap();
@@ -31,6 +32,20 @@ export function present(bundle, artifactName) {
     const value = getArtifactValue(bundle, artifactName);
     return value !== undefined && value !== null;
 }
+// Stable signature of the overall artifact state, keyed on per-artifact CONTENT
+// hashes — deliberately NOT revisions, which only ever increment. A
+// deterministic advance loop that revisits a signature it already produced this
+// run is cycling (e.g. a runtime_validation <-> synthesis staleness ping-pong);
+// the content-hash basis catches that even while revisions churn underneath.
+export function computeArtifactStateSignature(bundle) {
+    const metadata = bundle.artifact_metadata;
+    if (!metadata)
+        return "no-metadata";
+    const entries = Object.entries(metadata.artifacts)
+        .map(([name, entry]) => `${name}:${entry.content_hash}`)
+        .sort();
+    return createHash("sha256").update(entries.join("\n")).digest("hex");
+}
 export function computeArtifactMetadata(bundle, previous, updatedArtifacts = []) {
     const artifacts = {};
     const updated = new Set(updatedArtifacts);

package/dist/orchestrator/autoFixExecutor.d.ts

@@ -1,3 +1,3 @@
 import type { ArtifactBundle } from "../io/artifacts.js";
-import type { ExecutorRunResult } from "./internalExecutors.js";
+import type { ExecutorRunResult } from "./executorResult.js";
 export declare function runAutoFixExecutor(bundle: ArtifactBundle, root: string): ExecutorRunResult;

package/dist/orchestrator/autoFixExecutor.js

@@ -49,6 +49,7 @@ export function runAutoFixExecutor(bundle, root) {
         }
     }
     const executedTools = [];
+    const toolTimings = [];
     // JS, TS, HTML, CSS, JSON, YAML, MD
     if (hasPrettierConfig(root) &&
         (extensions.has("ts") ||
@@ -61,16 +62,19 @@ export function runAutoFixExecutor(bundle, root) {
             extensions.has("yml") ||
             extensions.has("yaml") ||
             extensions.has("md"))) {
+        const prettierStart = Date.now();
         if (tryRunConfiguredFormatter(root, [
             ...resolveNodeTool(root, join("node_modules", "prettier", "bin", "prettier.cjs"), ["--write", "."], "prettier --write ."),
             { command: "prettier", args: ["--write", "."], display: "prettier --write ." },
             { command: "npx", args: ["--yes", "prettier", "--write", "."], display: "npx --yes prettier --write ." },
         ])) {
             executedTools.push("prettier");
+            toolTimings.push({ tool: "prettier", duration_ms: Date.now() - prettierStart });
         }
     }
     // Python
     if (extensions.has("py")) {
+        const blackStart = Date.now();
         if (tryRunConfiguredFormatter(root, [
             { command: "black", args: ["."], display: "black ." },
             { command: "python", args: ["-m", "black", "."], display: "python -m black ." },
@@ -78,28 +82,34 @@ export function runAutoFixExecutor(bundle, root) {
             { command: "pipx", args: ["run", "black", "."], display: "pipx run black ." },
         ])) {
             executedTools.push("black");
+            toolTimings.push({ tool: "black", duration_ms: Date.now() - blackStart });
         }
     }
     // SQL
     if (extensions.has("sql")) {
+        const sqlfluffStart = Date.now();
         if (tryRunConfiguredFormatter(root, [
             { command: "sqlfluff", args: ["fix", "--force", "."], display: "sqlfluff fix --force ." },
             { command: "uvx", args: ["sqlfluff", "fix", "--force", "."], display: "uvx sqlfluff fix --force ." },
             { command: "pipx", args: ["run", "sqlfluff", "fix", "--force", "."], display: "pipx run sqlfluff fix --force ." },
         ])) {
             executedTools.push("sqlfluff");
+            toolTimings.push({ tool: "sqlfluff", duration_ms: Date.now() - sqlfluffStart });
         }
     }
     // Go
     if (extensions.has("go")) {
+        const gofmtStart = Date.now();
         if (tryRunConfiguredFormatter(root, [
             { command: "gofmt", args: ["-w", "."], display: "gofmt -w ." },
         ])) {
             executedTools.push("gofmt");
+            toolTimings.push({ tool: "gofmt", duration_ms: Date.now() - gofmtStart });
         }
     }
     const resultsArtifact = {
         executed_tools: executedTools,
+        tool_timings: toolTimings,
         timestamp: new Date().toISOString(),
     };
     return {

package/dist/orchestrator/executorResult.d.ts

@@ -0,0 +1,12 @@
+import type { ArtifactBundle } from "../io/artifacts.js";
+/**
+ * Uniform result of running one audit executor: the updated artifact bundle, the
+ * artifact filenames it wrote (which drive metadata/staleness bookkeeping in
+ * advanceAudit), and a one-line human progress summary. Shared by every executor
+ * module so they need not depend on the internalExecutors barrel.
+ */
+export interface ExecutorRunResult {
+    updated: ArtifactBundle;
+    artifacts_written: string[];
+    progress_summary: string;
+}

package/dist/orchestrator/executorResult.js

@@ -0,0 +1 @@
+export {};

package/dist/orchestrator/fileIntegrity.d.ts

@@ -2,6 +2,7 @@ import type { RepoManifest } from "../types.js";
 export interface FileIntegrityResult {
     changed_files: string[];
     missing_files: string[];
+    io_errors: string[];
     is_clean: boolean;
 }
 export declare function checkFileIntegrity(root: string, manifest: RepoManifest, scope?: string[]): Promise<FileIntegrityResult>;

package/dist/orchestrator/fileIntegrity.js

@@ -9,6 +9,7 @@ async function hashFile(absolutePath) {
 export async function checkFileIntegrity(root, manifest, scope) {
     const changed = [];
     const missing = [];
+    const ioErrors = [];
     const scopeSet = scope ? new Set(scope) : null;
     const files = scopeSet
         ? manifest.files.filter((f) => scopeSet.has(f.path))
@@ -29,13 +30,21 @@ export async function checkFileIntegrity(root, manifest, scope) {
                 changed.push(record.path);
             }
         }
-        catch {
-            missing.push(record.path);
+        catch (err) {
+            const code = err.code;
+            if (code === "ENOENT") {
+                missing.push(record.path);
+            }
+            else {
+                console.warn(`fileIntegrity: I/O error on ${record.path}: ${code ?? String(err)}`);
+                ioErrors.push(record.path);
+            }
         }
     }
     return {
         changed_files: changed,
         missing_files: missing,
-        is_clean: changed.length === 0 && missing.length === 0,
+        io_errors: ioErrors,
+        is_clean: changed.length === 0 && missing.length === 0 && ioErrors.length === 0,
     };
 }

package/dist/orchestrator/flowRequeue.js

@@ -1,17 +1,4 @@
-function isLens(value) {
-    return [
-        "correctness",
-        "architecture",
-        "maintainability",
-        "security",
-        "reliability",
-        "performance",
-        "data_integrity",
-        "tests",
-        "operability",
-        "config_deployment",
-    ].includes(String(value));
-}
+import { isLens } from "../types.js";
 function getExternalSignalPaths(externalAnalyzerResults) {
     const results = Array.isArray(externalAnalyzerResults?.results)
         ? externalAnalyzerResults.results

package/dist/orchestrator/graphEnrichmentExecutor.d.ts

@@ -1,5 +1,5 @@
 import type { ArtifactBundle } from "../io/artifacts.js";
-import type { ExecutorRunResult } from "./internalExecutors.js";
+import type { ExecutorRunResult } from "./executorResult.js";
 import type { AnalyzerSetting } from "@audit-tools/shared";
 import type { LanguageAnalyzer } from "../extractors/analyzers/types.js";
 import { type EdgeReasoningResults } from "./edgeReasoning.js";