@aiwayds/dsh-tui-pi 2.23.0 → 2.24.0

package/lib/attention-jev.d.ts

@@ -0,0 +1,80 @@
+/**
+ * The jev upgrade layer for attention (ticket 04): batches every dirty
+ * live child into ONE System One call — two atomic noul questions per child
+ * (`attention_<id8>`: needs-operator-attention, `spin_<id8>`: productive vs
+ * circling) over a shared compact state table — and writes the scores back
+ * through `AttentionBoard.applyJevScores`. A high-segment `spin` verdict
+ * (≥0.75; middle values are uncertainty, never evidence) becomes the
+ * `spinning` tag the early-hard-stop ladder later consumes (ticket 05).
+ *
+ * jev-optional by construction: the source ticks silently when the setting
+ * is off, the core probe fails, no key is configured, the debounce window
+ * is open, another call is in flight, or nothing is dirty — and a failed
+ * call is a silent counter bump, never a warn and never a turned-down
+ * ranking (the heuristic layer underneath is always live).
+ */
+import type { AgentView } from './dsh-events.ts';
+import type { AttentionBoard, AttentionTag } from './attention.ts';
+/** Structural slice of @aiwayds/dsh-jev-core — type-only import, erased at runtime. */
+interface JevCoreModule {
+    classify(options: {
+        questions: Record<string, {
+            type: 'noul';
+            criteria: Record<string, string>;
+        }>;
+        state: string;
+        env?: NodeJS.ProcessEnv;
+        fetchImpl?: typeof fetch;
+        timeoutMs?: number;
+    }): Promise<{
+        answers: Record<string, {
+            kind: 'noul';
+            value: number;
+        }>;
+        model: string;
+        usage: unknown;
+        latencyMs: number;
+    }>;
+    isConfigured(sources?: {
+        env?: NodeJS.ProcessEnv;
+    }): boolean;
+}
+/** Minimum gap between jev dispatches (ticket 04: global debounce 30s). */
+export declare const ATTENTION_JEV_MIN_INTERVAL_MS = 30000;
+/** Per-call deadline: advisory data, generous but bounded. */
+export declare const ATTENTION_JEV_TIMEOUT_MS = 8000;
+/** High-segment line for the spin verdict — middle values are uncertainty, not evidence. */
+export declare const SPINNING_TAG_AT = 0.75;
+/** The id8 collision map is first-wins by view order; uuid4 id8 collisions are astronomic. */
+export declare function buildAttentionQuestions(id8s: readonly string[]): Record<string, {
+    type: 'noul';
+    criteria: Record<string, string>;
+}>;
+/** The shared state table: one compact line per child, the facts both questions judge. */
+export declare function buildAttentionState(views: readonly AgentView[], cap: number, now: number, stallOf: (childId: string) => number): string;
+/** Read the verdict map back onto child ids; the spinning tag rides the high segment only. */
+export declare function parseAttentionAnswers(answers: Record<string, {
+    value: number;
+}>, id8ToChild: ReadonlyMap<string, string>): [childId: string, score: number, tag: AttentionTag | undefined][];
+export interface AttentionJevOptions {
+    /** Live settings read — hot-applies the `jevAttention` toggle with no restart. */
+    modeReader: () => 'auto' | 'off';
+    env?: NodeJS.ProcessEnv;
+    fetchImpl?: typeof fetch;
+    now?: () => number;
+    minIntervalMs?: number;
+    /** Test seam: inject the core module directly, skipping the runtime probe. */
+    module?: JevCoreModule;
+}
+export interface AttentionJevSource {
+    /**
+     * Driven from the bridge's reconcile tick after `board.update(...)`;
+     * `cap` is the settings-resolved maxRounds (0 = unlimited) for the state
+     * table. Fire-and-forget, self-serializing.
+     */
+    tick(board: AttentionBoard, views: readonly AgentView[], cap: number): void;
+    /** Failed-call counter (diagnostics; the ranking itself never surfaces errors). */
+    failures(): number;
+}
+export declare function createJevAttentionSource(options: AttentionJevOptions): AttentionJevSource;
+export {};

package/lib/attention-jev.js

@@ -0,0 +1,161 @@
+/**
+ * The jev upgrade layer for attention (ticket 04): batches every dirty
+ * live child into ONE System One call — two atomic noul questions per child
+ * (`attention_<id8>`: needs-operator-attention, `spin_<id8>`: productive vs
+ * circling) over a shared compact state table — and writes the scores back
+ * through `AttentionBoard.applyJevScores`. A high-segment `spin` verdict
+ * (≥0.75; middle values are uncertainty, never evidence) becomes the
+ * `spinning` tag the early-hard-stop ladder later consumes (ticket 05).
+ *
+ * jev-optional by construction: the source ticks silently when the setting
+ * is off, the core probe fails, no key is configured, the debounce window
+ * is open, another call is in flight, or nothing is dirty — and a failed
+ * call is a silent counter bump, never a warn and never a turned-down
+ * ranking (the heuristic layer underneath is always live).
+ */
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+/** Probe the core once per process; a failed import degrades to heuristic-only ranking. */
+async function loadJevCore() {
+    const specifier = '@aiwayds/dsh-jev-core';
+    try {
+        const mod = (await import(__rewriteRelativeImportExtension(specifier)));
+        if (typeof mod['classify'] !== 'function' || typeof mod['isConfigured'] !== 'function')
+            return null;
+        return mod;
+    }
+    catch {
+        return null;
+    }
+}
+/** Minimum gap between jev dispatches (ticket 04: global debounce 30s). */
+export const ATTENTION_JEV_MIN_INTERVAL_MS = 30_000;
+/** Per-call deadline: advisory data, generous but bounded. */
+export const ATTENTION_JEV_TIMEOUT_MS = 8_000;
+/** High-segment line for the spin verdict — middle values are uncertainty, not evidence. */
+export const SPINNING_TAG_AT = 0.75;
+/** State table size guard (ticket 04: ~800 chars; hard cap keeps runaway labels bounded). */
+const STATE_MAX_CHARS = 1000;
+const LABEL_MAX_CHARS = 40;
+/** The id8 collision map is first-wins by view order; uuid4 id8 collisions are astronomic. */
+export function buildAttentionQuestions(id8s) {
+    const questions = {};
+    for (const id8 of id8s) {
+        questions[`attention_${id8}`] = {
+            type: 'noul',
+            criteria: {
+                true: 'needs operator attention now — stalled, circling, near its round cap, or ignoring guidance',
+                false: 'progressing fine — no intervention warranted',
+            },
+        };
+        questions[`spin_${id8}`] = {
+            type: 'noul',
+            criteria: {
+                true: 'work is UNPRODUCTIVE — repeating the same tools or circling without forward motion',
+                false: 'work is productive — measurable forward progress',
+            },
+        };
+    }
+    return questions;
+}
+/** The shared state table: one compact line per child, the facts both questions judge. */
+export function buildAttentionState(views, cap, now, stallOf) {
+    const lines = views.map((view) => {
+        const flags = [];
+        if (view.injectedAt !== undefined)
+            flags.push('injected');
+        if (view.retries > 0)
+            flags.push(`retrying ${view.retries}/${view.maxRetries ?? '?'}`);
+        const parts = [
+            `${view.childId.slice(0, 8)} ${view.label.slice(0, LABEL_MAX_CHARS)}`,
+            `rounds ${view.rounds}/${cap > 0 ? cap : '∞'}`,
+            `idle ${Math.round(stallOf(view.childId) / 1000)}s`,
+            `tok ${view.tokens}`,
+            ...(view.contextWindow !== undefined && view.contextWindow > 0
+                ? [`ctx ${Math.round((view.contextTokens / view.contextWindow) * 100)}%`]
+                : []),
+            ...(view.lastTool !== undefined ? [`last=${view.lastTool}`] : []),
+            ...(flags.length > 0 ? [`flags: ${flags.join(', ')}`] : []),
+        ];
+        return `- ${parts.join(' | ')}`;
+    });
+    const head = 'Subagents under supervision; judge each child on the two questions keyed by its id.';
+    return `${head}\n${lines.join('\n')}`.slice(0, STATE_MAX_CHARS);
+}
+/** Read the verdict map back onto child ids; the spinning tag rides the high segment only. */
+export function parseAttentionAnswers(answers, id8ToChild) {
+    const out = [];
+    for (const [id8, childId] of id8ToChild) {
+        const attention = answers[`attention_${id8}`];
+        if (attention === undefined)
+            continue;
+        const spin = answers[`spin_${id8}`];
+        const tag = spin !== undefined && spin.value >= SPINNING_TAG_AT ? 'spinning' : undefined;
+        out.push([childId, attention.value, tag]);
+    }
+    return out;
+}
+export function createJevAttentionSource(options) {
+    const now = options.now ?? Date.now;
+    const minIntervalMs = options.minIntervalMs ?? ATTENTION_JEV_MIN_INTERVAL_MS;
+    const env = options.env ?? process.env;
+    let core;
+    let loading;
+    let lastDispatchAt = -Infinity;
+    let inFlight = false;
+    let failureCount = 0;
+    const ensureLoaded = () => {
+        if (options.module !== undefined)
+            return Promise.resolve(options.module);
+        if (core !== undefined)
+            return Promise.resolve(core);
+        loading ??= loadJevCore().then((mod) => {
+            core = mod;
+            return mod;
+        });
+        return loading;
+    };
+    return {
+        failures: () => failureCount,
+        tick(board, views, cap) {
+            if (inFlight)
+                return;
+            if (options.modeReader() !== 'auto')
+                return;
+            const live = views.filter(view => view.outcome === undefined);
+            const dirty = board.dirtyChildren().filter(childId => live.some(view => view.childId === childId));
+            if (dirty.length === 0)
+                return;
+            const at = now();
+            if (at - lastDispatchAt < minIntervalMs)
+                return;
+            void ensureLoaded().then((mod) => {
+                if (mod === null)
+                    return;
+                if (!mod.isConfigured({ env }))
+                    return;
+                const id8ToChild = new Map(live.map(view => [view.childId.slice(0, 8), view.childId]));
+                const questions = buildAttentionQuestions([...id8ToChild.keys()]);
+                const state = buildAttentionState(live, cap, at, childId => board.rows().find(row => row.childId === childId)?.stallMs ?? 0);
+                inFlight = true;
+                lastDispatchAt = at;
+                mod
+                    .classify({ questions, state, env, fetchImpl: options.fetchImpl, timeoutMs: ATTENTION_JEV_TIMEOUT_MS })
+                    .then(result => board.applyJevScores(parseAttentionAnswers(result.answers, id8ToChild)))
+                    .catch(() => {
+                    failureCount += 1;
+                })
+                    .finally(() => {
+                    inFlight = false;
+                });
+            });
+        },
+    };
+}
+//# sourceMappingURL=attention-jev.js.map

package/lib/attention-jev.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attention-jev.js","sourceRoot":"","sources":["../src/attention-jev.ts"],"names":[],"mappings":"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"}

package/lib/attention.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Subagent attention ranking — the heuristic base layer (Charter #6:
+ * jev-optional). Scores every live child 0–1 for "how much does this need
+ * the operator's eye" from structured view facts alone (stall, rounds vs
+ * cap, unanswered injections, retries, context occupancy); the jev layer
+ * (attention-jev.ts) may REPLACE a heuristic judgment with a semantic one
+ * and does nothing when unconfigured — the ranking below is always live and
+ * costs nothing but a map walk on the bridge's 600ms reconcile tick.
+ *
+ * Layer contract (ticket 04): a jev judgment is authoritative UNTIL the
+ * child makes progress (rounds or tokens move) — jev judged a snapshot, and
+ * progress is new state, so the entry falls back to heuristic until the
+ * next jev pass covers it. Heuristic and jev scores share the same 0–1
+ * scale and tier cuts, so consumers never branch on the layer beyond the
+ * `source` label they may display.
+ *
+ * This file is pure terminal-free logic; `AttentionBoard` holds the only
+ * mutable state (per-child observation + the current info map).
+ */
+import type { AgentView } from './dsh-events.ts';
+export type AttentionTier = 'critical' | 'warn' | 'ok';
+export type AttentionSourceKind = 'heuristic' | 'jev';
+/**
+ * `stalled` / `near-cap` are heuristic signals (the top contributing
+ * factor); `spinning` / `deep-work` / `waiting` are jev's semantic tags and
+ * never produced here.
+ */
+export type AttentionTag = 'stalled' | 'near-cap' | 'spinning' | 'deep-work' | 'waiting';
+export interface AttentionInfo {
+    readonly score: number;
+    readonly tier: AttentionTier;
+    readonly source: AttentionSourceKind;
+    readonly tag?: AttentionTag;
+}
+/**
+ * The spin-streak state the early-stop ladder consumes. `lastStrikeAt` is
+ * the clock of the MOST RECENT spinning verdict — the ladder's freshness
+ * anchor (a strike older than the stale window, or older than a delivered
+ * wrap-up, must not stop anything).
+ */
+export interface SpinState {
+    /** Consecutive spinning verdicts (a non-spinning verdict zeroes it). */
+    readonly streak: number;
+    readonly lastStrikeAt: number;
+}
+/** A spinning verdict older than this is stale evidence — three debounce windows. */
+export declare const SPIN_STRIKE_STALE_MS = 90000;
+/** One consumer-facing row: the view facts plus the current attention info. */
+export interface AttentionRow {
+    readonly childId: string;
+    readonly label: string;
+    readonly info: AttentionInfo;
+    /** Ms since the child last made observable progress (rounds/tokens moved). */
+    readonly stallMs: number;
+}
+/** Tier cuts — shared by both layers so a jev score and a heuristic score are tier-comparable. */
+export declare const ATTENTION_CRITICAL_AT = 0.6;
+export declare const ATTENTION_WARN_AT = 0.35;
+/** Stall ramp: no penalty under a minute of silence; full weight at ten minutes. */
+export declare const ATTENTION_STALL_FLOOR_MS = 60000;
+export declare const ATTENTION_STALL_CEIL_MS = 600000;
+export interface HeuristicInput {
+    /** Ms since observable progress (rounds or tokens moved). */
+    stallMs: number;
+    /** Assistant-message count; the "rounds" the maxRounds ladder caps. */
+    rounds: number;
+    /** The effective maxRounds cap; 0 = unlimited (the rounds component drops out). */
+    cap: number;
+    /** A plugin injection (wrap-up / steer) landed and NO progress followed it. */
+    ignoredInjection: boolean;
+    retries: number;
+    /** Current context occupancy as a 0–1 ratio, when the window is known. */
+    contextRatio?: number;
+}
+export declare function tierFor(score: number): AttentionTier;
+/** The heuristic score: weighted view facts, 0–1, two decimals. */
+export declare function heuristicAttentionScore(input: HeuristicInput): number;
+/** Heuristic tag: the one strong signal worth naming, else unnamed. */
+export declare function heuristicTag(input: HeuristicInput, score: number): AttentionTag | undefined;
+/**
+ * The mutable ranking. One instance per bridge; `update()` on the reconcile
+ * tick is the only required driver. `now` is injectable for tests.
+ */
+export declare class AttentionBoard {
+    private readonly observations;
+    private now;
+    constructor(now?: () => number);
+    setClock(now: () => number): void;
+    /**
+     * Re-observe every live child: detect progress, recompute heuristic info,
+     * apply any still-fresh jev judgment, prune settled/gone children. Idempotent
+     * and O(n) — safe on every tick.
+     */
+    update(views: readonly AgentView[], cap: number): void;
+    /**
+     * The jev layer's write-in: replaces the heuristic judgment for the named
+     * children (same scale, same tiers — ticket 04 "替代非融合"). Children the
+     * board no longer tracks are ignored; covered children lose their dirty flag.
+     */
+    applyJevScores(scores: readonly (readonly [childId: string, score: number, tag: AttentionTag | undefined])[]): void;
+    /**
+     * The early-stop ladder's input: consecutive spinning verdicts plus the
+     * clock of the most recent one (the freshness anchor). Absent children
+     * report zeroed state.
+     */
+    spinState(childId: string): SpinState;
+    /** Children whose state changed since their last jev judgment (the refresh's work list). */
+    dirtyChildren(): string[];
+    /** One child's current info, when ranked. */
+    get(childId: string): AttentionInfo | undefined;
+    /** All rows, highest attention first — the picker/status/guard read side. */
+    rows(): AttentionRow[];
+    /**
+     * The guard's deny-copy hint: the most attention-worthy live child that is
+     * actually worth acting on (tier above ok), or undefined when the ranking
+     * has nothing to say.
+     */
+    topHint(): {
+        label: string;
+        detail: string;
+    } | undefined;
+}

package/lib/attention.js

@@ -0,0 +1,220 @@
+/**
+ * Subagent attention ranking — the heuristic base layer (Charter #6:
+ * jev-optional). Scores every live child 0–1 for "how much does this need
+ * the operator's eye" from structured view facts alone (stall, rounds vs
+ * cap, unanswered injections, retries, context occupancy); the jev layer
+ * (attention-jev.ts) may REPLACE a heuristic judgment with a semantic one
+ * and does nothing when unconfigured — the ranking below is always live and
+ * costs nothing but a map walk on the bridge's 600ms reconcile tick.
+ *
+ * Layer contract (ticket 04): a jev judgment is authoritative UNTIL the
+ * child makes progress (rounds or tokens move) — jev judged a snapshot, and
+ * progress is new state, so the entry falls back to heuristic until the
+ * next jev pass covers it. Heuristic and jev scores share the same 0–1
+ * scale and tier cuts, so consumers never branch on the layer beyond the
+ * `source` label they may display.
+ *
+ * This file is pure terminal-free logic; `AttentionBoard` holds the only
+ * mutable state (per-child observation + the current info map).
+ */
+/** A spinning verdict older than this is stale evidence — three debounce windows. */
+export const SPIN_STRIKE_STALE_MS = 90_000;
+/** Tier cuts — shared by both layers so a jev score and a heuristic score are tier-comparable. */
+export const ATTENTION_CRITICAL_AT = 0.6;
+export const ATTENTION_WARN_AT = 0.35;
+/** Stall ramp: no penalty under a minute of silence; full weight at ten minutes. */
+export const ATTENTION_STALL_FLOOR_MS = 60_000;
+export const ATTENTION_STALL_CEIL_MS = 600_000;
+/** Component weights — documented so preview data can tune them deliberately. */
+const W_STALL = 0.45;
+const W_ROUNDS = 0.25;
+const W_IGNORED = 0.15;
+const W_RETRIES = 0.1;
+const W_CONTEXT = 0.05;
+function clamp01(value) {
+    return Math.min(1, Math.max(0, value));
+}
+function stallFactor(stallMs) {
+    if (stallMs <= ATTENTION_STALL_FLOOR_MS)
+        return 0;
+    return clamp01((stallMs - ATTENTION_STALL_FLOOR_MS) / (ATTENTION_STALL_CEIL_MS - ATTENTION_STALL_FLOOR_MS));
+}
+export function tierFor(score) {
+    if (score >= ATTENTION_CRITICAL_AT)
+        return 'critical';
+    if (score >= ATTENTION_WARN_AT)
+        return 'warn';
+    return 'ok';
+}
+/** The heuristic score: weighted view facts, 0–1, two decimals. */
+export function heuristicAttentionScore(input) {
+    const stall = W_STALL * stallFactor(input.stallMs);
+    const rounds = input.cap > 0 ? W_ROUNDS * clamp01(input.rounds / input.cap) : 0;
+    const ignored = input.ignoredInjection ? W_IGNORED : 0;
+    const retries = W_RETRIES * clamp01(input.retries / 3);
+    const context = input.contextRatio !== undefined ? W_CONTEXT * clamp01(input.contextRatio) : 0;
+    return Math.round((stall + rounds + ignored + retries + context) * 100) / 100;
+}
+/** Heuristic tag: the one strong signal worth naming, else unnamed. */
+export function heuristicTag(input, score) {
+    if (input.cap > 0 && input.rounds / input.cap >= 0.85)
+        return 'near-cap';
+    if (stallFactor(input.stallMs) >= 0.5)
+        return 'stalled';
+    // A score that reached warn/critical without a dominant single factor is
+    // still worth flagging as stalled-ish for consumers that filter on tags.
+    if (score >= ATTENTION_WARN_AT)
+        return 'stalled';
+    return undefined;
+}
+/** Heuristic inputs derived from one live view + the board's own observation of it. */
+function inputsFor(view, observation, now) {
+    return {
+        stallMs: Math.max(0, now - observation.lastProgressAt),
+        rounds: view.rounds,
+        cap: 0, // substituted by the board (settings-resolved)
+        ignoredInjection: view.injectedAt !== undefined && observation.lastProgressAt <= view.injectedAt,
+        retries: view.retries,
+        contextRatio: view.contextWindow !== undefined && view.contextWindow > 0
+            ? view.contextTokens / view.contextWindow
+            : undefined,
+    };
+}
+/**
+ * The mutable ranking. One instance per bridge; `update()` on the reconcile
+ * tick is the only required driver. `now` is injectable for tests.
+ */
+export class AttentionBoard {
+    observations = new Map();
+    now;
+    constructor(now = Date.now) {
+        this.now = now;
+    }
+    setClock(now) {
+        this.now = now;
+    }
+    /**
+     * Re-observe every live child: detect progress, recompute heuristic info,
+     * apply any still-fresh jev judgment, prune settled/gone children. Idempotent
+     * and O(n) — safe on every tick.
+     */
+    update(views, cap) {
+        const now = this.now();
+        // The board ranks LIVE children only: a child that settled this pass is
+        // pruned with the same stroke (its observation must not linger stale).
+        const live = new Set(views.filter(view => view.outcome === undefined).map(view => view.childId));
+        for (const childId of [...this.observations.keys()]) {
+            if (!live.has(childId))
+                this.observations.delete(childId);
+        }
+        for (const view of views) {
+            if (view.outcome !== undefined || !live.has(view.childId))
+                continue;
+            const previous = this.observations.get(view.childId);
+            const progressed = previous === undefined ||
+                view.rounds !== previous.lastRounds ||
+                view.tokens !== previous.lastTokens;
+            const observation = previous ?? {
+                label: view.label,
+                lastProgressAt: now,
+                lastRounds: view.rounds,
+                lastTokens: view.tokens,
+                info: { score: 0, tier: 'ok', source: 'heuristic' },
+                dirtyForJev: true,
+                spinStreak: 0,
+                lastStrikeAt: 0,
+            };
+            observation.label = view.label;
+            if (progressed) {
+                observation.lastProgressAt = now;
+                observation.lastRounds = view.rounds;
+                observation.lastTokens = view.tokens;
+                observation.dirtyForJev = true;
+                // A jev judgment judged the state BEFORE this progress — the info
+                // falls back to heuristic (below). The spin streak is deliberately
+                // NOT cleared: a circling child makes "progress" (rounds grow) by
+                // definition, and freshness is the ladder's job (lastStrikeAt).
+            }
+            const input = { ...inputsFor(view, observation, now), cap };
+            const score = heuristicAttentionScore(input);
+            observation.info = {
+                score,
+                tier: tierFor(score),
+                source: 'heuristic',
+                tag: heuristicTag(input, score),
+            };
+            this.observations.set(view.childId, observation);
+        }
+    }
+    /**
+     * The jev layer's write-in: replaces the heuristic judgment for the named
+     * children (same scale, same tiers — ticket 04 "替代非融合"). Children the
+     * board no longer tracks are ignored; covered children lose their dirty flag.
+     */
+    applyJevScores(scores) {
+        const now = this.now();
+        for (const [childId, score, tag] of scores) {
+            const observation = this.observations.get(childId);
+            if (observation === undefined)
+                continue;
+            const clamped = clamp01(score);
+            observation.info = { score: clamped, tier: tierFor(clamped), source: 'jev', ...(tag !== undefined ? { tag } : {}) };
+            observation.dirtyForJev = false;
+            if (tag === 'spinning') {
+                observation.spinStreak += 1;
+                observation.lastStrikeAt = now;
+            }
+            else {
+                observation.spinStreak = 0;
+                observation.lastStrikeAt = 0;
+            }
+        }
+    }
+    /**
+     * The early-stop ladder's input: consecutive spinning verdicts plus the
+     * clock of the most recent one (the freshness anchor). Absent children
+     * report zeroed state.
+     */
+    spinState(childId) {
+        const observation = this.observations.get(childId);
+        return observation === undefined
+            ? { streak: 0, lastStrikeAt: 0 }
+            : { streak: observation.spinStreak, lastStrikeAt: observation.lastStrikeAt };
+    }
+    /** Children whose state changed since their last jev judgment (the refresh's work list). */
+    dirtyChildren() {
+        return [...this.observations.entries()].filter(([, observation]) => observation.dirtyForJev).map(([childId]) => childId);
+    }
+    /** One child's current info, when ranked. */
+    get(childId) {
+        return this.observations.get(childId)?.info;
+    }
+    /** All rows, highest attention first — the picker/status/guard read side. */
+    rows() {
+        const now = this.now();
+        return [...this.observations.entries()]
+            .map(([childId, observation]) => ({
+            childId,
+            label: observation.label,
+            info: observation.info,
+            stallMs: Math.max(0, now - observation.lastProgressAt),
+        }))
+            .sort((a, b) => b.info.score - a.info.score);
+    }
+    /**
+     * The guard's deny-copy hint: the most attention-worthy live child that is
+     * actually worth acting on (tier above ok), or undefined when the ranking
+     * has nothing to say.
+     */
+    topHint() {
+        const row = this.rows().find(row => row.info.tier !== 'ok');
+        if (row === undefined)
+            return undefined;
+        const tag = row.info.tag !== undefined ? `, ${row.info.tag}` : '';
+        return {
+            label: row.label,
+            detail: `${row.info.source} score ${row.info.score.toFixed(2)}${tag}, idle ${Math.round(row.stallMs / 1000)}s`,
+        };
+    }
+}
+//# sourceMappingURL=attention.js.map

package/lib/attention.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attention.js","sourceRoot":"","sources":["../src/attention.ts"],"names":[],"mappings":"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"}

package/lib/dsh-events.d.ts

@@ -197,14 +197,17 @@ export interface AgentView {
     readonly injectedAt?: number;
     /**
      * Set when the maxRounds policy HARD-STOPPED this child (the wrap-up's
-     * grace window exhausted): the round count at the stop and the cap it
-     * exceeded. Surfaced as the `⏻` marker on the compact line, the picker row
-     * and the viewer transcript (a marker row) — a force-stop is policy, not a
-     * failure, and must be visible as such.
+     * grace window exhausted, or the spin-detected early stop): the round
+     * count at the stop and the cap it exceeded. `early` marks a stop fired
+     * BEFORE the grace window — the attention ranking judged the child
+     * circling twice. Surfaced as the `⏻` marker on the compact line, the
+     * picker row and the viewer transcript (a marker row) — a force-stop is
+     * policy, not a failure, and must be visible as such.
      */
     readonly hardStop?: {
         readonly round: number;
         readonly cap: number;
+        readonly early?: true;
     };
     /**
      * Latest visible last line of the child's own CONTENT output (the tail the