akm-cli 0.9.0-beta.11 → 0.9.0-beta.26

package/dist/commands/improve/extract-watch.js

@@ -0,0 +1,140 @@
+// 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 { akmExtract } from "./extract.js";
+const DEFAULT_DEBOUNCE_MS = 2000;
+/** Small look-back window for the default trigger's `akmExtract` call. */
+const DEFAULT_TRIGGER_SINCE = "10m";
+/**
+ * Does `filePath` look like a real session file under one of the configured
+ * roots? True only when the path is under a root AND matches that harness's
+ * on-disk session-file shape:
+ *   - claude-code: `<root>/<project>/<id>.jsonl`
+ *   - opencode:    `<root>/<project>/<id>.json`
+ * Anything out-of-root, or in-root with the wrong extension, returns false.
+ */
+export function isSessionFile(filePath, roots) {
+    return matchHarness(filePath, roots) !== undefined;
+}
+/** Normalize a path for prefix comparison (ensure a trailing separator). */
+function withSep(dir) {
+    return dir.endsWith("/") ? dir : `${dir}/`;
+}
+/**
+ * Resolve which harness a path belongs to by longest-prefix match against the
+ * configured roots, then validate the file shape for that harness. Returns the
+ * harness name, or `undefined` when the path is out-of-root or not a session
+ * file. Longest-prefix match guards against the (in practice impossible) case
+ * of nested roots.
+ */
+export function matchHarness(filePath, roots) {
+    let best;
+    let bestLen = -1;
+    for (const target of roots) {
+        for (const root of target.roots) {
+            const prefix = withSep(root);
+            if (filePath.startsWith(prefix) && prefix.length > bestLen) {
+                best = { harnessName: target.harnessName };
+                bestLen = prefix.length;
+            }
+        }
+    }
+    if (!best)
+        return undefined;
+    // Validate the file shape for the resolved harness.
+    if (best.harnessName === "claude-code") {
+        return filePath.endsWith(".jsonl") ? best.harnessName : undefined;
+    }
+    if (best.harnessName === "opencode") {
+        return filePath.endsWith(".json") ? best.harnessName : undefined;
+    }
+    // Unknown harness: accept any file under its root.
+    return best.harnessName;
+}
+/**
+ * Start the watch-mode core. Returns a handle whose `stop()` tears everything
+ * down. The event source is injected, so this never touches the real
+ * filesystem itself.
+ */
+export function akmExtractWatch(options) {
+    const { roots, eventSource, debounceMs = DEFAULT_DEBOUNCE_MS, setTimeoutFn = setTimeout, clearTimeoutFn = clearTimeout, isSessionFile: isSessionFileFn = isSessionFile, } = options;
+    const onTrigger = options.onTrigger ??
+        (async (harnessName) => {
+            await akmExtract({ type: harnessName, since: DEFAULT_TRIGGER_SINCE, force: false });
+        });
+    let stopped = false;
+    // Pending debounce timers, keyed by harness name.
+    const pendingTimers = new Map();
+    // Harnesses with an in-flight trigger, and whether a re-run is queued.
+    const inFlight = new Set();
+    const rerunPending = new Set();
+    function runTrigger(harnessName) {
+        if (stopped)
+            return;
+        if (inFlight.has(harnessName)) {
+            // A trigger is already running for this harness; coalesce into a single
+            // re-run after it resolves rather than launching a concurrent extract.
+            rerunPending.add(harnessName);
+            return;
+        }
+        inFlight.add(harnessName);
+        // Invoke synchronously so a synchronous `onTrigger` observes its effect
+        // before control returns (tests advance the clock then assert inline).
+        // Wrap the (possibly async) result in a promise to drive the in-flight
+        // guard's release without forcing the trigger itself into a microtask.
+        let result;
+        try {
+            result = onTrigger(harnessName);
+        }
+        catch (err) {
+            // One failed extract must never kill the watcher (mirrors the non-fatal
+            // handling in collectSessionEvents).
+            console.error(`[akm] extract --watch trigger for "${harnessName}" failed:`, err);
+            inFlight.delete(harnessName);
+            if (rerunPending.delete(harnessName) && !stopped)
+                runTrigger(harnessName);
+            return;
+        }
+        Promise.resolve(result)
+            .catch((err) => {
+            console.error(`[akm] extract --watch trigger for "${harnessName}" failed:`, err);
+        })
+            .finally(() => {
+            inFlight.delete(harnessName);
+            if (rerunPending.delete(harnessName) && !stopped) {
+                runTrigger(harnessName);
+            }
+        });
+    }
+    function onEvent(e) {
+        if (stopped)
+            return;
+        if (!isSessionFileFn(e.path, roots))
+            return;
+        const harnessName = matchHarness(e.path, roots);
+        if (!harnessName)
+            return;
+        const existing = pendingTimers.get(harnessName);
+        if (existing !== undefined)
+            clearTimeoutFn(existing);
+        const timer = setTimeoutFn(() => {
+            pendingTimers.delete(harnessName);
+            if (!stopped)
+                runTrigger(harnessName);
+        }, debounceMs);
+        pendingTimers.set(harnessName, timer);
+    }
+    const unsubscribe = eventSource.subscribe(onEvent);
+    return {
+        stop() {
+            if (stopped)
+                return;
+            stopped = true;
+            unsubscribe();
+            for (const timer of pendingTimers.values())
+                clearTimeoutFn(timer);
+            pendingTimers.clear();
+            rerunPending.clear();
+        },
+    };
+}

package/dist/commands/improve/extract.js

@@ -36,11 +36,15 @@ import { normalizeHarnessId } from "../../integrations/harnesses/index.js";
 import { getAvailableHarnesses } from "../../integrations/session-logs/index.js";
 import { preFilterSession } from "../../integrations/session-logs/pre-filter.js";
 import { chatCompletion } from "../../llm/client.js";
+import { embed } from "../../llm/embedder.js";
 import { isLlmFeatureEnabled, tryLlmFeature } from "../../llm/feature-gate.js";
+import { sha256Hex } from "../../runtime.js";
 import { createProposal, isProposalSkipped } from "../proposal/validators/proposals.js";
 import { buildExtractPrompt, EXTRACT_JSON_SCHEMA, parseExtractPayload } from "./extract-prompt.js";
+import { applySchemaSimilarityPenalty, buildHotProbationFrontmatter, loadDerivedLayerEmbeddings, } from "./homeostatic.js";
 import { resolveProcessEnabled } from "./improve-profiles.js";
 import { buildSessionSummaryPrompt, parseSessionSummary, SESSION_SUMMARY_JSON_SCHEMA, sessionMeetsDurationGate, writeSessionAsset, } from "./session-asset.js";
+import { resolveTriageConfig, scoreSessionTriage } from "./triage.js";
 /** Default minimum session duration (minutes) for session indexing (#561). */
 const DEFAULT_MIN_SESSION_DURATION_MINUTES = 5;
 /**
@@ -121,9 +125,43 @@ function buildCandidateProposal(candidate, sourceRef) {
     if (candidate.type === "lesson" && candidate.when_to_use) {
         fm.when_to_use = candidate.when_to_use;
     }
+    // #615 WS-0: preserve ordered-action + outcome data in frontmatter so the data
+    // survives even if source transcripts are not re-extractable later. The
+    // procedural-compilation feature (detection/compilation) is deferred to 0.10+.
+    if (candidate.orderedActions && candidate.orderedActions.length > 0) {
+        fm.orderedActions = candidate.orderedActions;
+        if (candidate.outcomeData) {
+            fm.outcomeData = candidate.outcomeData;
+        }
+    }
     const content = assembleAsset(fm, candidate.body);
     return { ref, content, description };
 }
+/**
+ * Canonicalize a session's content into a single deterministic string for
+ * hashing (#602). Each event is rendered `<role>\n<text>` and events are joined
+ * with a NUL-delimited separator (`\n\0\n`) so event boundaries cannot be forged
+ * by text that itself contains newlines.
+ *
+ * The input is the RAW `data.events` stream — NOT the pre-filtered / truncated
+ * set — so the hash is stable across `maxTotalChars` (and any other pre-filter)
+ * config changes: changing config must NEVER change the hash (idempotency AC).
+ * `inlineRefs` and ref metadata (title, startedAt/endedAt timestamps) are
+ * deliberately EXCLUDED so clock/title churn (and an agent adding an inline
+ * `akm remember` mid-session) does not change the hash.
+ */
+function canonicalizeSessionContent(data) {
+    return data.events.map((e) => `${e.role ?? "unknown"}\n${e.text}`).join("\n\0\n");
+}
+/**
+ * sha256 (hex) of the normalized session content (#602). This is the byte-exact,
+ * clock-independent skip authority that replaced the old `session_ended_at`
+ * timestamp comparison. See {@link canonicalizeSessionContent} for exactly what
+ * is (and is not) hashed.
+ */
+export function hashSessionContent(data) {
+    return sha256Hex(canonicalizeSessionContent(data));
+}
 /**
  * Process one session through the full pipeline: read → pre-filter → LLM →
  * parse → createProposal-per-candidate. Returns the per-session result.
@@ -132,7 +170,16 @@ function buildCandidateProposal(candidate, sourceRef) {
  * proposal validation failure) the session result records a warning and
  * keeps going — one session's bad luck never aborts a multi-session run.
  */
-async function processSession(harness, sessionRef, stashDir, config, llmConfig, chat, ctx, sourceRun, dryRun, timeoutMs, maxTotalChars, minContentChars, sessionIndexing) {
+async function processSession(harness, sessionRef, stashDir, config, llmConfig, chat, ctx, sourceRun, dryRun, timeoutMs, maxTotalChars, minContentChars, 
+// #626 — pre-LLM heuristic triage gate. Default-off (enabled:false) takes the
+// exact pre-change path (no scorer call, no new skipReason).
+triage, sessionIndexing, schemaSimilarityCtx, 
+// #602 — already-extracted skip moved INSIDE processSession: the content hash
+// can only be computed after readSession, so the skip decision lives here. The
+// prior row + bypass flags are threaded in from the caller. Skipping here still
+// costs ZERO LLM calls (the expensive resource #602 protects); only the cheap
+// file read is incurred.
+prior, force, singleSession) {
     const warnings = [];
     let data;
     try {
@@ -150,6 +197,25 @@ async function processSession(harness, sessionRef, stashDir, config, llmConfig,
             skipReason: "read_failed",
         };
     }
+    // #602 — content-hash skip. Computed on the RAW event stream immediately after
+    // a successful read, BEFORE the pre-filter / minContentChars / triage gates, so
+    // an unchanged session never reaches the LLM. Hash-based ⇒ clock-independent
+    // (immune to the Jun 11-12 timestamp double-extract/over-throttle bug). --force
+    // and single-session (explicit sessionId) modes bypass the skip entirely.
+    const contentHash = hashSessionContent(data);
+    if (!force && !singleSession && shouldSkipAlreadyExtractedSession(prior, contentHash)) {
+        return {
+            sessionId: sessionRef.sessionId,
+            harness: harness.name,
+            candidateCount: 0,
+            proposalIds: [],
+            preFilter: { inputCount: 0, outputCount: 0, truncatedCount: 0 },
+            warnings: [`already extracted (content unchanged) at ${prior?.processed_at}; pass --force to re-process`],
+            skipped: true,
+            skipReason: "already_extracted",
+            contentHash,
+        };
+    }
     const filtered = preFilterSession(data, {
         ...(typeof maxTotalChars === "number" ? { maxTotalChars } : {}),
     });
@@ -176,8 +242,34 @@ async function processSession(harness, sessionRef, stashDir, config, llmConfig,
             warnings: [],
             skipped: true,
             skipReason: "too_short",
+            contentHash,
         };
     }
+    // #626 — pre-LLM heuristic triage gate. Runs AFTER minContentChars + the
+    // already-extracted skip check (both in the caller / above), BEFORE the
+    // extraction prompt and the session-asset write. When the session scores below
+    // the configured threshold we triage it out: no chat() call, no session asset,
+    // no proposals. Pure-heuristic — zero added LLM cost. Default-off → skipped.
+    if (triage.enabled) {
+        const t = scoreSessionTriage(data, triage.minScore);
+        if (!t.pass) {
+            return {
+                sessionId: sessionRef.sessionId,
+                harness: harness.name,
+                candidateCount: 0,
+                proposalIds: [],
+                preFilter: {
+                    inputCount: filtered.stats.inputCount,
+                    outputCount: filtered.stats.outputCount,
+                    truncatedCount: filtered.stats.truncatedCount,
+                },
+                warnings: [],
+                skipped: true,
+                skipReason: "triaged_out",
+                contentHash,
+            };
+        }
+    }
     const prompt = buildExtractPrompt({ data, events: filtered.events, inlineRefs: data.inlineRefs });
     // #561 — ADDITIVE session indexing. Generate + write the session asset
     // (`sessions/<harness>/<id>.md`). FAIL-OPEN: any failure only records a
@@ -226,6 +318,7 @@ async function processSession(harness, sessionRef, stashDir, config, llmConfig,
             warnings: ["session_extraction feature returned empty (disabled / timeout / error)"],
             skipped: true,
             skipReason: "llm_unavailable",
+            contentHash,
         };
     }
     const payload = parseExtractPayload(llmRaw);
@@ -257,15 +350,34 @@ async function processSession(harness, sessionRef, stashDir, config, llmConfig,
                 truncatedCount: filtered.stats.truncatedCount,
             },
             warnings,
+            contentHash,
             ...sessionAsset,
         };
     }
+    // WS-3b step 0c: hot-probation intake buffer (#604).
+    // When enabled, system-generated extractions enter captureMode: hot-probation
+    // so they spend ONE consolidation cycle in probation before the deterministic
+    // dedup+quality pass promotes them. Default OFF.
+    const hotProbationEnabled = config.profiles?.improve?.default?.processes?.extract?.hotProbation
+        ?.enabled === true;
     for (const candidate of payload.candidates) {
         if (dryRun) {
             proposalIds.push(`dry-run:${candidate.type}:${candidate.name}`);
             continue;
         }
         try {
+            // WS-3b Step-0b: schema-similarity intake gate. When enabled and the
+            // candidate is a lesson/knowledge whose body embedding is within ε of an
+            // existing derived-layer node, down-prioritize by multiplying confidence by
+            // the penalty. PARITY: schemaSimilarityCtx is null when the flag is off →
+            // applySchemaSimilarityPenalty returns the original confidence untouched and
+            // never embeds. (Logic lives in homeostatic.ts so it is unit-testable.)
+            const gateResult = await applySchemaSimilarityPenalty(candidate, schemaSimilarityCtx, (text) => schemaSimilarityCtx?.embedFn
+                ? schemaSimilarityCtx.embedFn(text)
+                : embed(text, schemaSimilarityCtx?.embeddingConfig));
+            const effectiveConfidence = gateResult.effectiveConfidence;
+            if (gateResult.warning)
+                warn(gateResult.warning);
             const { ref, content, description } = buildCandidateProposal(candidate, sessionRef);
             const result = createProposal(stashDir, {
                 ref,
@@ -276,9 +388,22 @@ async function processSession(harness, sessionRef, stashDir, config, llmConfig,
                     frontmatter: {
                         description,
                         ...(candidate.when_to_use ? { when_to_use: candidate.when_to_use } : {}),
-                        ...(typeof candidate.confidence === "number" ? { confidence: candidate.confidence } : {}),
+                        ...(effectiveConfidence !== undefined ? { confidence: effectiveConfidence } : {}),
                         sources: [`session:${sessionRef.harness}:${sessionRef.sessionId}`],
                         evidence: candidate.evidence,
+                        // #615 WS-0: mirror ordered-action + outcome data in the proposal
+                        // frontmatter record so downstream tooling can read it without
+                        // re-parsing the content body. Omitted when not present.
+                        ...(candidate.orderedActions && candidate.orderedActions.length > 0
+                            ? { orderedActions: candidate.orderedActions }
+                            : {}),
+                        ...(candidate.outcomeData ? { outcomeData: candidate.outcomeData } : {}),
+                        // WS-3b step 0c: tag system-generated extractions as hot-probation
+                        // when the feature is enabled. The consolidation pass will exclude
+                        // them from the LLM merge pool until the intake dedup+quality pass
+                        // runs against them. User-explicit `akm remember` (captureMode: hot)
+                        // is unaffected — this only applies to extract-generated proposals.
+                        ...(hotProbationEnabled ? buildHotProbationFrontmatter() : {}),
                     },
                 },
             }, ctx);
@@ -319,6 +444,7 @@ async function processSession(harness, sessionRef, stashDir, config, llmConfig,
             truncatedCount: filtered.stats.truncatedCount,
         },
         warnings,
+        contentHash,
         ...sessionAsset,
     };
 }
@@ -399,6 +525,9 @@ export async function akmExtract(options) {
         : DEFAULT_MAX_SESSIONS_PER_RUN;
     // Default discovery window — process config can override the built-in 24h.
     const effectiveSince = options.since ?? extractProcess?.defaultSince;
+    // #626 — resolve the triage gate config once per run. Default-off → the
+    // per-session path never calls the scorer and emits no telemetry.
+    const triage = resolveTriageConfig(extractProcess);
     // #561 — resolve session-indexing config. Default ON: we only reach this code
     // when `session_extraction` is enabled AND an LLM is configured (both checked
     // above), so defaulting on costs nothing offline (the summary call fails open)
@@ -496,6 +625,10 @@ export async function akmExtract(options) {
     const sessions = [];
     let processedCount = 0;
     let skippedCount = 0;
+    // #626 — per-run triage aggregation counters (counts-only telemetry, AC4).
+    let triageEvaluated = 0;
+    let triagePassed = 0;
+    let triagedOut = 0;
     const allProposalIds = [];
     const topLevelWarnings = [];
     const chat = options.chat ?? chatCompletion;
@@ -519,27 +652,28 @@ export async function akmExtract(options) {
             stateDb = undefined;
         }
     }
+    // WS-3b Step-0b: schema-similarity intake gate.
+    // Load derived-layer (lesson/knowledge) embeddings once per run, but ONLY
+    // when the gate is enabled in config. When disabled (the default) this block
+    // is fully skipped and schemaSimilarityCtx stays null → byte-identical to
+    // prior behaviour.
+    const schemaSimilarityCfg = extractProcess?.schemaSimilarity;
+    let schemaSimilarityCtx = null;
+    if (schemaSimilarityCfg?.enabled === true) {
+        const derivedEmbeddings = options.schemaSimilarityEmbeddings ?? loadDerivedLayerEmbeddings();
+        schemaSimilarityCtx = {
+            config: schemaSimilarityCfg,
+            derivedEmbeddings,
+            embeddingConfig: config.embedding,
+            embedFn: options.schemaSimilarityEmbedFn,
+        };
+    }
     for (const summary of candidates) {
-        // Skip-tracking: if this session was already processed AND no new events
-        // have arrived since (live endedAt <= recorded endedAt), don't burn an LLM
-        // call. --force or single-session mode (explicit sessionId) bypasses.
+        // #602 — the already-extracted skip moved INTO processSession (the content
+        // hash needs the session body, only available after readSession). The prior
+        // row + bypass flags are threaded through; an unchanged session returns
+        // skipReason 'already_extracted' WITHOUT any LLM call.
         const prior = seenMap.get(summary.sessionId);
-        if (!options.force && !options.sessionId && shouldSkipAlreadyExtractedSession(prior, summary.endedAt)) {
-            sessions.push({
-                sessionId: summary.sessionId,
-                harness: harness.name,
-                candidateCount: 0,
-                proposalIds: [],
-                preFilter: { inputCount: 0, outputCount: 0, truncatedCount: 0 },
-                warnings: [
-                    `already extracted at ${prior?.processed_at}; pass --force to re-process or wait until the session has new content`,
-                ],
-                skipped: true,
-                skipReason: "already_extracted",
-            });
-            skippedCount += 1;
-            continue;
-        }
         // Per-run cap on LLM-processed sessions (skip-tracked seen sessions above
         // don't count). Single-session / --force modes bypass the cap (explicit
         // intent). Overflow sessions are left unseen for the next run.
@@ -548,17 +682,36 @@ export async function akmExtract(options) {
             break;
         }
         try {
-            const result = await processSession(harness, summary, stashDir, config, llmConfig, chat, options.ctx, sourceRun, dryRun, timeoutMs, maxTotalChars, minContentChars, sessionIndexing);
+            const result = await processSession(harness, summary, stashDir, config, llmConfig, chat, options.ctx, sourceRun, dryRun, timeoutMs, maxTotalChars, minContentChars, triage, sessionIndexing, schemaSimilarityCtx, prior, options.force === true, typeof options.sessionId === "string" && options.sessionId.length > 0);
             sessions.push(result);
+            // #626 — triage aggregation. A session reached the triage gate only when it
+            // was NOT already preempted by an earlier skip (read_failed / too_short /
+            // already_extracted handled above the processSession call). When triage is
+            // enabled, processSession either triages-out (skipReason 'triaged_out') or
+            // proceeds past the gate — both count as "evaluated".
+            if (triage.enabled) {
+                const preemptedBeforeTriage = result.skipReason === "read_failed" ||
+                    result.skipReason === "too_short" ||
+                    result.skipReason === "already_extracted";
+                if (!preemptedBeforeTriage) {
+                    triageEvaluated += 1;
+                    if (result.skipReason === "triaged_out")
+                        triagedOut += 1;
+                    else
+                        triagePassed += 1;
+                }
+            }
             if (result.skipped)
                 skippedCount += 1;
             else
                 processedCount += 1;
             allProposalIds.push(...result.proposalIds);
-            // Persist outcome so the next run skips this session unless new events
-            // arrive. We only track non-dry-run paths — dry-run is for inspection
-            // and should never poison the seen-table.
-            if (trackingEnabled && stateDb && !dryRun) {
+            // Persist outcome so the next run skips this session unless its content
+            // changes. We only track non-dry-run paths — dry-run is for inspection
+            // and should never poison the seen-table. #602: an `already_extracted`
+            // skip is a no-op (the row already carries the matching hash), so don't
+            // re-write it — that keeps `processed_at` stable across unchanged runs.
+            if (trackingEnabled && stateDb && !dryRun && result.skipReason !== "already_extracted") {
                 try {
                     const outcome = result.skipped
                         ? result.skipReason === "read_failed" || result.skipReason === "exception"
@@ -577,6 +730,10 @@ export async function akmExtract(options) {
                         proposalCount: result.proposalIds.length,
                         rationale: result.rationaleIfEmpty ?? null,
                         sourceRun,
+                        // #602 — persist the freshly computed content hash so the NEXT run
+                        // can compare byte-for-byte. read_failed (before hash) → null, which
+                        // keeps the row eligible for retry (matches failed-row semantics).
+                        contentHash: result.contentHash ?? null,
                         metadata: {
                             preFilterInputCount: result.preFilter.inputCount,
                             preFilterOutputCount: result.preFilter.outputCount,
@@ -624,6 +781,20 @@ export async function akmExtract(options) {
             // best-effort close
         }
     }
+    // #626 — counts-only triage telemetry (AC4). Exactly ONE aggregated event per
+    // run, emitted only when the gate was enabled and actually evaluated at least
+    // one session. No per-session events (avoids the log-spam the issue warns of).
+    if (triage.enabled && triageEvaluated > 0) {
+        appendEvent({
+            eventType: "extract_triaged",
+            metadata: {
+                evaluated: triageEvaluated,
+                passed: triagePassed,
+                triagedOut,
+                sourceRun,
+            },
+        }, options.ctx);
+    }
     return {
         schemaVersion: 1,
         ok: true,
@@ -645,9 +816,15 @@ export async function akmExtract(options) {
  * logic in {@link akmExtract} so the `#554 minNewSessions` gate in `improve`
  * can decide whether the extract pass is worth running before any work begins.
  *
- * A session is a "new candidate" when it is in the `since` window AND it would
- * not be skipped by {@link shouldSkipAlreadyExtractedSession} (i.e. it has never
- * been extracted, or new events have arrived since it was last extracted).
+ * #602 — this gate is intentionally CHEAP: it does NOT read session bodies, so
+ * it cannot compute the content hash that {@link shouldSkipAlreadyExtractedSession}
+ * now uses. It therefore uses a CONSERVATIVE row-presence approximation: a
+ * session counts as "new" when there is NO prior row OR the prior row's
+ * `content_hash` is null (never-seen or backfill-eligible). A prior row WITH a
+ * non-null content_hash counts as NOT new — it MIGHT have changed, but the
+ * precise per-session hash check happens downstream in processSession, so an
+ * over-/under-count here only affects whether the pass RUNS, never whether a
+ * changed session is actually re-processed.
  */
 export function countNewExtractCandidates(config, options = {}) {
     const extractProcess = config.profiles?.improve?.default?.processes?.extract;
@@ -681,7 +858,10 @@ export function countNewExtractCandidates(config, options = {}) {
             }
             for (const summary of candidates) {
                 const prior = seenMap.get(summary.sessionId);
-                if (shouldSkipAlreadyExtractedSession(prior, summary.endedAt))
+                // #602 row-presence approximation (see fn doc): a prior row WITH a
+                // non-null content_hash is treated as not-new here; everything else
+                // (never-seen, or null-hash backfill-eligible) counts as new.
+                if (prior && prior.content_hash != null)
                     continue;
                 total += 1;
             }

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 };
+}