comisai 1.0.42 → 1.0.45

package/node_modules/@comis/daemon/dist/wiring/setup-learning.js

@@ -0,0 +1,545 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Outcome-signal (Verified Learning WS1) write-back wiring.
+ *
+ * The composition-root glue between the deterministic completion bus events
+ * (`tool:executed`, `graph:completed`, `diagnostic:message_processed`) and the
+ * `OutcomeSignalPort` (@comis/memory adapter). The daemon is the ONLY place holding
+ * BOTH the bus AND the adapter — the agent↛memory build cut means the agent emits
+ * ids+counts on the bus and the daemon does the observe/resolve. Mirrors
+ * `wireMemoryUsefulness`. The resolve→consume chain is shared by the DAG
+ * (`graph:completed`) AND single-agent (`diagnostic:message_processed`) seams and
+ * runs at most ONCE per trajectory (resolve() is a pure read; both events can fire
+ * for one DAG turn). Counts + ids + closed-enums ONLY cross the bus (§2.7 / SEC-01).
+ *
+ * BYTE-IDENTITY GATE: every handler's FIRST statement is the
+ * `learningOutcomeEnabled(agentId)` short-circuit — default config observes/resolves/
+ * emits NOTHING (the recall/score hot path is byte-identical). Fire-and-forget /
+ * non-fatal: a failing observe/resolve warns and continues, never throwing out of the
+ * handler or blocking the turn. An `unknown` resolved outcome derives no learning
+ * (fail-closed, OUTCOME-05) and is NOT counted as resolved coverage.
+ *
+ * @module
+ */
+import { tryGetContext, } from "@comis/core";
+import { deriveTenantFromSessionKey } from "./setup-memory-usefulness-wiring.js";
+import { createSkillTrendTracker } from "./setup-learning-skill-trend.js";
+import { markTrajectoryResolved } from "./setup-learning-dedup.js";
+import { failureCorroborated, CORROBORATION_MIN_INDEPENDENT, MAX_TRACKED_FAILURE_MEMORIES, } from "./setup-learning-corroboration.js";
+// OUTCOME-04 judge fallback lives in its own leaf (no cycle: setup-learning → judge only).
+import { maybeUpgradeWithJudge } from "./setup-learning-judge.js";
+// SURFACE-04/05/06 skill promote/demote loop lives in its own leaf (no cycle: it imports
+// failureCorroborated from setup-learning-corroboration.ts, nothing from here).
+import { applySkillOutcomeTransitions } from "./setup-learning-skill-transitions.js";
+// Re-export for the existing importers (setup-learning.test.ts) — moved to the leaf
+// to keep this file under the 800-line cap; the gate logic is unchanged.
+export { failureCorroborated, CORROBORATION_MIN_INDEPENDENT, MAX_TRACKED_FAILURE_MEMORIES };
+/** High-confidence default for a clean deterministic tool/pipeline signal. */
+const DETERMINISTIC_CONFIDENCE = 0.9;
+/** Slightly lower confidence for a content/detector-classified (non-transport) tool failure. */
+const CLASSIFIED_FAILURE_CONFIDENCE = 0.8;
+/**
+ * ATTR-02: confidence for a pure skill-attribution row (memory:skill_used → observe).
+ * LOW + paired with `outcome:"unknown"` so the row NEVER wins resolve() fusion — it
+ * carries the `used_skill_ids` column only, asserting no outcome verdict.
+ */
+const ATTRIBUTION_CONFIDENCE = 0;
+/**
+ * Resolve the (tenant, agent, session, trajectory) scope for an observation. Payload
+ * fields win when present (tool:executed / memory:skill_used / diagnostic:message_
+ * processed all carry agentId/traceId/sessionKey); ALS is the fallback (graph:completed
+ * carries only graphId). Returns `undefined` when neither source yields an agentId AND a
+ * trajectory identity (caller skips). Tenant defaults to "default" only when absent; the
+ * agentId is NEVER collapsed across agents (cross-agent isolation, T-198-16).
+ */
+function resolveScope(payload) {
+    const ctx = tryGetContext();
+    const agentId = payload.agentId ?? ctx?.agentId;
+    const trajectoryId = payload.traceId ?? ctx?.traceId;
+    if (agentId === undefined || agentId.length === 0)
+        return undefined;
+    if (trajectoryId === undefined || trajectoryId.length === 0)
+        return undefined;
+    const sessionKey = payload.sessionKey ?? ctx?.sessionKey;
+    const tenantId = deriveTenantFromSessionKey(sessionKey) ?? ctx?.tenantId ?? "default";
+    // sessionId is the conversation identity; the events carry sessionKey (not a
+    // distinct sessionId). Use sessionKey when present, else fall back to the
+    // trajectory identity (a stable, scope-consistent key).
+    const sessionId = sessionKey ?? trajectoryId;
+    return { tenantId, agentId, sessionId, trajectoryId };
+}
+/**
+ * Persist one raw observation, fire-and-forget / non-fatal. NEVER throws out of
+ * the bus handler. Counts/ids/closed-enums only ever reach the store.
+ */
+function observeNonFatal(deps, scope, outcome, source, confidence, usedSkillIds, recalledIds) {
+    return deps.outcomeStore
+        .observe({
+        tenantId: scope.tenantId,
+        agentId: scope.agentId,
+        sessionId: scope.sessionId,
+        trajectoryId: scope.trajectoryId,
+        outcome,
+        source,
+        confidence,
+        // ATTR-02: thread the per-turn used-skill ids onto observe() so the
+        // used_skill_ids COLUMN is written; resolve() union-dedups across rows. Omitted
+        // (the tool/pipeline paths) ⇒ the column stays NULL, byte-identical to pre-ATTR-02.
+        ...(usedSkillIds !== undefined && usedSkillIds.length > 0 ? { usedSkillIds: [...usedSkillIds] } : {}),
+        // OUTCOME-06 / RANK-01 (live 2026-06-18): thread the per-turn recalled+used memory
+        // ids onto observe() so the recalled_ids COLUMN is written; resolve() union-dedups
+        // them onto `verdict.recalledIds`, which is what the outcome-gated reward seam keys
+        // on (success→recordUsage, failure/corrected→recordFailure → failure_count). Omitted
+        // (tool/pipeline/skill paths) ⇒ NULL, byte-identical. Without this carrier the
+        // outcome-gated recall reward was DORMANT (recalledIds always empty).
+        ...(recalledIds !== undefined && recalledIds.length > 0 ? { recalledIds: [...recalledIds] } : {}),
+        observedAt: deps.clock.now(),
+    })
+        .then((r) => {
+        if (!r.ok) {
+            deps.logger.warn({
+                agentId: scope.agentId,
+                source,
+                errorKind: "internal",
+                hint: "outcome observe failed; the outcome signal was not persisted for this trajectory",
+            }, "outcome observe failed (non-fatal)");
+        }
+    })
+        .catch((e) => {
+        deps.logger.warn({
+            agentId: scope.agentId,
+            source,
+            err: e instanceof Error ? e : new Error(String(e)),
+            errorKind: "internal",
+            hint: "outcome observe threw; the outcome signal was not persisted for this trajectory",
+        }, "outcome observe threw (non-fatal)");
+    });
+}
+// FORGET-03 corroboration gate (failureCorroborated + its constants) lives in
+// ./setup-learning-corroboration.js (imported + re-exported above) — extracted to keep
+// this file under the 800-line cap; the gate logic is byte-identical.
+/**
+ * Run one usefulness-store reward/failure write, fire-and-forget / non-fatal.
+ * NEVER throws out of the bus handler. `kind` tags the WARN so an operator sees
+ * which write (reward vs failure-accrual) was dropped. Counts/ids only reach the
+ * store (the (tenant, agent) scope is the load-bearing isolation boundary).
+ */
+function recordNonFatal(deps, agentId, kind, run) {
+    void Promise.resolve()
+        .then(run)
+        .then((r) => {
+        if (!r.ok) {
+            deps.logger.warn({
+                agentId,
+                errorKind: "internal",
+                hint: `outcome ${kind} write failed; the ${kind} state transition was not persisted for this trajectory`,
+            }, `outcome ${kind} write failed (non-fatal)`);
+        }
+    })
+        .catch((e) => {
+        deps.logger.warn({
+            agentId,
+            err: e instanceof Error ? e : new Error(String(e)),
+            errorKind: "internal",
+            hint: `outcome ${kind} write threw; the ${kind} state transition was not persisted for this trajectory`,
+        }, `outcome ${kind} write threw (non-fatal)`);
+    });
+}
+// SURFACE-04/05/06: the learned-skill promote/demote loop (applySkillOutcomeTransitions
+// + runSkillTransition + skillGaugeKey + SkillOutcomeDeps) lives in the
+// setup-learning-skill-transitions.ts leaf (imported above) to keep this file under the
+// 800-line cap. It imports `failureCorroborated` from setup-learning-corroboration.ts
+// directly (no back-import here → no cycle).
+// OUTCOME-04: `maybeUpgradeWithJudge` (the unknown→judge upgrade) lives in the
+// setup-learning-judge.ts leaf (imported above) to keep this file under the 800-line cap.
+/**
+ * Stand up the observe/resolve subscriber on the daemon's bus. Fire-and-forget /
+ * non-fatal; default-OFF via `learningOutcomeEnabled`.
+ *
+ * Wiring:
+ *  - `tool:executed`               → observe a `tool` outcome (`success===false`→failure).
+ *  - `memory:skill_used`           → observe the ATTR-02 used-skill ids (attribution row).
+ *  - `graph:completed` (DAG)       → observe a `pipeline` outcome, then the shared
+ *                                    resolve→consume chain. (`graph:driver_lifecycle`
+ *                                    is NOT observed — per-node, floods the ledger; WR-02.)
+ *  - `diagnostic:message_processed` → the single-agent turn's resolve→consume (CR; the
+ *                                    common turn never fires graph:completed).
+ *
+ * The shared chain resolves the fused verdict, runs RANK/FORGET/SURFACE consumers,
+ * emits `learning:outcome_observed` (counts/ids only), updates the fail-closed coverage
+ * gauge (`resolved` counts only a non-`unknown` outcome, T-198-18), and runs at most
+ * ONCE per trajectory (a DAG turn fires BOTH completion events).
+ */
+export function wireLearningOutcome(deps) {
+    // Daemon-lifetime coverage gauge (resets on restart). Counts only.
+    let total = 0;
+    let resolved = 0;
+    // FORGET-03 corroboration tally: memoryId → the DISTINCT sessions that failed it
+    // (within this subscriber's lifetime). A NON-deterministic failure accrues
+    // `failure_count` only once this reaches ≥2 distinct sessions; a deterministic
+    // failure (tool/pipeline) bypasses it. Mirrors the coverage gauge's in-process
+    // counters (resets on restart) — counts/ids only, never bodies.
+    const failureCorroborationTally = new Map();
+    // SURFACE-05: a SECOND, independent daemon-lifetime corroboration tally for the
+    // learned-SKILL demote path (skillId → DISTINCT failing sessions). Kept separate
+    // from the memory tally above so the two write paths never alias an id. Reuses the
+    // SAME failureCorroborated() gate (≥2 distinct-session OR 1 deterministic).
+    const skillFailureCorroborationTally = new Map();
+    // SURFACE-05: the in-process, daemon-lifetime decay-aware trend (the WHEN-to-demote
+    // decision). A corroborated failure demotes ONLY when the trend reaches WEAKENING —
+    // so a single induced failure on a well-reused procedure does NOT archive it. WR-05:
+    // its keys are scope-qualified (tenant+agent+name) by the caller (skillGaugeKey).
+    const skillTrend = createSkillTrendTracker();
+    // WR-01: the per-agent surface-cache refresh closure (looked up from the shared
+    // registry threaded via deps) — fired after a REAL promote/demote so the next
+    // session sees the new active set. Undefined ⇒ no refresh (byte-identical).
+    const refreshSurface = deps.refreshLearnedSkillSurface;
+    // CR (idempotency): the per-trajectory resolve-dedup set (see setup-learning-dedup.ts).
+    const resolvedTrajectories = new Set();
+    /**
+     * CR: the SHARED resolve→consume chain called by BOTH the `graph:completed` (DAG)
+     * and `diagnostic:message_processed` (single-agent turn) handlers — factored out so
+     * the reward/forget-accrual/skill-transition logic is NOT duplicated. Runs AT MOST
+     * ONCE per trajectory ({@link markTrajectoryResolved}). The caller resolves the scope
+     * from its own source (graph: ALS; diagnostic: the payload, mirroring 199 CR-02) and,
+     * for the DAG path, observes the pipeline row FIRST. Non-fatal — never throws.
+     */
+    function resolveAndConsume(scope, resolveStart) {
+        // Dedup FIRST (synchronous check-and-mark before the async resolve) so a
+        // both-events DAG turn cannot slip a second chain through.
+        if (!markTrajectoryResolved(scope.trajectoryId, resolvedTrajectories))
+            return;
+        void deps.outcomeStore
+            .resolve(scope.trajectoryId, { tenantId: scope.tenantId, agentId: scope.agentId })
+            .then(async (r) => {
+            total += 1;
+            if (!r.ok) {
+                deps.logger.warn({
+                    agentId: scope.agentId,
+                    errorKind: "internal",
+                    hint: "outcome resolve failed; no learning:outcome_observed emitted for this trajectory",
+                }, "outcome resolve failed (non-fatal)");
+                return;
+            }
+            // OUTCOME-04: an `unknown` deterministic verdict (a CONVERSATIONAL turn with no
+            // tool/pipeline signal) gets ONE cheap-model judge pass as the fallback source;
+            // a non-`unknown` verdict is returned unchanged (the judge never runs). The
+            // dedup already ran at the top — this is the SAME chain (no second chain).
+            const verdict = await maybeUpgradeWithJudge(deps, scope, r.value);
+            // Fail-closed coverage: an `unknown` verdict is NOT counted as resolved.
+            if (verdict.outcome !== "unknown")
+                resolved += 1;
+            // ---- RANK-01 / FORGET-02 reward/failure write (the agent↛memory cut: the
+            // daemon holds BOTH this verdict AND the usefulness adapter). intent OMITTED →
+            // the global '' bucket; an `unknown` verdict writes NOTHING (fail-closed). ----
+            let failureAccrued = 0;
+            if (verdict.outcome === "success") {
+                if (deps.learningTuningEnabled(scope.agentId) && verdict.recalledIds.length > 0) {
+                    const rewardScope = { tenantId: scope.tenantId, agentId: scope.agentId, now: deps.clock.now() };
+                    // IN-01: ONE batched reward write for ALL recalled ids (the store loops in
+                    // one transaction); the FAILURE branch below stays per-id (gated per memory).
+                    recordNonFatal(deps, scope.agentId, "reward", () => deps.usefulnessStore.recordUsage(verdict.recalledIds, [], rewardScope));
+                }
+            }
+            else if (verdict.outcome === "failure" || verdict.outcome === "corrected") {
+                if (deps.learningForgettingEnabled(scope.agentId)) {
+                    const failScope = { tenantId: scope.tenantId, agentId: scope.agentId, now: deps.clock.now() };
+                    for (const mid of verdict.recalledIds) {
+                        // FORGET-03 gate: accrue ONLY when corroborated (≥2 independent sessions
+                        // OR 1 deterministic source); past it the accrual is UNCONDITIONAL (no
+                        // daemon-side proof/trust read — the eviction exemption is store-side).
+                        if (failureCorroborated(mid, scope.sessionId, verdict.sources, failureCorroborationTally)) {
+                            failureAccrued += 1;
+                            recordNonFatal(deps, scope.agentId, "failure_accrual", () => deps.usefulnessStore.recordFailure(mid, failScope));
+                        }
+                    }
+                }
+            }
+            // ---- SURFACE-04/05/06 learned-SKILL promote/demote: iterate the ATTR-02
+            // verdict.usedSkillIds — `success` PROMOTES each; a corroborated failure
+            // DEMOTES only when the decay-aware trend reaches WEAKENING (anti-induced).
+            // Gated default-OFF / no-store ⇒ byte-identical. AWAITS the store to read
+            // rows-changed so a 0-row write does NOT inflate the counters (CR-01). ----
+            if (deps.learnedSkillStore !== undefined &&
+                deps.learningSkillsEnabled?.(scope.agentId) === true) {
+                void applySkillOutcomeTransitions(deps, scope, verdict, {
+                    skillStore: deps.learnedSkillStore,
+                    threshold: deps.learningSkillsPromoteAt?.(scope.agentId) ?? 3,
+                    skillFailureCorroborationTally,
+                    skillTrend,
+                    refreshSurface,
+                });
+            }
+            // Emit the resolved outcome (counts/ids/closed-enums ONLY — bridged for comis explain).
+            deps.eventBus.emit("learning:outcome_observed", {
+                agentId: scope.agentId,
+                traceId: scope.trajectoryId,
+                trajectoryId: scope.trajectoryId,
+                outcome: verdict.outcome,
+                source: verdict.sources[0] ?? "pipeline",
+                confidence: verdict.confidence,
+                timestamp: deps.clock.now(),
+            });
+            // When corroborated failures accrued (failure_count++) this resolve, emit the
+            // eviction-causation precursor (count only, bridged for comis explain) so "why did/didn't
+            // this memory evict" has an event trail — not just a DB column that changes over time. The
+            // accrual is already FORGET-03 corroboration-gated above.
+            if (failureAccrued > 0) {
+                deps.eventBus.emit("learning:memory_failure_attributed", {
+                    agentId: scope.agentId,
+                    count: failureAccrued,
+                    timestamp: deps.clock.now(),
+                });
+            }
+            // OBS-01/02: one INFO completion line per resolve with durationMs + the
+            // running coverage gauge + the corroborating `sources` (counts/ids only).
+            deps.logger.info({
+                agentId: scope.agentId,
+                outcome: verdict.outcome,
+                sources: verdict.sources,
+                corroboratingSourceCount: verdict.sources.length,
+                resolvedCount: resolved,
+                totalCount: total,
+                durationMs: deps.clock.now() - resolveStart,
+            }, "Outcome resolved for trajectory");
+            // OBS-01 DEBUG: the corroboration outcome (counts only) so the gate decision is
+            // reconstructable — recalled vs accrued. Never alpha values / memory bodies.
+            deps.logger.debug({
+                agentId: scope.agentId,
+                step: "outcome-resolve",
+                sources: verdict.sources,
+                recalledCount: verdict.recalledIds.length,
+                failureAccrued,
+            }, "outcome resolve detail");
+        })
+            .catch((e) => {
+            deps.logger.warn({
+                agentId: scope.agentId,
+                err: e instanceof Error ? e : new Error(String(e)),
+                errorKind: "internal",
+                hint: "outcome resolve/emit threw; no learning:outcome_observed emitted for this trajectory",
+            }, "outcome resolve threw (non-fatal)");
+        });
+    }
+    // ---- Deterministic tool signal (the only source that ships ACTIVE, OUTCOME-03) ----
+    deps.eventBus.on("tool:executed", (p) => {
+        // Byte-identity short-circuit (default OFF) — observe NOTHING.
+        const agentId = p.agentId ?? tryGetContext()?.agentId;
+        if (agentId === undefined || !deps.learningOutcomeEnabled(agentId))
+            return;
+        const scope = resolveScope(p);
+        if (scope === undefined)
+            return;
+        // The failure signal is the real `success` boolean field. A transport-level
+        // / sdk_iserror failure is the highest-confidence deterministic signal; a
+        // content/detector/mcp-classified failure is still a failure at a slightly
+        // lower confidence (the fusion still ranks tool above judge regardless).
+        const outcome = p.success === false ? "failure" : "success";
+        const confidence = outcome === "failure" && p.transportOk !== false && p.classifiedFailureBy !== "sdk_iserror"
+            ? CLASSIFIED_FAILURE_CONFIDENCE
+            : DETERMINISTIC_CONFIDENCE;
+        void observeNonFatal(deps, scope, outcome, "tool", confidence);
+    });
+    // ---- ATTR-02 skill-use attribution write-back (the loop-close, Plan 07) ----
+    // The agent emits `memory:skill_used` (Plan 03) after a turn whose `read` matched a
+    // frozen learned-skill `<location>` — the per-turn used-skill ids (counts/ids only,
+    // the memory:recall_used precedent). The daemon is the ONLY place holding BOTH the
+    // bus AND the @comis/memory store (the agent↛memory cut), so the daemon does the
+    // observe() write here: a neutral `explicit`/`unknown` attribution row carrying the
+    // `usedSkillIds` so the `used_skill_ids` COLUMN is written. The `unknown` outcome +
+    // low confidence means this row NEVER wins the resolve() fusion (the deterministic
+    // tool/pipeline rows outrank it) — it is a pure attribution carrier; resolve()
+    // union-dedups the column across ALL the trajectory's rows. Default-OFF via
+    // `learningOutcomeEnabled` (byte-identical when off); a non-empty carrier is required.
+    deps.eventBus.on("memory:skill_used", (p) => {
+        const agentId = p.agentId ?? tryGetContext()?.agentId;
+        if (agentId === undefined || !deps.learningOutcomeEnabled(agentId))
+            return;
+        // Nothing attributed this turn → no write (avoids an empty attribution row).
+        if (p.usedSkillIds.length === 0)
+            return;
+        const scope = resolveScope({ agentId: p.agentId, traceId: p.traceId, sessionKey: p.sessionKey });
+        if (scope === undefined)
+            return;
+        // ATTRIBUTION_CONFIDENCE: a neutral, low-confidence `explicit`/`unknown` carrier —
+        // it threads the used-skill ids onto the column WITHOUT asserting an outcome verdict
+        // (resolve() fuses the real tool/pipeline outcome; this row only carries ids).
+        void observeNonFatal(deps, scope, "unknown", "explicit", ATTRIBUTION_CONFIDENCE, p.usedSkillIds);
+    });
+    // ---- OUTCOME-06 / RANK-01 recall-use attribution write-back (live 2026-06-18) ----
+    // The executor emits `memory:recall_used` after a turn (executor-post-execution.ts) with
+    // the recalled+used memory ids. wireMemoryUsefulness consumes it for the CORROBORATING
+    // usage feed (used_count) — but nothing wrote those ids onto the OUTCOME ledger, so
+    // `verdict.recalledIds` was ALWAYS empty and the PRIMARY outcome-gated reward seam
+    // (resolve → success:recordUsage / failure:recordFailure→failure_count) was DORMANT.
+    // Mirror the ATTR-02 skill-use carrier: a neutral `explicit`/`unknown` row (NEVER wins
+    // resolve() fusion — the deterministic tool/pipeline rows outrank it) that carries the
+    // recalled ids so the recalled_ids COLUMN is written and resolve() union-dedups them.
+    // Default-OFF via `learningOutcomeEnabled` (byte-identical when off); a non-empty
+    // carrier required (no empty attribution row).
+    deps.eventBus.on("memory:recall_used", (p) => {
+        const agentId = p.agentId ?? tryGetContext()?.agentId;
+        if (agentId === undefined || !deps.learningOutcomeEnabled(agentId))
+            return;
+        if (p.usedIds.length === 0)
+            return; // nothing recalled+used → no carrier row
+        const scope = resolveScope({ agentId: p.agentId, traceId: p.traceId, sessionKey: p.sessionKey });
+        if (scope === undefined)
+            return;
+        void observeNonFatal(deps, scope, "unknown", "explicit", ATTRIBUTION_CONFIDENCE, undefined, p.usedIds);
+    });
+    // NB: `graph:driver_lifecycle` is intentionally NOT subscribed (WR-02) — it is
+    // PER NODE, so observing it floods the ledger with O(nodes) `pipeline` rows and
+    // amplifies the WR-01 fusion non-determinism. `graph:completed` is the SINGLE
+    // trajectory-level pipeline signal.
+    // ---- DAG pipeline signal: observe the pipeline row FIRST (visible to the resolve),
+    // then the SHARED resolve→consume chain. graph:completed fires ONLY for DAG runs. ----
+    deps.eventBus.on("graph:completed", (p) => {
+        const ctx = tryGetContext();
+        const agentId = ctx?.agentId;
+        if (agentId === undefined || !deps.learningOutcomeEnabled(agentId))
+            return;
+        // graph:completed carries only graphId — recover the scope from ALS.
+        const scope = resolveScope({});
+        if (scope === undefined)
+            return;
+        // Success ONLY on a CLEAN completion; failed/cancelled/running → failure.
+        const outcome = p.status === "completed" ? "success" : "failure";
+        const resolveStart = deps.clock.now();
+        void observeNonFatal(deps, scope, outcome, "pipeline", DETERMINISTIC_CONFIDENCE).then(() => resolveAndConsume(scope, resolveStart));
+    });
+    // ---- CR: single-agent turn completion → resolve via the per-turn PAYLOAD ----
+    // graph:completed fires ONLY for DAG runs, so a single-agent turn never resolved —
+    // its tool:executed + memory:skill_used rows (keyed on traceId) went unresolved.
+    // diagnostic:message_processed fires once per turn for single-agent turns too
+    // (execution-pipeline.ts) and carries agentId/sessionKey/traceId on its PAYLOAD — so
+    // resolve keys off the payload NOT the ALS (the emit is outside runWithContext;
+    // mirrors 199 CR-02). The trajectoryId is the payload traceId = the SAME key the
+    // tool/skill observe() wrote, so resolve finds the rows. NO pipeline observe; an
+    // absent traceId → skip (fail-closed); the dedup makes a both-events DAG turn resolve once.
+    deps.eventBus.on("diagnostic:message_processed", (p) => {
+        if (!deps.learningOutcomeEnabled(p.agentId))
+            return;
+        const scope = resolveScope({ agentId: p.agentId, traceId: p.traceId, sessionKey: p.sessionKey });
+        if (scope === undefined)
+            return; // no trajectory identity (absent traceId) → skip
+        resolveAndConsume(scope, deps.clock.now());
+    });
+    // ---- SURFACE-ADMIT (live-2026-06-18): refresh the per-agent surface the MOMENT a
+    // reflection run ADMITS a doc. Without this a freshly-admitted candidate stays invisible
+    // until the next daemon boot — and promotion is USE-gated (the agent must SEE the skill to
+    // use it), so the post-promote/demote refresh can NEVER fire: a second-order deadlock that
+    // leaves a learned skill permanently dormant on a long-running daemon. `reflect:admitted.count`
+    // IS the admitted count (events-learning.ts emits v.admitted; RENAMED from
+    // learning:skill_synthesized in Phase 226). NOT gated by learningOutcomeEnabled (this is a
+    // SKILLS signal); refreshSurface is undefined when no registry is wired ⇒ byte-identical no-op.
+    // Mirrors the post-promote/demote refresh. ----
+    deps.eventBus.on("reflect:admitted", (p) => {
+        if (p.count > 0)
+            refreshSurface?.(p.agentId);
+    });
+    // ---- Correction-driven demote: demote the learned skill a user CORRECTION invalidated. The
+    // correction reader observed a `corrected` soft-failure against the PRIOR trajectory and emitted
+    // `learning:correction_observed`; the normal resolve seam already CONSUMED that trajectory
+    // (markTrajectoryResolved dedup), so the skill demote can ONLY happen here. We re-RESOLVE the prior
+    // trajectory (read-only) to recover its CREDITED skills, then run ONLY the GATED skill-transition
+    // with a `corrected` verdict — NOT the full resolveAndConsume (which would re-run failure-accrual /
+    // re-emit / double-count). Reuses the SAME corroboration tally + decay-aware trend as the
+    // resolve-seam demote, so the anti-flap belt holds: a single correction never stales a well-reused
+    // skill; a corroborated (≥2 distinct (session,sender)) correction flips active/candidate→stale
+    // (KEPT, not deleted — revivable). Gated default-OFF / no-store ⇒ byte-identical no-op. ----
+    deps.eventBus.on("learning:correction_observed", (p) => {
+        const skillStore = deps.learnedSkillStore;
+        if (skillStore === undefined || deps.learningSkillsEnabled?.(p.agentId) !== true)
+            return;
+        void (async () => {
+            const r = await deps.outcomeStore.resolve(p.trajectoryId, { tenantId: p.tenantId, agentId: p.agentId });
+            // No credited skill on the corrected turn → nothing to demote (fail-closed, non-fatal).
+            if (!r.ok || r.value.usedSkillIds.length === 0)
+                return;
+            // One INFO line per correction that credits ≥1 skill — the re-resolve is OTHERWISE silent until
+            // the 3rd corroborated correction actually demotes (anti-flap), so a single real correction
+            // couldn't be confirmed live. Counts/ids only — the skill COUNT, never the procedure body/id-list
+            // (the §2.7 / SEC-01 firewall). Rare + load-bearing (a user correction feeding the demote gate is
+            // the acute signal), so INFO (not DEBUG) — diagnosability must not depend on logLevel:debug having
+            // been set before the incident.
+            deps.logger.info({
+                agentId: p.agentId,
+                tenantId: p.tenantId,
+                sessionId: p.sessionId,
+                trajectoryId: p.trajectoryId,
+                creditedSkillCount: r.value.usedSkillIds.length,
+                confidence: p.confidence,
+                step: "correction-demote-reresolve",
+            }, "Correction re-resolve: feeding prior trajectory's credited skills to the gated demote");
+            const scope = { tenantId: p.tenantId, agentId: p.agentId, sessionId: p.sessionId, trajectoryId: p.trajectoryId };
+            // An explicit `corrected` verdict carrying the prior turn's credited skills — the demote
+            // branch of applySkillOutcomeTransitions (source:"correction" feeds the corroboration gate).
+            const verdict = {
+                outcome: "corrected",
+                confidence: p.confidence,
+                sources: ["correction"],
+                recalledIds: [],
+                usedSkillIds: r.value.usedSkillIds,
+            };
+            await applySkillOutcomeTransitions(deps, scope, verdict, {
+                skillStore,
+                threshold: deps.learningSkillsPromoteAt?.(p.agentId) ?? 3,
+                skillFailureCorroborationTally,
+                skillTrend,
+                refreshSurface,
+            });
+        })();
+    });
+}
+/**
+ * Composition helper: compute the per-agent BYTE-IDENTITY enable gates from the
+ * parsed config and stand up {@link wireLearningOutcome}.
+ *
+ * Every gate force-disables on the master cost switch
+ * (`memory.enabled !== false` — renamed from costFeatures.enabled in Phase 226,
+ * OUTCOME-09) AND requires the agent's own learning flag. Phase 226 / M-1 COLLAPSED
+ * the four former per-feature flags (learningOutcome / learningTuning / learningForgetting /
+ * learningSkills `.enabled`) into the ONE `learning.enabled` gate — the RANK-01 reward,
+ * FORGET-02 accrual, and SURFACE-04 promote/demote WRITES all STAY wired, just behind the
+ * single flag. With `memory.enabled:false` every gate is `false` for every agent → the
+ * subscriber observes/resolves/emits/writes NOTHING → ranking/recall/replies are byte-identical.
+ */
+export function setupLearningOutcomeWiring(deps) {
+    // Master cost kill-switch: read defensively (`!== false`) so an absent block
+    // fails OPEN to the per-agent flag rather than silently force-disabling.
+    const costFeaturesEnabled = deps.config.memory?.enabled !== false;
+    // Hoist the typed agents map once (mirrors setup-schedulers.ts:107) so the per-agent
+    // lookup is a bracket access on a known Record (not a dynamic optional-chain sink).
+    const agents = deps.config.agents ?? {};
+    // M-1 (Phase 226): the single collapsed learning gate. The four reward/promote WRITES that
+    // were independently gated (each default-ON behind costFeatures) now share this one flag
+    // (default-ON `learning.enabled` under default-ON `memory.enabled`) — net enablement matches
+    // the prior opt-out posture; the per-feature split is gone by design (D-01).
+    const learningEnabled = (agentId) => costFeaturesEnabled && agents[agentId]?.learning?.enabled === true;
+    wireLearningOutcome({
+        eventBus: deps.eventBus,
+        outcomeStore: deps.outcomeStore,
+        usefulnessStore: deps.usefulnessStore,
+        learnedSkillStore: deps.learnedSkillStore,
+        clock: deps.clock,
+        logger: deps.logger,
+        learningOutcomeEnabled: learningEnabled, // the observe/resolve/emit subscriber (Phase 198)
+        learningTuningEnabled: learningEnabled, // RANK-01 SUCCESS→reward write — STAYS wired
+        learningForgettingEnabled: learningEnabled, // FORGET-02 FAILURE→failure_count accrual — STAYS wired
+        // SURFACE-04/05: the learned-skill promote/demote gate — STAYS wired behind the one flag +
+        // the per-agent promote threshold now reads learning.reflect.promoteAtProofCount.
+        learningSkillsEnabled: learningEnabled,
+        learningSkillsPromoteAt: (agentId) => agents[agentId]?.learning?.reflect?.promoteAtProofCount ?? 3,
+        // WR-01: route a post-transition re-refresh to the agent's surface cache (a no-op
+        // for an unregistered/default-off agent). Undefined registry ⇒ undefined closure.
+        refreshLearnedSkillSurface: deps.learnedSkillSurfaceRegistry
+            ? (agentId) => deps.learnedSkillSurfaceRegistry.refresh(agentId)
+            : undefined,
+        // OUTCOME-04: the conversational-breadth LLM-judge fallback (built in setup-memory via
+        // buildOutcomeJudgeWiring). Absent ⇒ the upgrade path is never entered (byte-identical).
+        outcomeJudge: deps.outcomeJudge,
+        learningOutcomeJudgeEnabled: deps.learningOutcomeJudgeEnabled,
+        readTurnTranscript: deps.readTurnTranscript,
+    });
+}

package/node_modules/@comis/daemon/dist/wiring/setup-logging.d.ts

@@ -1,8 +1,8 @@
 /**
  * Logging subsystem setup: file transport, tracing logger, log level
  * manager, module-bound loggers, and daemon version detection.
- * Extracted from daemon.ts steps 1.5 through 3.7 to isolate
- * infrastructure concerns from the main wiring sequence.
+ * Extracted from daemon.ts to isolate infrastructure concerns from the
+ * main wiring sequence.
  * @module
  */
 import type { AppContainer } from "@comis/core";

package/node_modules/@comis/daemon/dist/wiring/setup-logging.js

@@ -2,14 +2,16 @@
 /**
  * Logging subsystem setup: file transport, tracing logger, log level
  * manager, module-bound loggers, and daemon version detection.
- * Extracted from daemon.ts steps 1.5 through 3.7 to isolate
- * infrastructure concerns from the main wiring sequence.
+ * Extracted from daemon.ts to isolate infrastructure concerns from the
+ * main wiring sequence.
  * @module
  */
+import { LoggingConfigSchema, safePath } from "@comis/core";
 import { createFileTransport, isPm2Managed } from "../observability/log-infra.js";
 import { readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import os from "node:os";
 // ---------------------------------------------------------------------------
 // Setup function
 // ---------------------------------------------------------------------------
@@ -23,11 +25,44 @@ import { fileURLToPath } from "node:url";
  */
 export function setupLogging(deps) {
     const { container, instanceId, _createTracingLogger, _createLogLevelManager } = deps;
-    // 1.5. Construct file transport from logging config
+    // 1.5. Construct file transport from logging config.
+    // Forward observability.logRotation policy when present so pino-roll uses
+    // the cross-stream policy. The logRotation policy takes
+    // precedence over daemon.logging.maxSize/maxFiles for daemon.log.
     const loggingConfig = container.config.daemon?.logging;
-    const configLogLevel = container.config.logLevel ?? "info";
-    const fileTransport = loggingConfig ? createFileTransport(loggingConfig, configLogLevel) : undefined;
-    // 2. Create tracing logger (use config logLevel or default to "info")
+    const configLogLevel = container.config.logLevel ?? "debug";
+    const logRotation = container.config.observability?.logRotation
+        ? {
+            maxSizeBytes: container.config.observability.logRotation.maxSizeBytes,
+            maxFiles: container.config.observability.logRotation.maxFiles,
+        }
+        : undefined;
+    // B (obs-sweep): the structured-log filePath must track the RESOLVED data dir. The schema
+    // default (`~/.comis/logs/daemon.log`, schema-daemon.ts) is hardcoded to the DEFAULT home and
+    // does NOT honor a custom COMIS_DATA_DIR / config.dataDir — and the root `daemon` field is
+    // ALWAYS schema-defaulted (schema.ts), so `daemon.logging` is never undefined and that default
+    // path is always in force. Left as-is, a daemon with a custom data dir writes its structured
+    // log to the SHARED ~/.comis/logs — colliding with other instances and NOT landing at
+    // <dataDir>/logs/daemon.*.log as docs/operations/data-directory.mdx promises (proven live: a
+    // <dataDir>-configured daemon wrote 50MB to the real ~/.comis/logs while <dataDir>/logs held
+    // only the audit + session-index sinks, which DO resolve via safePath). Rebase the
+    // un-customized default onto <dataDir>; an EXPLICIT custom filePath is honored verbatim.
+    // dataDir is resolved the same way as daemon.ts (config.dataDir, else COMIS_DATA_DIR, else ~/.comis).
+    // eslint-disable-next-line no-restricted-syntax -- COMIS_DATA_DIR path resolution before SecretManager is initialized (mirrors daemon.ts:1170)
+    const dataDirEnv = process.env["COMIS_DATA_DIR"];
+    const resolvedDataDir = container.config.dataDir && container.config.dataDir.length > 0
+        ? container.config.dataDir
+        : (dataDirEnv ?? safePath(os.homedir(), ".comis"));
+    const effectiveLoggingConfig = loggingConfig ?? LoggingConfigSchema.parse({});
+    const schemaDefaultLogPath = LoggingConfigSchema.parse({}).filePath;
+    const resolvedLogPath = effectiveLoggingConfig.filePath === schemaDefaultLogPath
+        ? safePath(resolvedDataDir, "logs", "daemon.log")
+        : effectiveLoggingConfig.filePath;
+    const loggingConfigForTransport = resolvedLogPath === effectiveLoggingConfig.filePath
+        ? effectiveLoggingConfig
+        : { ...effectiveLoggingConfig, filePath: resolvedLogPath };
+    const fileTransport = createFileTransport(loggingConfigForTransport, configLogLevel, logRotation);
+    // 2. Create tracing logger (use config logLevel or default to "debug")
     const rawLogger = _createTracingLogger({
         name: "comis-daemon",
         level: configLogLevel,
@@ -35,9 +70,17 @@ export function setupLogging(deps) {
     });
     // Bind instanceId to root logger — all children inherit it
     const logger = rawLogger.child({ instanceId });
-    // Log transport mode so operators can verify PM2-aware selection
+    // Log transport mode so operators can verify PM2-aware selection. INFO (not DEBUG): an
+    // operator who can't find the structured log must see WHERE it went without flipping to
+    // debug first — names the resolved file path + whether it was defaulted (no daemon.logging
+    // block) so the "where are my logs?" question is answered from the boot line itself.
     const pm2Detected = isPm2Managed();
-    logger.debug({ pm2Detected, fileTransportEnabled: !!loggingConfig, stdoutEnabled: !pm2Detected }, "Log transport configured");
+    logger.info({
+        structuredLogPath: resolvedLogPath,
+        rebasedFromDefault: resolvedLogPath !== effectiveLoggingConfig.filePath,
+        pm2Detected,
+        stdoutEnabled: !pm2Detected,
+    }, "Structured logging configured");
     // 3. Create log level manager
     const logLevelManager = _createLogLevelManager(logger);
     // 3.5. Create module-bound loggers for each subsystem