akm-cli 0.9.0-beta.6 → 0.9.0-rc.0

package/dist/commands/improve/feedback-valence.js

@@ -0,0 +1,54 @@
+// 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/.
+/**
+ * Symmetric valence weighting for the improve eligibility sort (#614).
+ *
+ * BACKGROUND. The improve attention/eligibility ranking historically combined
+ * utility with a NEGATIVE-ONLY feedback term: `negative / (positive + negative)`.
+ * Under that formula a strong-positive asset contributes a feedback ratio of
+ * `0` — i.e. positive feedback never drives attention. Only complaints could
+ * lift an asset up the ranking, so a heavily-praised, heavily-used asset that
+ * deserves REINFORCEMENT (distill / promote the win) is treated identically to
+ * a never-rated one.
+ *
+ * FIX (gated, default-off). When symmetric valence is enabled we replace the
+ * negative-only ratio with a |valence| MAGNITUDE term so that BOTH strong
+ * positive and strong negative feedback drive attention. Utility remains the
+ * dominant ordering factor — valence is a secondary attention nudge with a
+ * small fixed weight, never a utility override.
+ *
+ * This module is intentionally pure and storage-free: it takes pre-aggregated
+ * positive/negative counts plus a utility lookup and returns a deterministic
+ * score and lane. All DB access stays in the caller.
+ */
+/** Weight on utility in the combined eligibility score. Utility is dominant. */
+export const UTILITY_WEIGHT = 0.7;
+/** Weight on the feedback attention term in the combined eligibility score. */
+export const FEEDBACK_WEIGHT = 0.3;
+/**
+ * Minimum |valence| magnitude for an item to be ROUTED to the fix / reinforce
+ * lane. Below this the feedback is too weak/mixed to be a confident signal and
+ * the item carries no attention lane (`null`). Pure magnitude in [0, 1].
+ */
+export const STRONG_VALENCE_THRESHOLD = 0.5;
+/**
+ * Compute the symmetric-valence attention score for one asset's feedback.
+ *
+ * Deterministic: depends only on the integer counts. No clock, no randomness.
+ */
+export function computeValenceScore(counts) {
+    const positive = Math.max(0, counts.positive);
+    const negative = Math.max(0, counts.negative);
+    const total = positive + negative;
+    if (total === 0) {
+        return { valence: 0, magnitude: 0, attention: 0, lane: null };
+    }
+    const valence = (positive - negative) / total;
+    const magnitude = Math.abs(valence);
+    let lane = null;
+    if (magnitude >= STRONG_VALENCE_THRESHOLD) {
+        lane = valence < 0 ? "fix" : "reinforce";
+    }
+    return { valence, magnitude, attention: magnitude, lane };
+}

package/dist/commands/improve/hot-probation.js

@@ -0,0 +1,45 @@
+// 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/.
+/**
+ * WS-3b Step 0c — Hot-probation intake buffer (#604).
+ *
+ * New system-generated extractions enter `captureMode: hot-probation` and spend
+ * ONE consolidation cycle in probation before promotion to the main stash;
+ * dedup + quality second-pass runs against them. Stops noisy extractions from
+ * polluting the stash at the source. Reuses shared dedupHash + body_embeddings.
+ * Default OFF.
+ *
+ * @module hot-probation
+ */
+/**
+ * captureMode value for system-generated extractions in probation.
+ * Automatic counterpart to the user-explicit `captureMode: hot`.
+ */
+export const CAPTURE_MODE_HOT_PROBATION = "hot-probation";
+/**
+ * Returns true when an asset is in hot-probation (system-generated, not yet
+ * graduated from the intake dedup+quality pass).
+ */
+export function isHotProbation(captureModeValue) {
+    return captureModeValue === CAPTURE_MODE_HOT_PROBATION;
+}
+/**
+ * Returns true when an asset should be skipped by the consolidation LLM
+ * because it's still in hot-probation (hasn't completed the intake pass yet).
+ *
+ * Hot-probation assets are processed by the consolidation dedup pre-pass
+ * (runDeterministicDedup) but excluded from the LLM merge clustering, so
+ * noisy extractions can't pollute the LLM context.
+ */
+export function shouldSkipHotProbationInLlm(frontmatterData) {
+    return isHotProbation(frontmatterData.captureMode);
+}
+/**
+ * Build frontmatter fields to inject when creating a hot-probation proposal.
+ * The proposal will carry `captureMode: hot-probation` so downstream logic
+ * knows to run the intake dedup pass before graduating it.
+ */
+export function buildHotProbationFrontmatter() {
+    return { captureMode: CAPTURE_MODE_HOT_PROBATION };
+}

package/dist/commands/improve/improve-auto-accept.js

@@ -2,9 +2,34 @@
 // 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 { loadConfig } from "../../core/config/config.js";
+import { UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
+import { withStateDb } from "../../core/state-db.js";
 import { info, warn } from "../../core/warn.js";
-import { promoteProposal, recordGateDecision } from "../proposal/validators/proposals.js";
+import { getPhaseThreshold } from "../../storage/repositories/improve-runs-repository.js";
+import { archiveProposal, getProposal, promoteProposal, recordGateDecision } from "../proposal/repository.js";
+async function sha256Hex(input) {
+    const data = new TextEncoder().encode(input);
+    const digest = await crypto.subtle.digest("SHA-256", data);
+    return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+/**
+ * Derive a stable, low-cardinality reason bucket from an auto-accept promotion
+ * error. `promoteProposal` throws a `validateProposal` report formatted as
+ * `[kind] message` lines; we extract the first finding kind. Non-validation
+ * throws collapse to `promote-error`.
+ */
+function classifyPromoteFailure(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    const finding = /\[([a-z][a-z0-9-]*)\]/i.exec(message);
+    if (finding)
+        return `validation:${finding[1]}`;
+    if (/not pending/i.test(message))
+        return "not-pending";
+    if (/unknown asset type/i.test(message))
+        return "unknown-type";
+    return "promote-error";
+}
 // ---------------------------------------------------------------------------
 // Gate implementation
 // ---------------------------------------------------------------------------
@@ -18,13 +43,32 @@ import { promoteProposal, recordGateDecision } from "../proposal/validators/prop
  * @param promoteFn   Injectable override for `promoteProposal` (test seam).
  */
 export async function runAutoAcceptGate(candidates, cfg, promoteFn = promoteProposal) {
-    const result = { promoted: [], skipped: [], failed: [] };
+    const result = {
+        promoted: [],
+        skipped: [],
+        failed: [],
+        suppressed: [],
+        failedByReason: {},
+        failedBySource: {},
+    };
     // --- Guard: gate is disabled or context is incomplete ---
     if (cfg.dryRun || cfg.globalThreshold === undefined || !cfg.stashDir) {
         result.skipped = candidates.map((c) => c.proposalId);
         return result;
     }
-    const effectiveThreshold = Math.max(cfg.globalThreshold, cfg.minimumThreshold ?? 0) / 100;
+    // WS-4: per-phase threshold from state.db overrides the global threshold.
+    // The per-phase value is populated by makeGateConfig when a stateDbPath is
+    // available; callers that don't pass it get the global threshold unchanged.
+    const resolvedThreshold = cfg.phaseThreshold ?? cfg.globalThreshold;
+    const effectiveThreshold = Math.max(resolvedThreshold, cfg.minimumThreshold ?? 0) / 100;
+    // WS-4: Exploration budget — promote at most N candidates regardless of
+    // confidence to prevent the gate converging to pure exploitation.
+    // Exploration candidates are chosen from the LOWEST-confidence eligible set
+    // (i.e. those that would be deferred) so the budget truly samples the low-
+    // confidence tail and is meaningfully distinct from normal auto-accept.
+    // Promoted exploration proposals are logged with eligibilitySource="exploration".
+    const explorationBudget = cfg.explorationBudgetCount ?? 0;
+    let explorationRemaining = explorationBudget;
     const resolvedConfig = typeof cfg.config === "function" ? cfg.config() : cfg.config;
     const gateLabel = `improve:${cfg.phase}`;
     // #577: stamp the gate's verdict onto each proposal so `akm proposal show`
@@ -40,7 +84,20 @@ export async function runAutoAcceptGate(candidates, cfg, promoteFn = promoteProp
     };
     for (const candidate of candidates) {
         const { proposalId, confidence } = candidate;
-        if (confidence === undefined || confidence < effectiveThreshold) {
+        let currentProposal;
+        try {
+            currentProposal = cfg.stashDir ? getProposal(cfg.stashDir, proposalId) : undefined;
+        }
+        catch {
+            currentProposal = undefined;
+        }
+        const currentContentHash = currentProposal ? await sha256Hex(currentProposal.payload.content) : undefined;
+        // Determine if this candidate is exploration-eligible: below-threshold
+        // (would normally be deferred) but with a valid confidence score and budget
+        // remaining. No-confidence candidates are never exploration-promoted.
+        const belowThreshold = confidence === undefined || confidence < effectiveThreshold;
+        const isExploration = belowThreshold && confidence !== undefined && explorationRemaining > 0;
+        if (belowThreshold && !isExploration) {
             stamp(proposalId, {
                 outcome: "deferred",
                 reason: confidence === undefined ? "no-confidence" : "below-threshold",
@@ -51,15 +108,32 @@ export async function runAutoAcceptGate(candidates, cfg, promoteFn = promoteProp
             result.skipped.push(proposalId);
             continue;
         }
+        // Either above-threshold (normal auto-accept) or exploration-budget promoted.
+        if (isExploration)
+            explorationRemaining -= 1;
+        const promoteReason = isExploration ? "exploration-budget" : "above-threshold";
+        if (currentProposal?.gateDecision?.outcome === "auto-rejected" &&
+            currentProposal.gateDecision.contentHash !== undefined &&
+            currentProposal.gateDecision.contentHash === currentContentHash) {
+            result.suppressed.push(proposalId);
+            continue;
+        }
         try {
             const promotion = await promoteFn(cfg.stashDir, resolvedConfig, proposalId, {}, undefined);
             stamp(promotion.proposal.id, {
                 outcome: "auto-accepted",
-                reason: "above-threshold",
+                reason: promoteReason,
                 confidence,
                 thresholds: { autoAccept: effectiveThreshold },
+                ...(currentContentHash !== undefined ? { contentHash: currentContentHash } : {}),
                 gate: gateLabel,
             });
+            // Resolve the eligibilitySource: exploration-promoted proposals get
+            // eligibilitySource="exploration" (WS-4); normal auto-accepts carry
+            // whatever the proposal was tagged with at selection time.
+            const resolvedEligibilitySource = isExploration
+                ? "exploration"
+                : promotion.proposal.eligibilitySource;
             appendEvent({
                 eventType: "promoted",
                 ref: promotion.ref,
@@ -72,14 +146,62 @@ export async function runAutoAcceptGate(candidates, cfg, promoteFn = promoteProp
                     confidence,
                     threshold: effectiveThreshold,
                     phase: cfg.phase,
+                    // Attribution tagging: carry the eligibility lane from the proposal
+                    // record onto the auto-accept promoted event so the lane survives to
+                    // accept time even when promotion happens in a later run.
+                    ...(resolvedEligibilitySource !== undefined ? { eligibilitySource: resolvedEligibilitySource } : {}),
+                    // WS-4: mark exploration promotions so health/telemetry can
+                    // distinguish them from calibration-signal promotions.
+                    ...(isExploration ? { explorationBudget: true } : {}),
                 },
             }, cfg.eventsCtx ?? {});
-            info(`[improve] auto-accepted ${promotion.ref} (${cfg.phase}; confidence=${confidence.toFixed(2)} >= threshold=${effectiveThreshold.toFixed(2)})`);
+            if (isExploration) {
+                info(`[improve] exploration-accepted ${promotion.ref} (${cfg.phase}; confidence=${confidence.toFixed(2)}; budgetRemaining=${explorationRemaining})`);
+            }
+            else {
+                info(`[improve] auto-accepted ${promotion.ref} (${cfg.phase}; confidence=${confidence.toFixed(2)} >= threshold=${effectiveThreshold.toFixed(2)})`);
+            }
             result.promoted.push(proposalId);
         }
         catch (err) {
-            warn(`[improve] ${cfg.phase} auto-accept failed for ${proposalId}: ${err instanceof Error ? err.message : String(err)}`);
+            const reason = classifyPromoteFailure(err);
+            warn(`[improve] ${cfg.phase} auto-accept failed for ${proposalId} (${reason}): ${err instanceof Error ? err.message : String(err)}`);
             result.failed.push(proposalId);
+            result.failedByReason[reason] = (result.failedByReason[reason] ?? 0) + 1;
+            // Record WHY on the proposal so `akm proposal show` explains the rejection
+            // and the leak is no longer blind. Best-effort.
+            stamp(proposalId, {
+                outcome: "auto-rejected",
+                reason,
+                confidence,
+                thresholds: { autoAccept: effectiveThreshold },
+                ...(currentContentHash !== undefined ? { contentHash: currentContentHash } : {}),
+                gate: gateLabel,
+            });
+            // A validation failure is permanent — the minted content can never satisfy
+            // the asset schema, so archive it as rejected instead of leaving it pending
+            // to be retried on every future run (the 90-day TTL is otherwise the first
+            // thing ever to touch these zombies). Best-effort; ctx=undefined mirrors the
+            // promoteFn call above so the archive hits the same stashDir-derived DB.
+            //
+            // Discriminate on the STRUCTURED error, not the `reason` string: promoteProposal
+            // throws UsageError("MISSING_REQUIRED_ARGUMENT") only for the validateProposal
+            // failure branch. Message-sniffing (`reason` = "validation:<kind>") would also
+            // match a transient git-push rejection ("[rejected] ... non-fast-forward") from
+            // a git-backed write target and permanently archive a valid, retryable proposal.
+            const isPermanentValidationFailure = err instanceof UsageError && err.code === "MISSING_REQUIRED_ARGUMENT";
+            if (isPermanentValidationFailure) {
+                try {
+                    archiveProposal(cfg.stashDir, proposalId, "rejected", `auto-accept ${reason}`, undefined);
+                }
+                catch (archiveErr) {
+                    warn(`[improve] ${cfg.phase} failed to archive validation-failed proposal ${proposalId}: ${archiveErr instanceof Error ? archiveErr.message : String(archiveErr)}`);
+                }
+            }
+            // If exploration budget was consumed but promotion failed, restore the slot
+            // so the budget isn't exhausted on errors.
+            if (isExploration)
+                explorationRemaining += 1;
         }
     }
     return result;
@@ -108,15 +230,46 @@ export function resolveExtractConfidence(proposal) {
 /**
  * Build a gate config for a phase, inheriting global settings from the
  * improve options. Callers supply only the phase-specific overrides.
+ *
+ * WS-4 additions:
+ * - When `shared.stateDbPath` is provided, reads the persisted per-phase
+ *   threshold from `improve_gate_thresholds` (Migration 012). The phase
+ *   value overrides `globalThreshold` but is still floored by
+ *   `minimumThreshold`. Falls back to `globalThreshold` when no row exists.
+ * - Computes `explorationBudgetCount` from
+ *   `config.improve.exploration.budgetFraction × candidateCount` when the
+ *   exploration budget is enabled. Defaults to 0 (no exploration).
  */
 export function makeGateConfig(phase, shared, overrides = {}) {
+    // WS-4: read per-phase threshold from state.db when available.
+    let phaseThreshold;
+    if (shared.stateDbPath && shared.globalThreshold !== undefined) {
+        try {
+            phaseThreshold = withStateDb((db) => getPhaseThreshold(db, phase) ?? undefined, {
+                path: shared.stateDbPath,
+            });
+        }
+        catch {
+            // DB unavailable — fall back to globalThreshold silently.
+        }
+    }
+    // WS-4: compute exploration budget count from config fraction × candidateCount.
+    let explorationBudgetCount;
+    const resolvedConfig = typeof shared.config === "function" ? shared.config() : shared.config;
+    const explorationCfg = resolvedConfig.improve?.exploration;
+    if (explorationCfg?.enabled && shared.candidateCount !== undefined && shared.candidateCount > 0) {
+        const fraction = Math.min(1, Math.max(0, explorationCfg.budgetFraction ?? 0.05));
+        explorationBudgetCount = Math.max(0, Math.floor(fraction * shared.candidateCount));
+    }
     return {
         phase,
         globalThreshold: shared.globalThreshold,
+        ...(phaseThreshold !== undefined ? { phaseThreshold } : {}),
         dryRun: shared.dryRun,
         stashDir: shared.stashDir,
         config: shared.config,
         eventsCtx: shared.eventsCtx,
+        ...(explorationBudgetCount !== undefined && explorationBudgetCount > 0 ? { explorationBudgetCount } : {}),
         ...overrides,
     };
 }

package/dist/commands/improve/improve-cli.js

@@ -8,15 +8,71 @@ import { output, runWithJsonErrors } from "../../cli/shared.js";
 import { loadConfig } from "../../core/config/config.js";
 import { UsageError } from "../../core/errors.js";
 import { getCacheDir } from "../../core/paths.js";
+import { withStateDb } from "../../core/state-db.js";
 import { clearLogFile, setLogFile } from "../../core/warn.js";
+import { closeDatabase, openExistingDatabase } from "../../indexer/db/db.js";
 import { resolveSourceEntries } from "../../indexer/search/search-source.js";
-import { getHyphenatedArg, getHyphenatedBoolean, parseFlagValue } from "../../output/context.js";
+import { parseFlagValue } from "../../output/context.js";
+import { getActiveCanaries, queryRecentCycleMetrics } from "../../storage/repositories/canaries-repository.js";
+import { refreshCanarySet } from "./collapse-detector.js";
 import { akmImprove } from "./improve.js";
 import { buildImproveRunId, recordTerminatedImproveRun, relativeImproveResultPath, writeImproveResultFile, } from "./improve-result-file.js";
+import { runImproveSession } from "./improve-session.js";
+// R5 — collapse-detector canary set inspection / explicit refresh. The
+// detector NEVER auto-refreshes the canary set (silent re-baselining is how a
+// slow collapse hides); this verb is the only refresh path.
+//
+// Dispatched from the parent improve run() on `scope === "canary"` — NOT a
+// citty subCommand: registering subCommands makes citty treat EVERY first
+// positional as a subcommand name, breaking `akm improve <type|ref>` outright
+// (citty throws "Unknown command memory"), and citty also re-runs the parent
+// run() after a matched subcommand.
+async function runCanaryInspection(refresh) {
+    const config = loadConfig();
+    const cfg = config.improve?.collapseDetector ?? {};
+    const result = withStateDb((stateDb) => {
+        let refreshOutcome;
+        if (refresh) {
+            const indexDb = openExistingDatabase();
+            try {
+                // Mint-first, deactivate-after (refreshCanarySet): an empty/unreadable
+                // index keeps the old baseline instead of destroying it.
+                refreshOutcome = refreshCanarySet(stateDb, indexDb, cfg) === null ? "kept-old-set" : "refreshed";
+            }
+            finally {
+                closeDatabase(indexDb);
+            }
+        }
+        const canaries = getActiveCanaries(stateDb);
+        const canarySetId = canaries[0]?.canary_set_id;
+        const recentCycles = canarySetId ? queryRecentCycleMetrics(stateDb, canarySetId, cfg.windowCycles ?? 5) : [];
+        return {
+            schemaVersion: 1,
+            ok: true,
+            refreshed: refreshOutcome === "refreshed",
+            ...(refreshOutcome === "kept-old-set"
+                ? { warning: "refresh skipped: no mintable learning entries in the index — existing canary set kept" }
+                : {}),
+            canarySetId: canarySetId ?? null,
+            canaries: canaries.map((c) => ({ id: c.id, anchorRef: c.anchor_ref, query: c.query })),
+            recentCycles: recentCycles.map((r) => ({
+                ts: r.ts,
+                pass: r.pass,
+                meanRecall: r.mean_recall,
+                meanNdcg: r.mean_ndcg,
+                distinctContentRatio: r.distinct_content_ratio,
+                acceptedActions: r.accepted_actions,
+                mergeFloorViolations: r.merge_floor_violations,
+                alerts: JSON.parse(r.alerts_json),
+            })),
+        };
+    });
+    output("improve-canary", result);
+}
 export const improveCommand = defineCommand({
     meta: {
         name: "improve",
-        description: "Analyze existing AKM assets and generate improvement proposals; also consolidates memories when profiles.improve.default.processes.consolidate.enabled is true",
+        description: "Analyze existing AKM assets and generate improvement proposals; also consolidates memories when profiles.improve.default.processes.consolidate.enabled is true. `akm improve canary [--refresh]` inspects the collapse-detector canary set.",
     },
     args: {
         scope: {
@@ -25,6 +81,11 @@ export const improveCommand = defineCommand({
             required: false,
         },
         task: { type: "string", description: "Add extra guidance for this improvement pass" },
+        refresh: {
+            type: "boolean",
+            description: "(canary scope only) Mint a new collapse-detector canary set and deactivate the old one; old rows and their cycle history are retained",
+            default: false,
+        },
         "dry-run": { type: "boolean", description: "Show planned actions without writing", default: false },
         target: { type: "string", description: "Override the write target for accepted proposals" },
         "auto-accept": {
@@ -73,37 +134,44 @@ export const improveCommand = defineCommand({
         },
     },
     async run({ args }) {
+        // "canary" is a reserved scope word (never a valid asset type, and refs
+        // contain ":"): dispatch to the detector inspection verb instead of an
+        // improve run.
+        if (args.scope === "canary") {
+            await runWithJsonErrors(() => runCanaryInspection(args.refresh));
+            return;
+        }
         await runWithJsonErrors(async () => {
             const formatFlagValue = parseFlagValue(process.argv, "--format");
             if (formatFlagValue !== undefined) {
                 throw new UsageError(`akm improve does not accept --format. That flag controls output formatting for other commands (search, show, etc.).\n` +
                     `Did you mean: akm improve (no --format flag)?`, "INVALID_FLAG_VALUE");
             }
-            const jsonToStdout = getHyphenatedBoolean(args, "json-to-stdout");
-            const autoAcceptRaw = getHyphenatedArg(args, "auto-accept");
+            const jsonToStdout = args["json-to-stdout"];
+            const autoAcceptRaw = args["auto-accept"];
             const autoAccept = parseAutoAcceptFlag(autoAcceptRaw);
             const targetArg = getStringArg(args, "target");
             const taskArg = getStringArg(args, "task");
-            const dryRun = getHyphenatedBoolean(args, "dry-run");
+            const dryRun = args["dry-run"];
             const limitRaw = parsePositiveIntFlag(args.limit ?? undefined);
-            const timeoutMs = parsePositiveIntFlag(getHyphenatedArg(args, "timeout-ms"), "--timeout-ms");
-            const consolidateRecoveryRaw = getHyphenatedArg(args, "consolidate-recovery");
+            const timeoutMs = parsePositiveIntFlag(args["timeout-ms"], "--timeout-ms");
+            const consolidateRecoveryRaw = args["consolidate-recovery"];
             const consolidateRecovery = consolidateRecoveryRaw === undefined
                 ? undefined
                 : consolidateRecoveryRaw.trim().toLowerCase();
             if (consolidateRecovery !== undefined && consolidateRecovery !== "abort" && consolidateRecovery !== "clean") {
                 throw new UsageError(`Invalid --consolidate-recovery value: "${consolidateRecoveryRaw}". Must be one of: abort, clean.`, "INVALID_FLAG_VALUE");
             }
-            const minRetrievalCountRaw = getHyphenatedArg(args, "min-retrieval-count");
+            const minRetrievalCountRaw = args["min-retrieval-count"];
             const minRetrievalCount = parseNonNegativeIntFlag(minRetrievalCountRaw, "--min-retrieval-count");
-            const requireFeedbackSignal = getHyphenatedBoolean(args, "require-feedback-signal");
-            const skipIfLocked = getHyphenatedBoolean(args, "skip-if-locked");
+            const requireFeedbackSignal = args["require-feedback-signal"];
+            const skipIfLocked = args["skip-if-locked"];
             const profileArg = getStringArg(args, "profile");
             // Only set the keys the user actually passed (citty leaves the flag
             // undefined unless `--sync`/`--no-sync` / `--push`/`--no-push` appears),
             // so the resolved profile `sync` block wins by default.
-            const syncFlag = getHyphenatedArg(args, "sync");
-            const pushFlag = getHyphenatedArg(args, "push");
+            const syncFlag = args.sync;
+            const pushFlag = args.push;
             const syncOverride = {};
             if (syncFlag !== undefined)
                 syncOverride.enabled = syncFlag;
@@ -144,67 +212,44 @@ export const improveCommand = defineCommand({
                     process.stderr.write(`warning: failed to persist terminated improve run ${runId}: ${err instanceof Error ? err.message : String(err)}\n`);
                 }
             };
-            // M5 (code-health round 2): signal -> {exit code, reason, ack message}
-            // as an explicit table instead of three near-identical handlers. The
-            // persist of the terminated-run row MUST complete before process.exit so
-            // a SIGTERM'd run (e.g. cron timeout) always leaves a row in
-            // improve_runs. recordTerminatedImproveRun is fully synchronous
-            // (bun:sqlite writes are sync), so the in-line call below blocks until
-            // the row is flushed before we exit.
-            const SIGNAL_TABLE = {
-                SIGTERM: { code: 143, reason: "SIGTERM", ack: true },
-                SIGINT: { code: 130, reason: "SIGINT", ack: true },
-                SIGHUP: { code: 129, reason: "SIGHUP", ack: false },
-            };
-            const makeSignalHandler = (sig) => () => {
-                const { code, reason, ack } = SIGNAL_TABLE[sig];
-                // Hard-exit fallback: if the synchronous persist ever hangs (e.g. a
-                // stuck sqlite lock under contention), the watchdog still exits with
-                // the correct code instead of leaving a zombie process. .unref() keeps
-                // the timer from holding the loop open on the normal (fast) path.
-                const watchdog = setTimeout(() => process.exit(code), 2000);
-                if (typeof watchdog.unref === "function")
-                    watchdog.unref();
-                try {
-                    persistTerminated(reason);
-                }
-                finally {
-                    clearTimeout(watchdog);
-                }
-                if (ack) {
-                    process.stderr.write(`[improve] received ${sig}; recorded terminated run ${runId}\n`);
-                }
-                process.exit(code);
-            };
-            const sigtermHandler = makeSignalHandler("SIGTERM");
-            const sigintHandler = makeSignalHandler("SIGINT");
-            const sighupHandler = makeSignalHandler("SIGHUP");
-            process.once("SIGTERM", sigtermHandler);
-            process.once("SIGINT", sigintHandler);
-            process.once("SIGHUP", sighupHandler);
+            // R8: the signal table / handlers / watchdog / persist-before-exit
+            // choreography lives in `runImproveSession`. It registers the
+            // SIGTERM/SIGINT/SIGHUP handlers (each persists the terminated-run row
+            // BEFORE process.exit so a SIGTERM'd run — e.g. cron timeout — always
+            // leaves a row in improve_runs), awaits the work, then removes the
+            // handlers on the way out. `onTerminate` persists synchronously
+            // (recordTerminatedImproveRun -> bun:sqlite writes are sync), and the
+            // 2000ms watchdog inside the session force-exits if that ever hangs.
             let improveResult;
             try {
-                improveResult = await akmImprove({
-                    scope: scopeArg,
-                    task: taskArg,
-                    dryRun,
-                    target: targetArg,
-                    autoAccept,
-                    ...(runId !== undefined ? { runId } : {}),
-                    ...(limitRaw !== undefined ? { limit: limitRaw } : {}),
-                    ...(timeoutMs !== undefined ? { timeoutMs } : {}),
-                    ...(minRetrievalCount !== undefined ? { minRetrievalCount } : {}),
-                    ...(requireFeedbackSignal ? { requireFeedbackSignal } : {}),
-                    ...(skipIfLocked ? { skipIfLocked } : {}),
-                    ...(profileArg !== undefined ? { profile: profileArg } : {}),
-                    ...(Object.keys(syncOverride).length > 0 ? { sync: syncOverride } : {}),
-                    consolidateOptions: {
-                        target: targetArg,
+                improveResult = await runImproveSession({
+                    runWork: () => akmImprove({
+                        scope: scopeArg,
+                        task: taskArg,
                         dryRun,
+                        target: targetArg,
                         autoAccept,
-                        task: taskArg,
-                        ...(consolidateRecovery !== undefined ? { recoveryMode: consolidateRecovery } : {}),
-                    },
+                        ...(runId !== undefined ? { runId } : {}),
+                        ...(limitRaw !== undefined ? { limit: limitRaw } : {}),
+                        ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+                        ...(minRetrievalCount !== undefined ? { minRetrievalCount } : {}),
+                        ...(requireFeedbackSignal ? { requireFeedbackSignal } : {}),
+                        ...(skipIfLocked ? { skipIfLocked } : {}),
+                        ...(profileArg !== undefined ? { profile: profileArg } : {}),
+                        ...(Object.keys(syncOverride).length > 0 ? { sync: syncOverride } : {}),
+                        consolidateOptions: {
+                            target: targetArg,
+                            dryRun,
+                            autoAccept,
+                            task: taskArg,
+                            ...(consolidateRecovery !== undefined ? { recoveryMode: consolidateRecovery } : {}),
+                        },
+                    }),
+                }, {
+                    signalSource: process,
+                    exit: process.exit,
+                    onTerminate: (reason) => persistTerminated(reason),
+                    ack: (message) => process.stderr.write(`[improve] ${message}; recorded terminated run ${runId}\n`),
                 });
             }
             catch (err) {
@@ -216,9 +261,6 @@ export const improveCommand = defineCommand({
                 throw err;
             }
             finally {
-                process.removeListener("SIGTERM", sigtermHandler);
-                process.removeListener("SIGINT", sigintHandler);
-                process.removeListener("SIGHUP", sighupHandler);
                 clearLogFile();
             }
             const durationMs = Date.now() - startedAtMs;
@@ -246,7 +288,7 @@ export const improveCommand = defineCommand({
             runRecorded = true; // Suppress any late signal-handler write — the success path owns the row now.
             if (primaryStashDir) {
                 try {
-                    writeImproveResultFile(primaryStashDir, runId, improveResult, startedAtIso);
+                    writeImproveResultFile(primaryStashDir, runId, improveResult, startedAtIso, profileArg ?? null);
                 }
                 catch (err) {
                     // Stderr warning on the failure path is preferable to crashing