@adhdev/daemon-core 0.9.82-rc.449 → 0.9.82-rc.450

package/dist/providers/spec/fsm-driver.d.ts

@@ -176,8 +176,10 @@ export declare class FsmDriver implements ISpecDriver {
     private stateEnteredAt;
     private startedAtMs;
     private prevScreenLines;
-    /** Per cursor_above region (key: cursor_above, -1 = whole screen) → last
-     *  time that region's content changed. Drives stable_ms conditions. */
+    /** Per stable region → last time that region's content changed. Drives
+     *  stable_ms conditions. Key = stableRegionKey(cond): numeric cursor_above
+     *  (−1 = whole screen), or a `section:<id>` / `<region>#ignore:<pat>` string
+     *  when the clause scopes to a section or declares an ignore_lines filter. */
     private regionLastChangedAt;
     /** Timer that re-runs evaluate() when a time-condition would flip true
      *  with no PTY frame to trigger it. */
@@ -307,15 +309,25 @@ export declare class FsmDriver implements ISpecDriver {
     private deriveModal;
     private deriveTitle;
     private deriveControls;
-    /** Track which cursor_above regions changed since the previous frame so
-     *  stable_ms conditions can measure quiet time. We record every region
-     *  size referenced by a stable_ms condition in the spec, plus the whole
-     *  screen (-1). */
+    /** Track which stable regions changed since the previous frame so
+     *  stable_ms conditions can measure quiet time. We record every distinct
+     *  stable region referenced in the current state (numeric cursor_above /
+     *  whole-screen -1, and named `section:<id>` regions) plus, for each, the
+     *  optional `ignore_lines` filter that folds into its key.
+     *
+     *  `ignore_lines` is the content-aware fix for the busy→idle wedge: lines
+     *  matching it are stripped from BOTH frames before the comparison, so a
+     *  benign residual ticker (bare token counter / elapsed timer that repaints
+     *  every frame post-generation) no longer resets the clock — while an active
+     *  spinner line, which does NOT match the benign pattern, still does (the
+     *  FALSEIDLE2 / FALSEBUSY-B whole-screen invariant is preserved). */
     private trackRegionChanges;
-    /** All cursor_above region sizes referenced by stable_ms conditions in the
-     *  current state's outgoing transitions, plus whole-screen. Cached lazily
-     *  per spec load would be nicer but the set is tiny. */
-    private stableRegionSizes;
+    /** Every distinct stable-region descriptor referenced by stable_ms
+     *  conditions in the current state's outgoing transitions, plus the plain
+     *  whole-screen key (-1) that other machinery (stall watchdog) reads.
+     *  De-duplicated by key. Cached lazily per spec load would be nicer but the
+     *  set is tiny. */
+    private stableRegionDescriptors;
     /** Schedule a re-evaluation for the soonest pending time-condition on any
      *  outgoing transition (elapsed_ms / stable_ms / min_hold_ms). Without
      *  this, a state whose only exit is time-based would never leave once the
@@ -425,4 +437,8 @@ export declare class FsmDriver implements ISpecDriver {
     private specTag;
     private emit;
 }
+/** Drop lines matching `ignoreRe` so a per-frame repaint confined to them does
+ *  not register as a region change. No filter → lines returned unchanged.
+ *  Exported for unit tests of the stable_ms `ignore_lines` change-detection. */
+export declare function filterIgnoredLines(lines: string[], ignoreRe: RegExp | undefined): string[];
 export {};

package/dist/providers/spec/fsm-evaluator.d.ts

@@ -6,10 +6,11 @@ export interface FsmClock {
     now: number;
     /** When the current state was entered (ms). */
     stateEnteredAt: number;
-    /** Last-changed timestamp per cursor_above region. Key = cursor_above
-     *  value (0 / undefined → whole-screen, keyed as -1). Missing key means
+    /** Last-changed timestamp per stable region. Numeric key = cursor_above
+     *  value (0 / undefined → whole-screen, keyed as -1). String key =
+     *  `section:<id>` for a section-scoped stable region. Missing key means
      *  "never observed changing" → treated as stable since stateEnteredAt. */
-    regionLastChangedAt: Map<number, number>;
+    regionLastChangedAt: Map<number | string, number>;
 }
 /** Per-condition evaluation detail — the debugging payload. */
 export interface CondResult {
@@ -54,6 +55,22 @@ export interface FsmEvaluation {
     /** v3-compatible trace lines for the legacy inspector. */
     trace: TraceEntry[];
 }
+/** The `regionLastChangedAt` key for a stable condition. The key must capture
+ *  everything that makes two stable clauses watch a DIFFERENT change signal:
+ *  the geometric region (`section` wins over `cursor_above`, else whole-screen)
+ *  AND the `ignore_lines` filter (two clauses on the same region but different
+ *  ignore patterns see different "did it change" answers). Kept in one place so
+ *  the driver (which populates the map) and the evaluator (which reads it)
+ *  agree on the key.
+ *
+ *  Bare whole-screen with no ignore filter keeps its historical numeric key -1
+ *  so existing callers/tests that seed `regionLastChangedAt` with [-1, ...]
+ *  keep working unchanged. */
+export declare function stableRegionKey(cond: {
+    section?: string;
+    cursor_above?: number;
+    ignore_lines?: string;
+}): number | string;
 /**
  * Evaluate the FSM: given the current state id and screen, return every
  * outgoing transition annotated with why it fires/doesn't, plus the one that

package/dist/providers/spec/fsm-types.d.ts

@@ -3,12 +3,40 @@ import type { RegexCondition, ChangedCondition, Control, NotificationRule, Deleg
 export interface ElapsedCondition {
     elapsed_ms: number;
 }
-/** True once the region `cursor_above` lines above the cursor has been
- *  unchanged for `ms`. A stability gate — the inverse of a busy signal. */
+/** True once a region has been unchanged for `ms`. A stability gate — the
+ *  inverse of a busy signal.
+ *
+ *  Region selection (precedence order):
+ *   - `section`     : a named section from the spec's `sections{}` (e.g. "body").
+ *                     Only lines inside that section are watched for change.
+ *   - `cursor_above`: the N lines directly above the cursor.
+ *   - neither       : the whole screen (default).
+ *
+ *  `ignore_lines` is orthogonal to region choice: lines matching it are
+ *  stripped from BOTH frames before the change comparison, so a per-frame
+ *  animation on those lines cannot reset the stable clock. This is the
+ *  content-aware escape hatch for the busy→idle wedge — a benign residual
+ *  ticker (a bare token counter / elapsed timer that repaints every frame
+ *  after generation has finished) is filtered out, so a genuinely settled
+ *  transcript can reach `stable_ms`. It is deliberately CONTENT-based, not
+ *  geometric: an ACTIVE spinner line (glyph + esc/token trailer) does NOT
+ *  match the benign pattern, so a real below-prompt spinner tick still resets
+ *  the clock and holds busy (the FALSEIDLE2 / FALSEBUSY-B invariant). */
 export interface StableCondition {
     stable_ms: number;
-    /** Lines above the cursor that must be stable. Default: whole screen. */
+    /** Named section (from `sections{}`) that must be stable. Takes precedence
+     *  over `cursor_above`. */
+    section?: string;
+    /** Lines above the cursor that must be stable. Default: whole screen.
+     *  Ignored when `section` is set. */
     cursor_above?: number;
+    /** Regex (line-tested with `m` flag). Lines matching it are removed from
+     *  both the current and previous frame before deciding whether the region
+     *  changed — a per-frame repaint confined to these lines does NOT reset the
+     *  stability clock. Use for benign residual animation (token counter /
+     *  elapsed timer). Must NOT match an active-spinner line, or a real spinner
+     *  tick would be masked. */
+    ignore_lines?: string;
 }
 export interface FsmAllCondition {
     all: FsmCondition[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhdev/daemon-core",
-  "version": "0.9.82-rc.449",
+  "version": "0.9.82-rc.450",
   "description": "ADHDev daemon core — CDP, IDE detection, providers, command execution",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -46,7 +46,7 @@
   "author": "vilmire",
   "license": "AGPL-3.0-or-later",
   "dependencies": {
-    "@adhdev/mesh-shared": "0.9.82-rc.449",
+    "@adhdev/mesh-shared": "0.9.82-rc.450",
     "@adhdev/session-host-core": "*",
     "@agentclientprotocol/sdk": "^0.16.1",
     "ajv": "^8.20.0",

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

@@ -29,7 +29,7 @@ import {
     resolveSections, sectionText, extractTitle, extractButtonsFromRule,
     type ResolvedSection, type TraceEntry,
 } from './evaluator.js';
-import { evaluateFsm, type FsmClock, type TransitionEval, type FsmEvaluation } from './fsm-evaluator.js';
+import { evaluateFsm, stableRegionKey, type FsmClock, type TransitionEval, type FsmEvaluation } from './fsm-evaluator.js';
 import {
     type CliSpecV4, type FsmState, type FsmTransition,
     initialState, stateById, statusForState, modalKindForState, outgoingTransitions,
@@ -295,9 +295,11 @@ export class FsmDriver implements ISpecDriver {
     // ── Clock bookkeeping for time conditions.
     private startedAtMs = 0;
     private prevScreenLines: string[] = [];
-    /** Per cursor_above region (key: cursor_above, -1 = whole screen) → last
-     *  time that region's content changed. Drives stable_ms conditions. */
-    private regionLastChangedAt = new Map<number, number>();
+    /** Per stable region → last time that region's content changed. Drives
+     *  stable_ms conditions. Key = stableRegionKey(cond): numeric cursor_above
+     *  (−1 = whole screen), or a `section:<id>` / `<region>#ignore:<pat>` string
+     *  when the clause scopes to a section or declares an ignore_lines filter. */
+    private regionLastChangedAt = new Map<number | string, number>();
     /** Timer that re-runs evaluate() when a time-condition would flip true
      *  with no PTY frame to trigger it. */
     private wakeTimer: ReturnType<typeof setTimeout> | null = null;
@@ -801,36 +803,57 @@ export class FsmDriver implements ISpecDriver {
         return out;
     }
 
-    /** Track which cursor_above regions changed since the previous frame so
-     *  stable_ms conditions can measure quiet time. We record every region
-     *  size referenced by a stable_ms condition in the spec, plus the whole
-     *  screen (-1). */
+    /** Track which stable regions changed since the previous frame so
+     *  stable_ms conditions can measure quiet time. We record every distinct
+     *  stable region referenced in the current state (numeric cursor_above /
+     *  whole-screen -1, and named `section:<id>` regions) plus, for each, the
+     *  optional `ignore_lines` filter that folds into its key.
+     *
+     *  `ignore_lines` is the content-aware fix for the busy→idle wedge: lines
+     *  matching it are stripped from BOTH frames before the comparison, so a
+     *  benign residual ticker (bare token counter / elapsed timer that repaints
+     *  every frame post-generation) no longer resets the clock — while an active
+     *  spinner line, which does NOT match the benign pattern, still does (the
+     *  FALSEIDLE2 / FALSEBUSY-B whole-screen invariant is preserved). */
     private trackRegionChanges(currentLines: string[], cursor: { row: number; col: number }, now: number): void {
         if (this.prevScreenLines.length === 0) return;
-        const sizes = this.stableRegionSizes();
-        for (const size of sizes) {
-            let cur: string; let prev: string;
-            if (size < 0) {
-                cur = currentLines.join('\n');
-                prev = this.prevScreenLines.join('\n');
+        const descs = this.stableRegionDescriptors();
+        // Section ranges depend on screen content, so resolve per-frame for both
+        // frames — but only when some tracked region is actually section-scoped.
+        const needsSections = descs.some(d => !!d.section);
+        const curSections = needsSections ? resolveSections(this.spec.sections ?? {}, currentLines) : [];
+        const prevSections = needsSections ? resolveSections(this.spec.sections ?? {}, this.prevScreenLines) : [];
+        for (const d of descs) {
+            let curLines: string[]; let prevLines: string[];
+            if (d.section) {
+                curLines = sliceSectionLines(currentLines, curSections, d.section);
+                prevLines = sliceSectionLines(this.prevScreenLines, prevSections, d.section);
+            } else if (!d.cursor_above || d.cursor_above <= 0) {
+                curLines = currentLines;
+                prevLines = this.prevScreenLines;
             } else {
-                const start = Math.max(0, cursor.row - size);
-                cur = currentLines.slice(start, cursor.row).join('\n');
-                prev = this.prevScreenLines.slice(start, cursor.row).join('\n');
+                const start = Math.max(0, cursor.row - d.cursor_above);
+                curLines = currentLines.slice(start, cursor.row);
+                prevLines = this.prevScreenLines.slice(start, cursor.row);
             }
-            if (cur !== prev) this.regionLastChangedAt.set(size, now);
+            const cur = filterIgnoredLines(curLines, d.ignoreRe).join('\n');
+            const prev = filterIgnoredLines(prevLines, d.ignoreRe).join('\n');
+            if (cur !== prev) this.regionLastChangedAt.set(d.key, now);
         }
     }
 
-    /** All cursor_above region sizes referenced by stable_ms conditions in the
-     *  current state's outgoing transitions, plus whole-screen. Cached lazily
-     *  per spec load would be nicer but the set is tiny. */
-    private stableRegionSizes(): Set<number> {
-        const sizes = new Set<number>([-1]);
+    /** Every distinct stable-region descriptor referenced by stable_ms
+     *  conditions in the current state's outgoing transitions, plus the plain
+     *  whole-screen key (-1) that other machinery (stall watchdog) reads.
+     *  De-duplicated by key. Cached lazily per spec load would be nicer but the
+     *  set is tiny. */
+    private stableRegionDescriptors(): StableRegionDescriptor[] {
+        const byKey = new Map<number | string, StableRegionDescriptor>();
+        byKey.set(-1, { key: -1 });
         for (const t of outgoingTransitions(this.spec, this.currentStateId)) {
-            collectStableSizes(t.when, sizes);
+            collectStableDescriptors(t.when, byKey);
         }
-        return sizes;
+        return [...byKey.values()];
     }
 
     /** Schedule a re-evaluation for the soonest pending time-condition on any
@@ -1409,11 +1432,50 @@ function findStable(c: import('./fsm-evaluator.js').CondResult): { totalMs: numb
     return null;
 }
 
-function collectStableSizes(when: FsmTransition['when'], sizes: Set<number>): void {
+/** Resolved description of one stable region the driver must track: its map
+ *  key, the geometry (section / cursor_above / whole-screen), and a compiled
+ *  `ignore_lines` matcher. */
+interface StableRegionDescriptor {
+    key: number | string;
+    section?: string;
+    cursor_above?: number;
+    ignoreRe?: RegExp;
+}
+
+function collectStableDescriptors(when: FsmTransition['when'], byKey: Map<number | string, StableRegionDescriptor>): void {
     if (!when) return;
     const w = when as any;
-    if ('stable_ms' in w) { sizes.add(w.cursor_above && w.cursor_above > 0 ? w.cursor_above : -1); return; }
-    if ('all' in w) { for (const c of w.all) collectStableSizes(c, sizes); return; }
-    if ('any' in w) { for (const c of w.any) collectStableSizes(c, sizes); return; }
-    if ('not' in w) { collectStableSizes(w.not, sizes); return; }
+    if ('stable_ms' in w) {
+        const key = stableRegionKey(w);
+        if (!byKey.has(key)) {
+            let ignoreRe: RegExp | undefined;
+            if (w.ignore_lines) {
+                // Compile once here; a bad pattern is validated at load time, so
+                // this is best-effort and simply skips the filter if it throws.
+                try { ignoreRe = new RegExp(w.ignore_lines, 'm'); } catch { /* validated at load */ }
+            }
+            byKey.set(key, { key, section: w.section, cursor_above: w.cursor_above, ignoreRe });
+        }
+        return;
+    }
+    if ('all' in w) { for (const c of w.all) collectStableDescriptors(c, byKey); return; }
+    if ('any' in w) { for (const c of w.any) collectStableDescriptors(c, byKey); return; }
+    if ('not' in w) { collectStableDescriptors(w.not, byKey); return; }
+}
+
+/** Lines of section `id` on the given frame, or [] if that section is absent
+ *  this frame. Used to compute per-frame change of a section-scoped stable
+ *  region. */
+function sliceSectionLines(lines: string[], sections: ResolvedSection[], id: string): string[] {
+    const sec = sections.find(s => s.id === id);
+    if (!sec) return [];
+    return lines.slice(sec.fromLine, sec.toLine);
+}
+
+/** Drop lines matching `ignoreRe` so a per-frame repaint confined to them does
+ *  not register as a region change. No filter → lines returned unchanged.
+ *  Exported for unit tests of the stable_ms `ignore_lines` change-detection. */
+export function filterIgnoredLines(lines: string[], ignoreRe: RegExp | undefined): string[] {
+    if (!ignoreRe) return lines;
+    return lines.filter(l => !ignoreRe.test(l));
 }

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

@@ -28,10 +28,11 @@ export interface FsmClock {
     now: number;
     /** When the current state was entered (ms). */
     stateEnteredAt: number;
-    /** Last-changed timestamp per cursor_above region. Key = cursor_above
-     *  value (0 / undefined → whole-screen, keyed as -1). Missing key means
+    /** Last-changed timestamp per stable region. Numeric key = cursor_above
+     *  value (0 / undefined → whole-screen, keyed as -1). String key =
+     *  `section:<id>` for a section-scoped stable region. Missing key means
      *  "never observed changing" → treated as stable since stateEnteredAt. */
-    regionLastChangedAt: Map<number, number>;
+    regionLastChangedAt: Map<number | string, number>;
 }
 
 /** Per-condition evaluation detail — the debugging payload. */
@@ -82,8 +83,23 @@ export interface FsmEvaluation {
 
 const WHOLE_SCREEN = -1;
 
-function regionKey(cursorAbove: number | undefined): number {
-    return cursorAbove && cursorAbove > 0 ? cursorAbove : WHOLE_SCREEN;
+/** The `regionLastChangedAt` key for a stable condition. The key must capture
+ *  everything that makes two stable clauses watch a DIFFERENT change signal:
+ *  the geometric region (`section` wins over `cursor_above`, else whole-screen)
+ *  AND the `ignore_lines` filter (two clauses on the same region but different
+ *  ignore patterns see different "did it change" answers). Kept in one place so
+ *  the driver (which populates the map) and the evaluator (which reads it)
+ *  agree on the key.
+ *
+ *  Bare whole-screen with no ignore filter keeps its historical numeric key -1
+ *  so existing callers/tests that seed `regionLastChangedAt` with [-1, ...]
+ *  keep working unchanged. */
+export function stableRegionKey(cond: { section?: string; cursor_above?: number; ignore_lines?: string }): number | string {
+    const region = cond.section
+        ? `section:${cond.section}`
+        : (cond.cursor_above && cond.cursor_above > 0 ? cond.cursor_above : WHOLE_SCREEN);
+    if (!cond.ignore_lines) return region;
+    return `${region}#ignore:${cond.ignore_lines}`;
 }
 
 function isRegex(c: FsmCondition): c is import('./types.js').RegexCondition {
@@ -150,7 +166,7 @@ function evalCond(
         return { kind: 'elapsed', result, detail: `elapsed ${age}ms / ${cond.elapsed_ms}ms`, remainingMs };
     }
     if (isStable(cond)) {
-        const key = regionKey(cond.cursor_above);
+        const key = stableRegionKey(cond);
         // If we never saw the region change, treat it as stable since the
         // state was entered (conservative — avoids a premature "stable" on
         // the very first frame).
@@ -158,8 +174,10 @@ function evalCond(
         const stableFor = clock.now - lastChanged;
         const result = stableFor >= cond.stable_ms;
         const remainingMs = result ? 0 : cond.stable_ms - stableFor;
-        const where = key === WHOLE_SCREEN ? 'screen' : `cursor_above=${cond.cursor_above}`;
-        return { kind: 'stable', result, detail: `stable ${where} ${stableFor}ms / ${cond.stable_ms}ms`, remainingMs };
+        const where = cond.section ? `section=${cond.section}`
+            : cond.cursor_above && cond.cursor_above > 0 ? `cursor_above=${cond.cursor_above}` : 'screen';
+        const ign = cond.ignore_lines ? ' (ignore_lines)' : '';
+        return { kind: 'stable', result, detail: `stable ${where}${ign} ${stableFor}ms / ${cond.stable_ms}ms`, remainingMs };
     }
     // regex / changed → shared evaluator (operates on v3 Condition shape)
     if (isRegex(cond) || isChanged(cond)) {

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

@@ -114,7 +114,15 @@ function validateCondition(c: FsmCondition, sectionIds: Set<string>, path: strin
     }
     if ('cursor_above' in w && 'changed' in w) 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`); return errs; }
+    if ('stable_ms' in w) {
+        if (typeof w.stable_ms !== 'number') errs.push(`${path}.stable_ms must be a number`);
+        if (w.section && !sectionIds.has(w.section)) errs.push(`${path}.section "${w.section}" unknown`);
+        if (w.ignore_lines !== undefined) {
+            if (typeof w.ignore_lines !== 'string') errs.push(`${path}.ignore_lines must be a string`);
+            else try { new RegExp(w.ignore_lines, 'm'); } catch (e) { errs.push(`${path}.ignore_lines invalid regex: ${(e as Error).message}`); }
+        }
+        return errs;
+    }
     errs.push(`${path} is not a recognized condition`);
     return errs;
 }

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

@@ -45,12 +45,40 @@ export interface ElapsedCondition {
     elapsed_ms: number;
 }
 
-/** True once the region `cursor_above` lines above the cursor has been
- *  unchanged for `ms`. A stability gate — the inverse of a busy signal. */
+/** True once a region has been unchanged for `ms`. A stability gate — the
+ *  inverse of a busy signal.
+ *
+ *  Region selection (precedence order):
+ *   - `section`     : a named section from the spec's `sections{}` (e.g. "body").
+ *                     Only lines inside that section are watched for change.
+ *   - `cursor_above`: the N lines directly above the cursor.
+ *   - neither       : the whole screen (default).
+ *
+ *  `ignore_lines` is orthogonal to region choice: lines matching it are
+ *  stripped from BOTH frames before the change comparison, so a per-frame
+ *  animation on those lines cannot reset the stable clock. This is the
+ *  content-aware escape hatch for the busy→idle wedge — a benign residual
+ *  ticker (a bare token counter / elapsed timer that repaints every frame
+ *  after generation has finished) is filtered out, so a genuinely settled
+ *  transcript can reach `stable_ms`. It is deliberately CONTENT-based, not
+ *  geometric: an ACTIVE spinner line (glyph + esc/token trailer) does NOT
+ *  match the benign pattern, so a real below-prompt spinner tick still resets
+ *  the clock and holds busy (the FALSEIDLE2 / FALSEBUSY-B invariant). */
 export interface StableCondition {
     stable_ms: number;
-    /** Lines above the cursor that must be stable. Default: whole screen. */
+    /** Named section (from `sections{}`) that must be stable. Takes precedence
+     *  over `cursor_above`. */
+    section?: string;
+    /** Lines above the cursor that must be stable. Default: whole screen.
+     *  Ignored when `section` is set. */
     cursor_above?: number;
+    /** Regex (line-tested with `m` flag). Lines matching it are removed from
+     *  both the current and previous frame before deciding whether the region
+     *  changed — a per-frame repaint confined to these lines does NOT reset the
+     *  stability clock. Use for benign residual animation (token counter /
+     *  elapsed timer). Must NOT match an active-spinner line, or a real spinner
+     *  tick would be masked. */
+    ignore_lines?: string;
 }
 
 export interface FsmAllCondition {