akm-cli 0.9.14 → 0.9.15-beta.2

package/dist/commands/improve/improve.js

@@ -22,11 +22,12 @@ import { akmIndex } from "../../indexer/indexer.js";
 import { collectPendingMemories } from "../../indexer/passes/memory-inference.js";
 import { resolveEntryContentDir, resolveSourceEntries } from "../../indexer/search/search-source.js";
 import { collectEngineCredentialValues } from "../../integrations/agent/engine-resolution.js";
-import { installLlmUsagePersistence } from "../../llm/usage-persist.js";
+import { installLlmUsagePersistence, LLM_USAGE_EVENT } from "../../llm/usage-persist.js";
 import { isGitBackedStash, listGitChangedPaths, resolveWritableOverride, saveGitStash, } from "../../sources/providers/git.js";
 import { closeDatabase, openExistingDatabase } from "../../storage/repositories/index-connection.js";
 import { getEntryCount } from "../../storage/repositories/index-entries-repository.js";
 import { openSqliteReadSnapshot, SqliteReadSnapshotUnavailableError } from "../../storage/sqlite-read-snapshot.js";
+import { summarizeLlmUsageCrossTab } from "../health/llm-usage.js";
 import { drainProposals } from "../proposal/drain.js";
 import { resolveDrainPolicy } from "../proposal/drain-policies.js";
 import { describeGatedLanes, isAutonomyLaneAllowed } from "./autonomy-gate.js";
@@ -34,7 +35,8 @@ import { akmDistill } from "./distill.js";
 // Eligibility / candidate-selection predicates live in ./eligibility.
 import { buildLatestProposalTsMap, collectEligibleRefs, collectEligibleRefsReadOnly, memoryCleanupParentRef, resolveImproveScope, shouldAnalyzeMemoryCleanup, } from "./eligibility.js";
 import { countEvalCases } from "./eval-cases.js";
-import { resolveImprovePlan, resolveImproveStrategy } from "./improve-strategies.js";
+import { projectResolvedProcessRouting, resolveImprovePlan, resolveImproveStrategy, shouldSkipRef, } from "./improve-strategies.js";
+import { buildImproveUsageReport } from "./improve-usage-report.js";
 import { improveLockPath, releaseImproveLock, tryAcquireImproveLock } from "./locks.js";
 // The cycle loop / post-loop / maintenance stages live in ./loop-stages.
 import { runImproveLoopStage, runImprovePostLoopStage } from "./loop-stages.js";
@@ -402,8 +404,12 @@ function resolveImproveRunSetup(options) {
     const _earlyConfig = options.config ?? loadConfig();
     const configuredImproveProfile = resolveImproveStrategy(options.strategy, _earlyConfig).config;
     const resolvedPlan = options.resolvedPlan ??
+        // #800/#957 round 3 — same dry-run exemption as improve-cli.ts's own
+        // resolveImprovePlan call: a dry run never dispatches, so a strategy left
+        // fully disabled by an unreachable credential must not abort here either.
         resolveImprovePlan(options.strategy, _earlyConfig, {
             repairValidationFailures: options.repairValidationFailures,
+            allowAllDisabled: options.dryRun,
         });
     const selectedStrategy = resolvedPlan.strategy;
     const improveSensitiveValues = collectEngineCredentialValues(_earlyConfig);
@@ -759,6 +765,7 @@ export function buildDryRunResult(run, collected, preparation) {
             }
             : {}),
         ...(strategyFilteredRefs.length > 0 ? { strategyFilteredRefs } : {}),
+        ...(run.resolvedPlan.engineUnavailable.length > 0 ? { skippedProcesses: run.resolvedPlan.engineUnavailable } : {}),
         ...(preparation?.proactiveMaintenance ? { proactiveMaintenance: preparation.proactiveMaintenance } : {}),
     };
 }
@@ -783,6 +790,17 @@ function buildResultExecutionPlan(run, preparation, rawProfileEligibleRefs, stra
         removed: strategyFilteredRefs.length,
         reason: "all enabled per-ref processes refuse the asset type",
     };
+    // #947 — per-process resolved engine/model/notices, plus how many of this
+    // run's effective refs each ref-scoped process (reflect/distill/consolidate)
+    // would act on. Counts only (not a per-ref matrix) to bound result_json size.
+    const REF_SCOPED_PROCESSES = new Set(["reflect", "distill", "consolidate"]);
+    const processes = projectResolvedProcessRouting(resolvedPlan).map((row) => {
+        if (!REF_SCOPED_PROCESSES.has(row.process))
+            return row;
+        const eligibleRefs = preparation.loopRefs.filter((entry) => !shouldSkipRef(entry.ref, row.process, resolvedPlan.strategy.config)
+            .skip).length;
+        return { ...row, eligibleRefs };
+    });
     const proactive = preparation.planning.proactive
         ? {
             ...preparation.planning.proactive,
@@ -823,6 +841,7 @@ function buildResultExecutionPlan(run, preparation, rawProfileEligibleRefs, stra
         effectiveLimit,
         replayBudget: preparation.planning.replayBudget,
         gates: [profileGate, ...preparation.planning.gates],
+        processes,
         ...(proactive ? { proactive } : {}),
         consolidation,
         stageConfig: {
@@ -1281,7 +1300,7 @@ async function runImproveStageSequence(args) {
  */
 function finalizeImproveResult(args) {
     const { guidance, memorySummary, memoryCleanupPlan, strategyFilteredRefs, rawPlannedRefs, indexSnapshot, triageDrain, eventsCtx, } = args;
-    const { selectedStrategy, scope, options, primaryStashDir, startMs } = args.run;
+    const { selectedStrategy, scope, options, primaryStashDir, startMs, resolvedPlan } = args.run;
     const { preparation, consolidation, memoryInference, graphExtraction, cycleMetrics, reflectsWithErrorContext, memoryInferenceDurationMs, graphExtractionDurationMs, orphansPurged, proposalsExpired, allWarnings, deadUrls, deadUrlCoverage, finalActions, } = args.seq;
     // C1 (13-bus-factor): fold the per-ref `distill-skipped` rows (~13k/run,
     // ~91% of result_json bytes) into a bounded aggregate BEFORE persistence.
@@ -1289,6 +1308,22 @@ function finalizeImproveResult(args) {
     // the unbounded row list never reaches result_json. Reflect skip counters
     // below still read `finalActions` (reflect skips are not folded).
     const { actions: persistedActions, aggregate: distillSkippedAggregate } = foldDistillSkipped(finalActions);
+    // #944 — this run's LLM call/token accounting, split by process x engine x
+    // model, plus which enabled processes made zero calls and why. `llm_usage`
+    // events carry no runId column, so bound the read to this run's own wall
+    // clock — the same per-run event-scoping technique `health/windows.ts`
+    // already uses for wall time. `until` is "now" (assembly happens at
+    // teardown, after every LLM call this run will make has already emitted
+    // its event).
+    const usageEvents = readEvents({ since: new Date(startMs).toISOString(), type: LLM_USAGE_EVENT }, eventsCtx).events;
+    const usageReport = buildImproveUsageReport({
+        resolvedPlan,
+        byProcessEngineModel: summarizeLlmUsageCrossTab(usageEvents),
+        strategyFilteredRefsCount: strategyFilteredRefs.length,
+        loopRefs: preparation.loopRefs,
+        persistedActions,
+        distillSkippedAggregate,
+    });
     const notices = collectImproveNotices({
         resolvedPlan: args.run.resolvedPlan,
         actions: finalActions,
@@ -1336,6 +1371,8 @@ function finalizeImproveResult(args) {
             }
             : {}),
         ...(strategyFilteredRefs.length > 0 ? { strategyFilteredRefs } : {}),
+        ...(resolvedPlan.engineUnavailable.length > 0 ? { skippedProcesses: resolvedPlan.engineUnavailable } : {}),
+        ...(usageReport ? { usageReport } : {}),
         actions: persistedActions,
         ...(distillSkippedAggregate ? { distillSkipped: distillSkippedAggregate } : {}),
         ...(preparation.validationFailures.length > 0 ? { validationFailures: preparation.validationFailures } : {}),

package/dist/commands/improve/locks.js

@@ -1,13 +1,12 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
-import fs from "node:fs";
 import path from "node:path";
 import { ConfigError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
-import { createLockPayload, probeLock, reclaimStaleLock, releaseLock, tryAcquireLockSync, } from "../../core/file-lock.js";
+import { releaseLock } from "../../core/file-lock.js";
 import { tryWithMaintenanceStartBarrier, withMaintenanceStartBarrier } from "../../core/maintenance-barrier.js";
-import { describeInaccessiblePath } from "../../core/path-access.js";
+import { formatLockHolderPid, tryAcquireRunLock } from "../../core/run-lock.js";
 import { warn } from "../../core/warn.js";
 export function improveLockPath(lockBaseDir) {
     return path.join(lockBaseDir, "improve.lock");
@@ -37,85 +36,36 @@ export function tryAcquireImproveLock(lockPath, skipIfLocked, eventsCtx) {
     return result;
 }
 function tryAcquireImproveLockUnlocked(lockPath, skipIfLocked, onRecovered) {
-    fs.mkdirSync(path.dirname(lockPath), { recursive: true });
-    const lockPayload = () => createLockPayload({ startedAt: new Date().toISOString() });
-    let ownership = tryAcquireLockSync(lockPath, lockPayload());
-    if (ownership) {
-        return { state: "acquired", ownership };
-    }
-    // No `staleAfterMs`: only a verifiably dead holder is ever reclaimed. A
-    // wedged-but-alive `akm improve` (SQLite WAL + busy_timeout + BEGIN
-    // IMMEDIATE already serialize concurrent writes to state.db at the
-    // correctness layer, so this lock only avoids duplicate LOGICAL work) must
-    // not have its lease silently taken away purely because a clock elapsed —
-    // that was the #872-shaped hazard here: a live holder passed the
-    // PID-liveness check forever, so only a multi-hour age window could ever
-    // free it, stranding every `akm improve --skip-if-locked` invocation for
-    // up to that long while reporting success.
-    const probe = probeLock(lockPath);
-    // Race: the holder released the lock between our failed `tryAcquireLockSync`
-    // and this probe, so the probe sees no file (`absent`). Retry acquisition once
-    // rather than falling through to the contended skip/throw below — otherwise we
-    // would warn/throw with a null PID for a lock that nobody actually holds.
-    // (Mirrors the absent/stale reclaim-and-retry in `acquireExtractSessionLock`.)
-    if (probe.state === "absent") {
-        ownership = tryAcquireLockSync(lockPath, lockPayload());
-        if (ownership) {
-            return { state: "acquired", ownership };
-        }
-        // Re-grabbed by another racer in the window — fall through and treat as held.
-    }
-    // A lock we cannot READ is a hard stop, never a reclaim candidate (#791): the
-    // holder may be alive and working, and we simply lack permission to see it.
-    // Stealing the lease here would let two improve runs mutate the same bundle.
-    if (probe.state === "inaccessible") {
-        throw new ConfigError(`improve lock exists but is not readable: ${describeInaccessiblePath(lockPath, probe.code)}.`, "DATA_DIR_UNREADABLE");
-    }
-    const rawContent = probe.state === "absent" ? undefined : probe.rawContent;
-    const lock = rawContent
-        ? (() => {
-            try {
-                return JSON.parse(rawContent);
-            }
-            catch {
-                return null;
-            }
-        })()
-        : null;
-    if (probe.state === "stale") {
-        if (!reclaimStaleLock(lockPath, probe)) {
-            if (skipIfLocked) {
-                warn("[improve] lock changed ownership during stale recovery; skipping (--skip-if-locked)");
-                return { state: "skipped" };
-            }
-            throw new ConfigError(`akm improve is already running. Delete ${lockPath} to force.`, "INVALID_CONFIG_FILE");
-        }
-        onRecovered({
-            eventType: "improve_lock_recovered",
-            metadata: {
-                lockName: "improve",
-                stalePid: lock?.pid ?? null,
-                lockedAt: lock?.startedAt ?? null,
-                recoveredAt: new Date().toISOString(),
-                lockAgeMs: probe.ageMs ?? null,
-                reason: probe.reason === "pid_dead" ? "pid_not_alive" : probe.reason,
-            },
-        });
-        ownership = tryAcquireLockSync(lockPath, lockPayload());
-        if (ownership) {
-            return { state: "acquired", ownership };
-        }
-        if (skipIfLocked) {
-            warn("[improve] lock acquired by another run during stale recovery; skipping (--skip-if-locked)");
-            return { state: "skipped" };
-        }
-        throw new ConfigError(`akm improve is already running. Delete ${lockPath} to force.`, "INVALID_CONFIG_FILE");
+    // Mechanics (PID-liveness-only acquire/probe/absent-race-retry/stale-reclaim)
+    // live in the shared `core/run-lock.ts` module (#956) — this wrapper only
+    // owns improve's own policy: what "held" means (skip vs throw) and the
+    // improve_lock_recovered audit event.
+    const result = tryAcquireRunLock(lockPath, {
+        label: "improve",
+        onReclaimed: (info) => {
+            onRecovered({
+                eventType: "improve_lock_recovered",
+                metadata: {
+                    lockName: "improve",
+                    stalePid: info.holderPid,
+                    lockedAt: info.lockedAt,
+                    recoveredAt: new Date().toISOString(),
+                    lockAgeMs: info.ageMs,
+                    reason: info.reason,
+                },
+            });
+        },
+    });
+    if (result.state === "acquired") {
+        return { state: "acquired", ownership: result.ownership };
     }
+    const { startedAt } = result.holder;
+    const pid = formatLockHolderPid(result.holder);
     if (skipIfLocked) {
-        warn(`[improve] another improve run holds the lock (PID ${lock?.pid}, started ${lock?.startedAt}); skipping (--skip-if-locked)`);
+        warn(`[improve] another improve run holds the lock (PID ${pid}, started ${startedAt}); skipping (--skip-if-locked)`);
         return { state: "skipped" };
     }
-    throw new ConfigError(`akm improve is already running (PID ${lock?.pid}, started ${lock?.startedAt}). Delete ${lockPath} to force.`, "INVALID_CONFIG_FILE");
+    throw new ConfigError(`akm improve is already running (PID ${pid}, started ${startedAt}). Delete ${lockPath} to force.`, "INVALID_CONFIG_FILE");
 }
 export function releaseImproveLock(ownership) {
     releaseLock(ownership);

package/dist/commands/improve/planner.js

@@ -87,6 +87,7 @@ export function buildImproveExecutionPlan(input) {
         },
         gates: input.gates.map((gate) => ({ ...gate })),
         effectiveRefs,
+        processes: input.processes.map((row) => ({ ...row })),
         ...(input.proactive
             ? {
                 proactive: {

package/dist/commands/improve/preparation.js

@@ -230,7 +230,15 @@ function planConsolidationPass(args) {
             readOnly: eventsCtx?.readOnly === true,
         })
         : { poolSize: 0, candidatePoolSize: 0, dedupPoolSize: 0, memories: [] };
-    const chunkSize = computeSafeChunkSize(resolvedPlan.processes.consolidate.runner?.connection.contextLength ?? DEFAULT_CONTEXT_LENGTH_TOKENS, 500, processConfig?.maxChunkSize);
+    // #800/#957 round 3 — a credential-unavailable consolidate engine still
+    // resolved a context length structurally; read it off the `engineUnavailable`
+    // entry instead of falling back to the generic default, so a dry-run
+    // preview reflects the real engine even when its credential isn't
+    // materialized here.
+    const consolidateUnavailable = resolvedPlan.engineUnavailable.find((item) => item.process === "consolidate");
+    const chunkSize = computeSafeChunkSize(resolvedPlan.processes.consolidate.runner?.connection.contextLength ??
+        consolidateUnavailable?.contextLength ??
+        DEFAULT_CONTEXT_LENGTH_TOKENS, 500, processConfig?.maxChunkSize);
     const profilePassed = !eligibility.consolidateDisabledByProfile;
     const minimumPoolPassed = !eligibility.poolBelowMinSize;
     const deltaPassed = !eligibility.consolidationOnCooldown;

package/dist/commands/improve/reflect.js

@@ -41,7 +41,7 @@ import { DEFAULT_LLM_TIMEOUT_MS } from "../../integrations/agent/config.js";
 import { fallbackAnnouncement, NO_ENGINE_MESSAGE_SUFFIX, NO_ENGINE_REMEDY, withEngineFallback, } from "../../integrations/agent/engine-fallback.js";
 import { acquireLoweredExecutionDispatchLease, dispatchLoweredExecutionRequest, disposeLoweredExecutionDispatchLease, lowerResolvedExecutionRequest, lowerResolvedExecutionRequestWithRunner, } from "../../integrations/agent/execution-lowering.js";
 import { prepareInlineExecution, prepareInlineExecutionWithRunner } from "../../integrations/agent/inline-execution.js";
-import { buildReflectOutputRepairPrompt, buildReflectPrompt, extractDraftConfidence, parseAgentProposalPayload, } from "../../integrations/agent/prompts.js";
+import { buildReflectOutputRepairPrompt, buildReflectPrompt, extractDraftConfidence, parseAgentProposalPayload, REFLECT_CONTENT_CAP, REFLECT_TRUNCATION_MARKER, } from "../../integrations/agent/prompts.js";
 import { runnerIsLlm, runnerSupportsFileWrite } from "../../integrations/agent/runner.js";
 import { collectDispatchSensitiveValues } from "../../integrations/agent/runner-dispatch.js";
 import { isJsonSchemaKnownUnsupported, LlmCallError } from "../../llm/client.js";
@@ -49,6 +49,7 @@ import { callStructured } from "../../llm/structured-call.js";
 import { baseFailureFields, enoentHintMessage, isEnoentFailure } from "../agent/agent-support.js";
 import { isProposalSkipped, listProposalsReadOnly, proposalContent, recordGateDecision, } from "../proposal/repository.js";
 import { checkReflectSize, isValidDescription } from "../proposal/validators/proposal-quality-validators.js";
+import { CHARS_PER_TOKEN, DEFAULT_CONTEXT_LENGTH_TOKENS } from "./consolidate/chunking.js";
 import { deriveLessonRef } from "./distill.js";
 import { runReflectQualityJudge } from "./distill/quality-gate.js";
 import { findAssetFilePath } from "./eligibility.js";
@@ -553,6 +554,17 @@ export function sanitizeReflectPayload(payload, sourceContent, targetRef) {
         warnings.push(`${sizeOutcome.code} — proposed body is ${pct}% of source (${limit}) for ref ${targetRef}. ${cause} Flagged for review.`);
         sizeGuardRatio = { code: sizeOutcome.code, ratio: sizeOutcome.ratio };
     }
+    // Truncation-marker leak (#952) — a model that saw a capped/truncated
+    // asset sometimes echoes the "[truncated ...]" notice verbatim into its
+    // rewrite instead of proposing real content for the missing tail. The
+    // body-length ratio check above does not reliably catch this (a leaked
+    // marker can still fall inside the 50%-250% band). Flag and defer to
+    // human review — same "degrade with a warning" rung as the size guard,
+    // not a new hard reject.
+    const truncationMarkerLeaked = cleanedBody.includes(REFLECT_TRUNCATION_MARKER);
+    if (truncationMarkerLeaked) {
+        warnings.push(`Proposed body for ref ${targetRef} contains the truncation-notice text the model was shown for a capped source asset ("${REFLECT_TRUNCATION_MARKER}"). The model likely echoed the notice instead of writing real content. Flagged for review.`);
+    }
     // Reassemble final content: merged frontmatter + cleaned body.
     // When there is no frontmatter at all (no source fm and no LLM fm), emit body
     // only so we don't add a stray `---` to e.g. a script asset that bypassed the
@@ -566,6 +578,7 @@ export function sanitizeReflectPayload(payload, sourceContent, targetRef) {
         ...(hasFrontmatter ? { frontmatter: mergedFm } : {}),
         warnings,
         ...(sizeGuardRatio ? { sizeGuardRatio } : {}),
+        ...(truncationMarkerLeaked ? { truncationMarkerLeaked } : {}),
     };
 }
 /**
@@ -962,7 +975,9 @@ async function finalizeReflectProposal(args) {
     }
     // 7c. Judge the exact sanitized content that can be persisted. Fail closed
     // on cancellation, transport failure, malformed output, or an invalid score.
-    if (qualityGateEnabled && !sanitizeOutcome.sizeGuardRatio) {
+    // Skipped when the size guard or the truncation-marker leak already fired —
+    // that content is deferred to human review regardless of what the judge says.
+    if (qualityGateEnabled && !sanitizeOutcome.sizeGuardRatio && !sanitizeOutcome.truncationMarkerLeaked) {
         const judgeResult = await runReflectQualityJudge(config, payload.content, assetContent ?? "", feedback, options.chat, {
             runnerSelectionFrozen: true,
             ...(qualityJudgeRunner ? { llmRunner: qualityJudgeRunner } : {}),
@@ -1004,6 +1019,7 @@ async function finalizeReflectProposal(args) {
         outputTelemetry,
         qualityGateSkippedNoJudge,
         sizeGuardRatio: sanitizeOutcome.sizeGuardRatio,
+        truncationMarkerLeaked: sanitizeOutcome.truncationMarkerLeaked,
     });
 }
 /**
@@ -1013,7 +1029,7 @@ async function finalizeReflectProposal(args) {
  * `akmReflect`'s finalize tail.
  */
 function createReflectProposal(args) {
-    const { payload, options, stash, engineName, durationMs, emitReflectFailed, outputTelemetry, qualityGateSkippedNoJudge, sizeGuardRatio, } = args;
+    const { payload, options, stash, engineName, durationMs, emitReflectFailed, outputTelemetry, qualityGateSkippedNoJudge, sizeGuardRatio, truncationMarkerLeaked, } = args;
     // 8. Create the proposal. The proposal queue is the ONLY thing reflect
     // writes — promotion to a real asset is gated by `akm proposal accept`.
     //
@@ -1082,6 +1098,8 @@ function createReflectProposal(args) {
         reviewReasons.push("no-judge-configured");
     if (sizeGuardRatio)
         reviewReasons.push("reflect-size-ratio");
+    if (truncationMarkerLeaked)
+        reviewReasons.push("reflect-truncation-leak");
     if (reviewReasons.length > 0) {
         proposal =
             recordGateDecision(stash, proposal.id, {
@@ -1100,6 +1118,7 @@ function createReflectProposal(args) {
             engine: engineName,
             ...(qualityGateSkippedNoJudge ? { qualityGateSkippedNoJudge: true } : {}),
             ...(sizeGuardRatio ? { sizeGuardRatio: sizeGuardRatio.code, sizeGuardRatioValue: sizeGuardRatio.ratio } : {}),
+            ...(truncationMarkerLeaked ? { truncationMarkerLeaked: true } : {}),
             ...(outputTelemetry ?? {}),
         },
     }, options.eventsCtx);
@@ -1385,7 +1404,7 @@ async function runReflectRefineIterations(args) {
             draftPathsToCleanup.push(iterDraftPath);
             lastDraftPath = iterDraftPath;
         }
-        const { prompt } = buildReflectPrompt({
+        const promptInput = {
             ...(options.ref ? { ref: options.ref } : {}),
             ...(parsedRef?.type ? { type: parsedRef.type } : {}),
             ...(parsedRef?.name ? { name: parsedRef.name } : {}),
@@ -1405,6 +1424,27 @@ async function runReflectRefineIterations(args) {
             // on long bodies (e.g. knowledge/systems/KOKORO_USAGE_GUIDE 8.4KB).
             ...(iterDraftPath ? { draftFilePath: iterDraftPath } : {}),
             ...(outputMode ? { outputMode } : {}),
+        };
+        // #952 — the flat REFLECT_CONTENT_CAP (12 000 chars) exists only to avoid
+        // E2BIG when the prompt travels through CLI argv (agent/SDK runners). The
+        // direct-LLM HTTP path never touches argv, so it can use the resolved
+        // engine's own context window instead. The reserve for "the rest of the
+        // prompt" is measured directly (not guessed): build the same prompt with
+        // the content cap forced to zero and use its length as the overhead, so
+        // feedback/standards/schema-hints/prior-draft size is accounted for
+        // exactly, per this call. A reflect rewrite returns a body roughly the
+        // size of the input, so the budget only spends HALF of the usable window
+        // on input content and reserves the other half for the model's own
+        // output — otherwise a full-context request leaves no room for a
+        // response. Never drops below the flat floor.
+        const contentBudgetChars = runnerIsLlm(runnerSpec) && assetContent?.trim()
+            ? Math.max(REFLECT_CONTENT_CAP, Math.floor(((runnerSpec.connection.contextLength ?? DEFAULT_CONTEXT_LENGTH_TOKENS) * CHARS_PER_TOKEN -
+                buildReflectPrompt({ ...promptInput, contentBudgetChars: 0 }).prompt.length) /
+                2))
+            : undefined;
+        const { prompt } = buildReflectPrompt({
+            ...promptInput,
+            ...(contentBudgetChars !== undefined ? { contentBudgetChars } : {}),
         });
         let iterResult;
         if (runnerIsLlm(runnerSpec)) {

package/dist/commands/models-cli.js

@@ -1,8 +1,48 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
+import { isDeepStrictEqual } from "node:util";
 import { defineGroupCommand, defineJsonCommand, output } from "../cli/shared.js";
-import { copyDefaultModelMap } from "../integrations/agent/model-map.js";
+import { loadConfig } from "../core/config/config.js";
+import { copyDefaultModelMap, loadModelMapLayers, mergedModelMapProfiles, mergeModelMapLayers, } from "../integrations/agent/model-map.js";
+/**
+ * Compute the effective alias table (#946): every (alias, column) pair from
+ * the fully resolved map, labeled with where its value came from.
+ *
+ * `source` compares the installed-only merge against the full (installed +
+ * user) merge for the same pair — identical means the user file never
+ * touched it. `via`/`engine` come from the raw overlaid-but-unresolved
+ * profile (before `engine` indirection is expanded), so a column that
+ * resolves through `{ engine: "local-fast" }` reports which engine it
+ * borrowed its model from.
+ */
+function modelsListRows() {
+    const config = loadConfig();
+    const layers = loadModelMapLayers();
+    const rawProfiles = mergedModelMapProfiles(layers.installed, layers.user);
+    const defaultsOnly = mergeModelMapLayers(layers.installed, undefined, config.engines);
+    const resolved = mergeModelMapLayers(layers.installed, layers.user, config.engines);
+    const rows = [];
+    for (const [alias, columns] of Object.entries(resolved.aliases)) {
+        for (const [column, profile] of Object.entries(columns)) {
+            const raw = rawProfiles[alias]?.[column];
+            const via = raw?.engine !== undefined ? "engine" : "literal";
+            const defaultProfile = defaultsOnly.aliases[alias]?.[column];
+            const source = defaultProfile !== undefined && isDeepStrictEqual(defaultProfile, profile) ? "default" : "user";
+            rows.push({
+                alias,
+                column,
+                model: profile.model,
+                ...(Object.hasOwn(profile, "inference") ? { inference: profile.inference } : {}),
+                source,
+                via,
+                ...(via === "engine" && raw?.engine !== undefined ? { engine: raw.engine } : {}),
+            });
+        }
+    }
+    rows.sort((left, right) => left.alias === right.alias ? left.column.localeCompare(right.column) : left.alias.localeCompare(right.alias));
+    return rows;
+}
 /** Operator-owned model-map lifecycle commands. Alias expansion is consumed through the runtime API. */
 export const modelsCommand = defineGroupCommand({
     meta: { name: "models", description: "Inspect and customize model intent alias defaults" },
@@ -23,5 +63,14 @@ export const modelsCommand = defineGroupCommand({
                 output("models", copyDefaultModelMap({ overwrite: args.overwrite === true }));
             },
         }),
+        list: defineJsonCommand({
+            meta: {
+                name: "list",
+                description: "Show the effective model intent alias table and where each mapping resolved from",
+            },
+            run() {
+                output("models-list", { rows: modelsListRows() });
+            },
+        }),
     },
 });

package/dist/commands/proposal/repository.js

@@ -67,7 +67,7 @@ import { pkgVersion } from "../../version.js";
 import { runBaseChecks } from "../lint/base-linter.js";
 import { formatNewAssetDiff, formatUnifiedDiff } from "./diff-format.js";
 import { isAutomatedProposalSource, isValidProposalSource, PROPOSAL_SOURCES, } from "./proposal-types.js";
-import { hasCanonicalProposalValidator } from "./validators/proposal-validators.js";
+import { canonicalOnlyProposalValidators, hasCanonicalProposalValidator, runProposalValidators, } from "./validators/proposal-validators.js";
 import { repairProposalContent, validateProposal } from "./validators/proposals.js";
 const PROMOTION_LINT_ISSUE_TYPES = new Set(["unquoted-colon", "missing-ref", "stale-path"]);
 // ── Proposal domain types (moved to ./proposal-types.ts, WI-9.8 KILL 1) ─────
@@ -343,7 +343,12 @@ export function createProposal(stashDir, input, ctx) {
     ];
     const mintedBeforeHash = mintBeforeContent !== undefined ? contentHash(mintBeforeContent) : undefined;
     if (hasCanonicalProposalValidator(parsedRef.type)) {
-        const report = validateProposal({
+        // Mint-time gate: structural shape only (generic + canonical-per-type),
+        // NOT the full quality-validator list — see canonicalOnlyProposalValidators'
+        // doc comment (#952 review round 2). Quality validators (including the
+        // blocking reflect-truncation-marker guard) run at `proposal accept` /
+        // drain-promotion time via validateProposal instead.
+        const report = runProposalValidators({
             id: "pending",
             ref: normalizedRef,
             status: "pending",
@@ -353,7 +358,7 @@ export function createProposal(stashDir, input, ctx) {
             payload: { ...input.payload, content: proposalContent },
             changes: mintedChanges,
             proposedTarget: { source: proposalTarget.source, root: targetRoot },
-        });
+        }, canonicalOnlyProposalValidators);
         if (!report.ok) {
             return rejectProposal("invalid_canonical_structure", `Proposal for "${input.ref}" has invalid ${parsedRef.type} structure:\n${report.findings
                 .map((finding) => `[${finding.kind}] ${finding.message}`)

package/dist/commands/proposal/validators/proposal-quality-validators.js

@@ -71,6 +71,7 @@ function refNameTail(inputRef) {
     return parseRefInput(inputRef).name.toLowerCase();
 }
 import { detectTruncatedDescription, TRUNCATION_TRAILING_WORDS } from "../../../core/text-truncation.js";
+import { REFLECT_TRUNCATION_MARKER } from "../../../integrations/agent/prompts.js";
 // ── Description / when_to_use shape ─────────────────────────────────────────
 export const HEADING_FRAGMENT_PATTERNS = [
     /^for example\b/i,
@@ -370,6 +371,34 @@ const reflectSizeGuardValidator = {
         ];
     },
 };
+/**
+ * Accept-time data-loss guard (#952 Addendum). `sanitizeReflectPayload`
+ * already defers a proposal whose body echoes {@link REFLECT_TRUNCATION_MARKER}
+ * (the notice appended when the source asset was too large to send in full)
+ * with `reflect-truncation-leak` — but that is a creation-time check, and a
+ * proposal can reach `proposal accept` / drain promotion without ever going
+ * through it (e.g. a defer that a human then accepts anyway, or a future
+ * reflect code path that mints proposals directly). A leaked marker replacing
+ * real asset content on disk is data loss, not a quality nit, so unlike the
+ * rest of this file's validators this one is NOT wrapped by {@link advisory}
+ * — it blocks acceptance the same way the generic/canonical validators do.
+ */
+const reflectTruncationMarkerValidator = {
+    name: "reflect-truncation-marker",
+    appliesTo(proposal) {
+        return proposal.source === "reflect" && typeof proposal.payload?.content === "string";
+    },
+    validate(proposal) {
+        if (!proposalContent(proposal).includes(REFLECT_TRUNCATION_MARKER))
+            return [];
+        return [
+            {
+                kind: "reflect-truncation-marker-leak",
+                message: `Proposal ${proposal.id} (${proposal.ref}) body still contains the reflect truncation marker "${REFLECT_TRUNCATION_MARKER}" — the source asset was too large to send in full and this body would overwrite it with an incomplete rewrite. Reflect this ref again (or raise its content budget) and re-propose.`,
+            },
+        ];
+    },
+};
 /**
  * Report a validator's findings as advisory.
  *
@@ -394,11 +423,17 @@ function advisory(validator) {
 /**
  * Full set of quality validators in registration order. Appended onto
  * {@link defaultProposalValidators} so they run inside `validateProposal` on
- * `proposal accept` automatically, and report without blocking.
+ * `proposal accept` automatically. All prose-quality checks report without
+ * blocking (see {@link advisory}); {@link reflectTruncationMarkerValidator} is
+ * the one exception and blocks, since it guards against data loss rather than
+ * prose quality.
  */
 export const defaultProposalQualityValidators = [
-    descriptionQualityValidator,
-    lessonContentQualityValidator,
-    sourceNotSupersededValidator,
-    reflectSizeGuardValidator,
-].map(advisory);
+    ...[
+        descriptionQualityValidator,
+        lessonContentQualityValidator,
+        sourceNotSupersededValidator,
+        reflectSizeGuardValidator,
+    ].map(advisory),
+    reflectTruncationMarkerValidator,
+];

package/dist/commands/proposal/validators/proposal-validators.js

@@ -123,6 +123,30 @@ export const defaultProposalValidators = [
     canonicalProposalValidator,
     ...defaultProposalQualityValidators,
 ];
+/**
+ * Structural-only subset used by {@link createProposal}'s mint-time
+ * canonical-structure gate (repository.ts, `hasCanonicalProposalValidator`).
+ * That gate exists to reject a lesson/task/workflow proposal whose body is
+ * not parseable as its type — it predates {@link defaultProposalQualityValidators}
+ * and was previously safe to run in full there because every quality
+ * validator was advisory (`advisory()` downgrades findings to `severity:
+ * "warn"`, which {@link runProposalValidators}'s `ok` never treats as
+ * failing). #952's `reflect-truncation-marker` validator is deliberately
+ * NOT advisory (it guards against data loss), so running the full
+ * {@link defaultProposalValidators} list at mint time would throw
+ * `invalid_canonical_structure` for any lesson/task/workflow reflect
+ * proposal whose body leaks the truncation marker — instead of letting
+ * `sanitizeReflectPayload` mint the proposal and defer it with
+ * `reflect-truncation-leak`, per the #952 design. Quality validators (prose
+ * shape, reflect size ratio, the truncation-marker guard) belong at
+ * `proposal accept` / drain-promotion time, which already calls
+ * {@link validateProposal} (the full list) via `preflightProposalPromotion`
+ * / `promoteProposalWithLease`.
+ */
+export const canonicalOnlyProposalValidators = [
+    genericProposalValidator,
+    canonicalProposalValidator,
+];
 export function runProposalValidators(proposal, validators = defaultProposalValidators, initialContext = {}) {
     const findings = [];
     const ctx = { ...initialContext };