@adhdev/daemon-core 1.0.28-rc.10 → 1.0.28-rc.12

package/src/providers/spec/fsm-evaluator.ts

@@ -22,6 +22,7 @@ import {
     type CliSpecV4, type FsmCondition, type FsmTransition,
     outgoingTransitions, stateById,
 } from './fsm-types.js';
+import { evaluateSignalLeaf, type SignalSnapshot } from './signal-envelope.js';
 
 export interface FsmClock {
     /** Wall-clock now (ms). Passed in so the evaluator stays pure. */
@@ -37,7 +38,7 @@ export interface FsmClock {
 
 /** Per-condition evaluation detail — the debugging payload. */
 export interface CondResult {
-    kind: 'regex' | 'changed' | 'elapsed' | 'stable' | 'all' | 'any' | 'not';
+    kind: 'regex' | 'changed' | 'elapsed' | 'stable' | 'signal' | 'all' | 'any' | 'not';
     result: boolean;
     detail: string;
     /** Remaining ms until a time-based condition would flip to true. 0 if
@@ -47,6 +48,12 @@ export interface CondResult {
      *  snapshot shows WHAT text the rule fired on — not just which regex. Never
      *  read by the FSM; purely for the Spec Debug Snapshot. */
     matchedText?: string;
+    /** TX-FSM Stage 0 (shadow): present only on `signal` leaves. `result` above
+     *  is ALWAYS true for a signal leaf (Stage-0 pass-through — the leaf never
+     *  gates a transition); this payload records what the leaf WOULD have
+     *  decided against the injected snapshot. shadowResult null = the signal
+     *  was unavailable/unknown (fail-open). */
+    signal?: { name: string; available: boolean; value: boolean | null; shadowResult: boolean | null };
     children?: CondResult[];
 }
 
@@ -66,6 +73,16 @@ export interface TransitionEval {
     /** Overall: would this transition fire? */
     fires: boolean;
     priority: number;
+    /**
+     * TX-FSM Stage 0 (shadow): present only when the guard contains at least
+     * one `signal` leaf. Records the verdict the transition WOULD have
+     * produced if signal leaves gated (condResult/fires), so the shadow log
+     * can compare it against the real PTY-only outcome. `unknown` = at least
+     * one signal leaf had no observation (fail-open); the shadow verdict is
+     * then informational, not a counterfactual proof. NEVER consumed by the
+     * driver for any transition decision — log/debug surface only.
+     */
+    shadow?: { condResult: boolean; fires: boolean; unknown: boolean };
 }
 
 export interface FsmEvaluation {
@@ -123,11 +140,69 @@ function isAny(c: FsmCondition): c is import('./fsm-types.js').FsmAnyCondition {
 function isNot(c: FsmCondition): c is import('./fsm-types.js').FsmNotCondition {
     return 'not' in c;
 }
+function isSignal(c: FsmCondition): c is import('./fsm-types.js').FsmSignalCondition {
+    return 'signal' in c;
+}
+
+/** True when the condition tree contains at least one `signal` leaf — only
+ *  those trees get a Stage-0 shadow verdict. */
+function containsSignal(c: FsmCondition): boolean {
+    if (isSignal(c)) return true;
+    if (isAll(c)) return c.all.some(containsSignal);
+    if (isAny(c)) return c.any.some(containsSignal);
+    if (isNot(c)) return containsSignal(c.not);
+    return false;
+}
+
+/**
+ * Fold an already-evaluated CondResult tree into the Stage-0 SHADOW verdict:
+ * signal leaves contribute their shadowResult (what they WOULD have decided),
+ * every other leaf contributes its real result, and all/any/not compose
+ * exactly as they did for the real verdict. Pure tree fold — no re-evaluation,
+ * so the shadow can never diverge from the real eval on PTY leaves.
+ *
+ * `unknown` tracks three-valued logic precisely: a definite child verdict
+ * decides the parent (false child ⇒ all is definitely false; true child ⇒ any
+ * is definitely true); only when no child decides does an unknown signal leaf
+ * make the parent unknown.
+ */
+function foldShadow(cond: CondResult): { value: boolean; unknown: boolean } {
+    if (cond.kind === 'signal') {
+        const s = cond.signal;
+        if (s && s.shadowResult !== null && s.shadowResult !== undefined) {
+            return { value: s.shadowResult, unknown: false };
+        }
+        return { value: true, unknown: true }; // fail-open placeholder
+    }
+    if (cond.kind === 'not' && cond.children?.length) {
+        const c = foldShadow(cond.children[0]);
+        return { value: !c.value, unknown: c.unknown };
+    }
+    if (cond.kind === 'all' && cond.children) {
+        const kids = cond.children.map(foldShadow);
+        if (kids.some(k => !k.unknown && !k.value)) return { value: false, unknown: false };
+        if (kids.some(k => k.unknown)) return { value: true, unknown: true };
+        return { value: true, unknown: false };
+    }
+    if (cond.kind === 'any' && cond.children) {
+        const kids = cond.children.map(foldShadow);
+        if (kids.some(k => !k.unknown && k.value)) return { value: true, unknown: false };
+        if (kids.some(k => k.unknown)) return { value: false, unknown: true };
+        return { value: false, unknown: false };
+    }
+    return { value: cond.result, unknown: false };
+}
 
 /**
  * Evaluate a single FSM condition into a {result, detail, remainingMs, children}.
  * Recurses through all/any/not; defers regex/changed to the shared evaluator;
  * handles elapsed_ms/stable_ms against the clock.
+ *
+ * `signalSnapshot` is the daemon-injected observation (TX-FSM Stage 0). A
+ * `signal` leaf evaluates to result=true UNCONDITIONALLY (Stage-0 pass-through
+ * — the leaf never gates a transition) and records its would-be verdict in
+ * CondResult.signal for the shadow fold. The pass-through, not the snapshot,
+ * is what the FSM sees.
  */
 function evalCond(
     cond: FsmCondition,
@@ -138,17 +213,18 @@ function evalCond(
     clock: FsmClock,
     legacyTrace: TraceEntry[],
     stateId: string,
+    signalSnapshot?: SignalSnapshot | null,
 ): CondResult {
     if (isAll(cond)) {
         const children = cond.all.map(c =>
-            evalCond(c, sections, fullScreen, cursor, prevLines, clock, legacyTrace, stateId));
+            evalCond(c, sections, fullScreen, cursor, prevLines, clock, legacyTrace, stateId, signalSnapshot));
         const result = children.every(c => c.result);
         const remainingMs = result ? 0 : Math.max(0, ...children.filter(c => !c.result).map(c => c.remainingMs ?? 0));
         return { kind: 'all', result, detail: `all(${children.length})`, remainingMs, children };
     }
     if (isAny(cond)) {
         const children = cond.any.map(c =>
-            evalCond(c, sections, fullScreen, cursor, prevLines, clock, legacyTrace, stateId));
+            evalCond(c, sections, fullScreen, cursor, prevLines, clock, legacyTrace, stateId, signalSnapshot));
         const result = children.some(c => c.result);
         // remaining = the soonest child that could flip true
         const pending = children.filter(c => !c.result).map(c => c.remainingMs ?? Infinity);
@@ -156,9 +232,26 @@ function evalCond(
         return { kind: 'any', result, detail: `any(${children.length})`, remainingMs: Number.isFinite(remainingMs) ? remainingMs : 0, children };
     }
     if (isNot(cond)) {
-        const child = evalCond(cond.not, sections, fullScreen, cursor, prevLines, clock, legacyTrace, stateId);
+        const child = evalCond(cond.not, sections, fullScreen, cursor, prevLines, clock, legacyTrace, stateId, signalSnapshot);
         return { kind: 'not', result: !child.result, detail: `not`, remainingMs: 0, children: [child] };
     }
+    if (isSignal(cond)) {
+        const leaf = evaluateSignalLeaf(cond, signalSnapshot);
+        // STAGE-0 PASS-THROUGH: result is always true so the leaf can never
+        // change `fires` — not even when a spec author adds a signal condition
+        // today. The shadow fold (foldShadow) reads `signal.shadowResult`.
+        return {
+            kind: 'signal',
+            result: true,
+            detail: `${leaf.detail} (stage0 shadow — pass-through)`,
+            signal: {
+                name: cond.signal,
+                available: !!signalSnapshot?.available,
+                value: leaf.value,
+                shadowResult: leaf.shadowResult,
+            },
+        };
+    }
     if (isElapsed(cond)) {
         const age = clock.now - clock.stateEnteredAt;
         const result = age >= cond.elapsed_ms;
@@ -221,6 +314,7 @@ export function evaluateFsm(
     cursor: { row: number; col: number } | undefined,
     prevLines: string[] | undefined,
     clock: FsmClock,
+    signalSnapshot?: SignalSnapshot | null,
 ): FsmEvaluation {
     const legacyTrace: TraceEntry[] = [];
     const lines = screenText.split('\n').map(l => l.endsWith('\r') ? l.slice(0, -1) : l);
@@ -240,7 +334,7 @@ export function evaluateFsm(
         let cond: CondResult | undefined;
         let condResult = true;
         if (t.when) {
-            cond = evalCond(t.when, sections, cleanScreen, cursor, prevLines, clock, legacyTrace, `${currentStateId}→${t.to}`);
+            cond = evalCond(t.when, sections, cleanScreen, cursor, prevLines, clock, legacyTrace, `${currentStateId}→${t.to}`, signalSnapshot);
             condResult = cond.result;
         }
 
@@ -256,6 +350,17 @@ export function evaluateFsm(
             fires,
             priority: t.priority ?? 0,
         };
+        // TX-FSM Stage 0 (shadow): record the counterfactual verdict for any
+        // guard containing a signal leaf. Read-only — `fires` above is already
+        // fixed by the pass-through rule before this runs.
+        if (t.when && containsSignal(t.when) && cond) {
+            const folded = foldShadow(cond);
+            te.shadow = {
+                condResult: folded.value,
+                fires: holdSatisfied && folded.value,
+                unknown: folded.unknown,
+            };
+        }
         transitions.push(te);
         if (fires && !fired) fired = te;
     }

package/src/providers/spec/fsm-loader.ts

@@ -113,6 +113,13 @@ function validateCondition(c: FsmCondition, sectionIds: Set<string>, path: strin
         return errs;
     }
     if ('cursor_above' in w && 'changed' in w) return errs;
+    if ('signal' in w) {
+        // TX-FSM Stage 0 (shadow) leaf — validated so a spec can declare it
+        // today (evaluation is shadow-only; see fsm-evaluator).
+        if (typeof w.signal !== 'string' || !w.signal.trim()) errs.push(`${path}.signal must be a non-empty string`);
+        if (w.equals !== undefined && typeof w.equals !== 'boolean') errs.push(`${path}.equals must be a boolean`);
+        return errs;
+    }
     if ('elapsed_ms' in w) { if (typeof w.elapsed_ms !== 'number') errs.push(`${path}.elapsed_ms must be a number`); return errs; }
     if ('stable_ms' in w) {
         if (typeof w.stable_ms !== 'number') errs.push(`${path}.stable_ms must be a number`);

package/src/providers/spec/fsm-types.ts

@@ -95,11 +95,31 @@ export interface FsmNotCondition {
     not: FsmCondition;
 }
 
+/**
+ * TX-FSM Stage 0 (shadow) — a daemon-signal leaf. References a NORMALIZED
+ * signal name from the SignalSnapshot envelope (never a provider name), so a
+ * spec can combine transcript evidence with PTY conditions via all/any/not:
+ *
+ *   { all: [ { matches: "…" }, { signal: "final_assistant_present" } ] }
+ *
+ * STAGE-0 SEMANTICS: evaluated for the shadow log only. The leaf NEVER gates
+ * a transition — the evaluator treats it as pass-through for the real verdict
+ * and records what it WOULD have decided (TransitionEval.shadow). A missing
+ * or unavailable signal fails open. Promotion to a real gate is Stage 1+.
+ */
+export interface FsmSignalCondition {
+    /** Normalized signal name (see SIGNAL_NAMES in signal-envelope.ts). */
+    signal: string;
+    /** Expected value; default true. */
+    equals?: boolean;
+}
+
 export type FsmCondition =
     | RegexCondition
     | ChangedCondition
     | ElapsedCondition
     | StableCondition
+    | FsmSignalCondition
     | FsmAllCondition
     | FsmAnyCondition
     | FsmNotCondition;

package/src/providers/spec/signal-envelope.ts

@@ -0,0 +1,136 @@
+/**
+ * TX-FSM Stage 0 (shadow) — the `signal` capability envelope.
+ *
+ * Stage 0 of the transcript+PTY dual-source redesign: the daemon collects
+ * native-transcript signals, normalizes them into this envelope, and injects
+ * the snapshot into the FsmDriver as a pure OBSERVATION. The FSM evaluates
+ * `signal` conditions against it and records what the verdict WOULD have been
+ * (shadow log) — but a signal condition NEVER gates a transition in Stage 0
+ * (pass-through, see fsm-evaluator.ts). Behavior change is exactly zero.
+ *
+ * Boundary contract:
+ *  - This module is ENGINE-side: it defines the envelope + leaf evaluation and
+ *    knows NOTHING about providers, file discovery, or parsing.
+ *  - The daemon-side TranscriptSignalSource (providers/transcript-signal-source.ts)
+ *    owns collection/normalization and is the only producer.
+ *  - Approval is explicitly OUT of scope (deferred to Stage 4): no provider
+ *    records its approval lifecycle in the native transcript, and an unfinished
+ *    tool call cannot distinguish running/approval-pending/result-delayed/crash,
+ *    so no approval signal exists in this envelope. PTY regex stays the sole
+ *    approval authority.
+ *
+ * Fail-open contract: when no snapshot is available (non-native-source class,
+ * unresolved transcript, read error), every signal is null and every `signal`
+ * condition fails OPEN — a missing signal must never wedge a session.
+ */
+'use strict';
+
+import type { TranscriptClass, CompletionTiming } from '../transcript-evidence.js';
+
+export const SIGNAL_SNAPSHOT_KIND = 'adhdev:fsm/signal-snapshot@0' as const;
+
+/** The normalized signal vocabulary. Stage 0 keeps this deliberately small —
+ *  every name must be derivable from the FLATTENED native-transcript pipeline
+ *  (which drops tool_use/tool_result correlation ids — that raw-JSONL read is
+ *  Stage 4 territory and must NOT be added here). */
+export type SignalName =
+    | 'final_assistant_present'
+    | 'in_turn_progress'
+    | 'transcript_growing';
+
+export const SIGNAL_NAMES: readonly SignalName[] = [
+    'final_assistant_present',
+    'in_turn_progress',
+    'transcript_growing',
+];
+
+export type SignalUnavailableReason = 'no_native_source' | 'unresolved' | 'error';
+
+/** The normalized, provider-agnostic observation the daemon hands the FSM. */
+export interface SignalSnapshot {
+    kind: typeof SIGNAL_SNAPSHOT_KIND;
+    /** Wall-clock time the underlying transcript read happened (ms). */
+    sampledAt: number;
+    /** False ⇒ every signal is null and conditions fail open. */
+    available: boolean;
+    unavailableReason?: SignalUnavailableReason;
+    /** The authority profile class/timing this snapshot was produced under
+     *  (via resolveTranscriptAuthorityProfile — never raw predicates). */
+    profile?: { class: TranscriptClass; timing: CompletionTiming };
+    /** Normalized signals; null = unknown (fail-open). */
+    signals: Record<SignalName, boolean | null>;
+    /** Raw sampling context for the shadow log / Stage 1-3 analysis. */
+    detail: {
+        msgCount: number;
+        sourceMtimeMs: number;
+        /** now - sourceMtimeMs; null when the mtime is unknown (0). */
+        ageMs: number | null;
+    };
+}
+
+/** The fail-open snapshot: no usable observation, every signal null. */
+export function unavailableSignalSnapshot(
+    now: number,
+    reason: SignalUnavailableReason,
+    profile?: { class: TranscriptClass; timing: CompletionTiming },
+): SignalSnapshot {
+    return {
+        kind: SIGNAL_SNAPSHOT_KIND,
+        sampledAt: now,
+        available: false,
+        unavailableReason: reason,
+        ...(profile ? { profile } : {}),
+        signals: { final_assistant_present: null, in_turn_progress: null, transcript_growing: null },
+        detail: { msgCount: 0, sourceMtimeMs: 0, ageMs: null },
+    };
+}
+
+/** The spec's `signal` leaf: `{ signal: 'transcript_growing', equals?: boolean }`. */
+export interface SignalLeaf {
+    signal: string;
+    equals?: boolean;
+}
+
+export interface SignalLeafEval {
+    /** The normalized signal value read from the snapshot; null = unknown. */
+    value: boolean | null;
+    /** What the leaf WOULD evaluate to if signals gated transitions; null =
+     *  unknown (no snapshot / signal missing → fail-open). */
+    shadowResult: boolean | null;
+    /** Human-readable shadow-log fragment. */
+    detail: string;
+}
+
+/**
+ * Evaluate one `signal` leaf against the injected snapshot. This computes the
+ * SHADOW verdict only — the caller (fsm-evaluator) owns the Stage-0
+ * pass-through rule that keeps the real result true regardless of what this
+ * returns.
+ */
+export function evaluateSignalLeaf(cond: SignalLeaf, snapshot: SignalSnapshot | null | undefined): SignalLeafEval {
+    const expected = cond.equals ?? true;
+    if (!snapshot || !snapshot.available) {
+        const why = !snapshot ? 'no snapshot' : `unavailable(${snapshot.unavailableReason ?? 'unknown'})`;
+        return {
+            value: null,
+            shadowResult: null,
+            detail: `signal ${cond.signal} ${why} → fail-open`,
+        };
+    }
+    const raw = Object.prototype.hasOwnProperty.call(snapshot.signals, cond.signal)
+        ? snapshot.signals[cond.signal as SignalName]
+        : null;
+    if (raw === null || raw === undefined) {
+        return {
+            value: null,
+            shadowResult: null,
+            detail: `signal ${cond.signal} unknown → fail-open`,
+        };
+    }
+    const shadowResult = raw === expected;
+    return {
+        value: raw,
+        shadowResult,
+        detail: `signal ${cond.signal}=${raw} expected=${expected} → ${shadowResult}`,
+    };
+}

package/src/providers/transcript-signal-source.ts

@@ -0,0 +1,179 @@
+/**
+ * TranscriptSignalSource — TX-FSM transcript signal normalizer, daemon side.
+ *
+ * Owns the collection/normalization half of the dual-source redesign: given
+ * the daemon's EXISTING native-transcript reads (file discovery + session pin
+ * + parsing all stay in CliProviderInstance.readExternalCompletionMessages,
+ * which resolves providerSessionId / persisted pins / floor-claims), this
+ * source normalizes each read into the provider-agnostic SignalSnapshot
+ * envelope (spec/signal-envelope.ts).
+ *
+ * Consumers:
+ *  - Stage 0 (shadow): the snapshot is injected into the FsmDriver as a pure
+ *    observation; `signal` conditions stay pass-through there (fsm-evaluator).
+ *  - Stage 1 (delegation): the instance's OWN stall/growth-hold judgments
+ *    (checkMeshWorkerStall's transcript-advancing axis, the TRANSCRIPT-
+ *    GROWTH-HOLD, and tryReconcileTranscriptCompletionForStall — the FIX 3
+ *    probe) consume the SAME normalized snapshot instead of running private
+ *    transcript scans. The FSM-side consumption remains shadow/pass-through.
+ *
+ * Hard contracts:
+ *  - ZERO added I/O. update() is fed by transcript reads the daemon already
+ *    performs (completion probe / stall sampling); it never opens a file
+ *    itself. getState() keeps its zero-native-read invariant untouched.
+ *  - Classification goes through resolveTranscriptAuthorityProfile ONLY (the
+ *    P0 choke point) — never raw isNativeSourceCanonicalHistory /
+ *    isPurePtyTranscriptProvider calls, and never a provider-name branch.
+ *  - Fail-open: a non-native-source class, an unresolved transcript, or a
+ *    read error yields an unavailable snapshot — consumers treat every signal
+ *    as null and keep their pre-delegation fallbacks; a missing signal must
+ *    never wedge a session or fabricate a completion.
+ *  - No approval signal (Stage 4 scope — see signal-envelope.ts).
+ */
+'use strict';
+
+import { LOG } from '../logging/logger.js';
+import type { TranscriptAuthorityProfile } from './transcript-evidence.js';
+import {
+    SIGNAL_SNAPSHOT_KIND,
+    unavailableSignalSnapshot,
+    type SignalSnapshot,
+} from './spec/signal-envelope.js';
+
+/** One daemon transcript read, normalized for the source. */
+export interface TranscriptSignalSample {
+    /** Parsed native-transcript messages, or null when the read failed to
+     *  resolve a source this time. */
+    messages: unknown[] | null;
+    /** The probe metadata the read refreshed (sourcePath/mtime/msgCount), or
+     *  null when no source is bound. A null sourceMtimeMs is treated as "no
+     *  freshness evidence" (same contract as the growth-hold path). */
+    probe: { msgCount: number; sourceMtimeMs: number | null; sourcePath?: string | null } | null;
+    /** True when the read threw — logged distinctly from a clean miss. */
+    error?: boolean;
+}
+
+export interface TranscriptSignalSourceOpts {
+    /** Log tag (provider type / session label) — never used for branching. */
+    label: string;
+    /** The P0 choke-point profile for this provider. */
+    profile: TranscriptAuthorityProfile;
+    /** Turn-boundary clock (adapter.currentTurnStartedAt) for turn-scoped
+     *  final-assistant detection; may yield undefined pre-turn. */
+    turnStartedAt?: () => number | undefined;
+    /** In-turn final-assistant predicate over the flattened messages — the
+     *  instance passes its existing completionHasFinalAssistantMessage so the
+     *  signal reuses the exact completion machinery instead of duplicating it. */
+    finalAssistantPresent: (messages: unknown[], turnStartedAt?: number) => boolean;
+    /** Freshness window (ms) for transcript_growing. The caller passes the
+     *  completion pipeline's MISSING_ASSISTANT_TRANSCRIPT_GROWTH_QUIET_MS so
+     *  the shadow signal is comparable to the existing growth-hold judgment. */
+    growthQuietMs: number;
+}
+
+export class TranscriptSignalSource {
+    /** msgCount seen at the previous update — drives in_turn_progress. */
+    private prevMsgCount = -1;
+    /** Fingerprint of the last LOGGED snapshot, so the shadow log fires on
+     *  change only (a quiet session must not spam one line per read). */
+    private lastLoggedFingerprint = '';
+
+    constructor(private readonly opts: TranscriptSignalSourceOpts) {}
+
+    /**
+     * Normalize one daemon read into a SignalSnapshot and emit the Stage-0
+     * shadow log when the observation changed. Pure w.r.t. the outside world:
+     * the only side effect is the (change-gated) log line. Returns the
+     * snapshot the caller should inject into the FSM driver.
+     */
+    update(sample: TranscriptSignalSample, now: number = Date.now()): SignalSnapshot {
+        const snapshot = this.buildSnapshot(sample, now);
+        this.logOnChange(snapshot);
+        return snapshot;
+    }
+
+    /** Pure normalization — separated from update() so tests can assert the
+     *  envelope without touching the log path. */
+    buildSnapshot(sample: TranscriptSignalSample, now: number): SignalSnapshot {
+        const profileRef = { class: this.opts.profile.class, timing: this.opts.profile.timing };
+
+        // Choke-point classification: only native-source providers have an
+        // on-disk transcript to signal from. daemon-owned / pure-pty classes
+        // fail open — no signal is ever fabricated for them.
+        if (this.opts.profile.class !== 'native-source') {
+            return unavailableSignalSnapshot(now, 'no_native_source', profileRef);
+        }
+        if (sample.error) {
+            return unavailableSignalSnapshot(now, 'error', profileRef);
+        }
+        const probe = sample.probe;
+        if (!probe || !Array.isArray(sample.messages)) {
+            return unavailableSignalSnapshot(now, 'unresolved', profileRef);
+        }
+
+        const msgCount = typeof probe.msgCount === 'number' && Number.isFinite(probe.msgCount)
+            ? probe.msgCount
+            : sample.messages.length;
+        const sourceMtimeMs = typeof probe.sourceMtimeMs === 'number' && Number.isFinite(probe.sourceMtimeMs)
+            ? probe.sourceMtimeMs
+            : 0;
+        // mtime 0 = "no freshness evidence" — the growth-hold test lock treats
+        // it as unprovable, and so do we: transcript_growing stays null rather
+        // than guessing from a missing clock.
+        const ageMs = sourceMtimeMs > 0 ? Math.max(0, now - sourceMtimeMs) : null;
+
+        let turnStartedAt: number | undefined;
+        try { turnStartedAt = this.opts.turnStartedAt?.(); } catch { turnStartedAt = undefined; }
+
+        let finalAssistant: boolean | null = null;
+        try {
+            finalAssistant = this.opts.finalAssistantPresent(sample.messages, turnStartedAt);
+        } catch { finalAssistant = null; /* fail-open: never let a parse quirk fabricate a signal */ }
+
+        // in_turn_progress: the transcript ADVANCED since the previous sample
+        // (msgCount grew) or is still fresh. Conservative: the first sample
+        // reports progress only on freshness, never on a count jump from -1.
+        const countAdvanced = this.prevMsgCount >= 0 && msgCount > this.prevMsgCount;
+        const fresh = ageMs !== null && ageMs < this.opts.growthQuietMs;
+        const inTurnProgress = countAdvanced || fresh;
+        const transcriptGrowing = ageMs === null ? null : fresh;
+        this.prevMsgCount = msgCount;
+
+        return {
+            kind: SIGNAL_SNAPSHOT_KIND,
+            sampledAt: now,
+            available: true,
+            profile: profileRef,
+            signals: {
+                final_assistant_present: finalAssistant,
+                in_turn_progress: inTurnProgress,
+                transcript_growing: transcriptGrowing,
+            },
+            detail: { msgCount, sourceMtimeMs, ageMs },
+        };
+    }
+
+    /** Stage-0 shadow log: emit one line when the normalized observation
+     *  CHANGES. This log is the Stage 1-3 judgment input ("which signals were
+     *  actually observable, and when"), so it carries the full signal set —
+     *  but only on change, so a steady-state session stays quiet. */
+    private logOnChange(snapshot: SignalSnapshot): void {
+        const s = snapshot.signals;
+        const fingerprint = snapshot.available
+            ? `1|fa=${s.final_assistant_present}|tp=${s.in_turn_progress}|tg=${s.transcript_growing}|n=${snapshot.detail.msgCount}`
+            : `0|${snapshot.unavailableReason ?? 'unknown'}`;
+        if (fingerprint === this.lastLoggedFingerprint) return;
+        this.lastLoggedFingerprint = fingerprint;
+        const age = snapshot.detail.ageMs === null ? 'n/a' : `${snapshot.detail.ageMs}ms`;
+        LOG.info(
+            'TranscriptSignalSource',
+            `[${this.opts.label}] [shadow] signals available=${snapshot.available}`
+            + (snapshot.available
+                ? ` final_assistant_present=${s.final_assistant_present}`
+                + ` in_turn_progress=${s.in_turn_progress}`
+                + ` transcript_growing=${s.transcript_growing}`
+                + ` msgCount=${snapshot.detail.msgCount} age=${age}`
+                : ` reason=${snapshot.unavailableReason ?? 'unknown'}`),
+        );
+    }
+}