@adhdev/daemon-core 0.9.82-rc.209 → 0.9.82-rc.210

package/dist/mesh/mesh-review-inbox.d.ts

@@ -0,0 +1,90 @@
+/**
+ * M4.0: Review inbox — derive review items from existing truth.
+ *
+ * No new store: review items are a query-time projection of
+ *   - mesh_status node statuses (daemon-owned branchConvergence), and
+ *   - the task ledger (completion evidence envelopes + refine job results).
+ *
+ * Scope (M4.0): host-daemon-local nodes only. Remote nodes are excluded and
+ * surfaced via remoteNodesExcluded/excludedRemoteNodeIds until the
+ * daemon↔daemon P2P relay path is live-verified (M4.2).
+ */
+import type { MeshLedgerEntry } from './mesh-ledger.js';
+export type MeshReviewInboxReason = 'merge_candidate' | 'refine_blocked_review';
+export interface MeshReviewInboxConvergence {
+    status: string;
+    reason: string | null;
+    nextStep: string | null;
+    needsConvergence: boolean;
+}
+export interface MeshReviewInboxEvidence {
+    available: boolean;
+    /** Ledger kind of the entry the evidence came from. */
+    kind?: 'task_completed' | 'task_failed';
+    /** 'task_completion' = ordinary worker completion envelope; 'refine_job' = Refinery result. */
+    source?: 'task_completion' | 'refine_job';
+    timestamp?: string;
+    taskId?: string;
+    sessionId?: string;
+    /** M2-3 bootstrap stage from the refine validation gate: cached|ran|failed|skipped|legacy|not_configured. */
+    bootstrap?: Record<string, unknown> | null;
+    validation?: Record<string, unknown> | null;
+    checkpoint?: Record<string, unknown> | null;
+    worker?: {
+        status: string;
+        classification?: string;
+        changedFiles: string[];
+        changedFilesTruncated?: true;
+        validationResults: Array<Record<string, unknown>>;
+        errors: string[];
+        requiresUserAction: boolean;
+    } | null;
+    finalBranchConvergenceState?: Record<string, unknown>;
+    refineJob?: Record<string, unknown>;
+}
+export interface MeshReviewInboxDiffFile {
+    path: string;
+    status?: string;
+    insertions?: number;
+    deletions?: number;
+    binary?: boolean;
+    oldPath?: string;
+}
+export interface MeshReviewInboxDiffSummary {
+    baseRef: string;
+    files: MeshReviewInboxDiffFile[];
+    totalFiles: number;
+    totalInsertions: number;
+    totalDeletions: number;
+    truncated: boolean;
+    error?: string;
+}
+export interface MeshReviewInboxItem {
+    nodeId: string;
+    workspace: string | null;
+    branch: string | null;
+    defaultBranch: string | null;
+    isLocalWorktree: boolean;
+    reviewReason: MeshReviewInboxReason;
+    convergence: MeshReviewInboxConvergence;
+    evidence: MeshReviewInboxEvidence;
+    transcriptHandle: Record<string, unknown> | null;
+    /** Latest non-terminal Refinery job for this node (accepted/running), if any. */
+    activeRefineJob: Record<string, unknown> | null;
+    lastActivityAt: string | null;
+    /** Filled by the daemon command with a bounded base-branch diff probe; null when the workspace is not locally readable. */
+    diffSummary?: MeshReviewInboxDiffSummary | null;
+}
+export interface MeshReviewInboxDerivation {
+    items: MeshReviewInboxItem[];
+    remoteNodesExcluded: boolean;
+    excludedRemoteNodeIds: string[];
+}
+/**
+ * Derive review inbox items from mesh_status node statuses and a bounded
+ * ledger tail. Pure and read-only; the caller attaches diffSummary separately.
+ */
+export declare function deriveMeshReviewInboxItems(args: {
+    nodes: Array<Record<string, unknown>>;
+    ledgerEntries: MeshLedgerEntry[];
+}): MeshReviewInboxDerivation;

package/dist/mesh/mesh-runtime-store.d.ts

@@ -146,4 +146,179 @@ export declare class MeshRuntimeStore {
         event: string;
         createdAt: string;
     }>;
+    /**
+     * Record a mesh tool call and check whether this mesh+tool combination is
+     * being called too rapidly (sliding window rate guard).
+     *
+     * Returns a rate-limit advisory string when the call rate is too high, null otherwise.
+     * windowMs: sliding window size in ms (default 10s)
+     * maxCalls: max allowed calls within the window (default 5)
+     */
+    recordMeshToolCall(opts: {
+        meshId: string;
+        tool: string;
+        sessionId?: string | null;
+        windowMs?: number;
+        maxCalls?: number;
+    }): {
+        rateLimitExceeded: boolean;
+        callsInWindow: number;
+        advisory: string | null;
+    };
+    /**
+     * Prune tool call log entries older than the given age in ms.
+     * Exposed for testing.
+     */
+    pruneToolCallLog(olderThanMs: number): void;
+    appendLedgerEntry(entry: {
+        id: string;
+        meshId: string;
+        timestamp: string;
+        kind: string;
+        nodeId?: string | null;
+        sessionId?: string | null;
+        providerType?: string | null;
+        payload?: unknown;
+    }): void;
+    readLedgerEntries(meshId: string, opts?: {
+        tail?: number;
+        since?: string;
+        kind?: string;
+        limit?: number;
+    }): Array<{
+        id: string;
+        meshId: string;
+        timestamp: string;
+        kind: string;
+        nodeId: string | null;
+        sessionId: string | null;
+        providerType: string | null;
+        payload: unknown;
+    }>;
+    /**
+     * G2 read cutover: read ledger entries in append order (oldest first),
+     * matching legacy JSONL file-order semantics. Ties on the same timestamp
+     * are broken by rowid (insertion order), preserving the positional
+     * guarantee that mesh-events relies on for same-millisecond entries.
+     */
+    readLedgerEntriesOrdered(meshId: string, opts?: {
+        since?: string;
+        kinds?: string[];
+        tail?: number;
+    }): Array<{
+        id: string;
+        meshId: string;
+        timestamp: string;
+        kind: string;
+        nodeId: string | null;
+        sessionId: string | null;
+        providerType: string | null;
+        payload: unknown;
+    }>;
+    /** Remove all ledger entries for a mesh (mesh deletion / test cleanup). */
+    clearLedgerForMesh(meshId: string): number;
+    /** G2: remove entries moved to the JSONL archive so the SQLite runtime set mirrors the active ledger. */
+    deleteLedgerEntries(meshId: string, ids: string[]): number;
+    hasLedgerEntry(meshId: string, id: string): boolean;
+    ledgerEntryCount(meshId: string): number;
+    importLedgerEntries(entries: Array<{
+        id: string;
+        meshId: string;
+        timestamp: string;
+        kind: string;
+        nodeId?: string | null;
+        sessionId?: string | null;
+        providerType?: string | null;
+        payload?: unknown;
+    }>): number;
+    /**
+     * G4: Read a bounded, cursor-addressable ledger slice directly from the SQLite
+     * mesh_event_ledger table. This is the P2P reconcile read path; JSONL files are
+     * retained as export/import/debug/legacy artifacts only.
+     *
+     * The return shape is structurally compatible with MeshLedgerSlice so callers
+     * in mesh-tools.ts can pass it directly to buildMeshLedgerReplicaEvidence.
+     */
+    readLedgerSlice(meshId: string, opts?: {
+        afterId?: string;
+        since?: string;
+        kind?: string;
+        limit?: number;
+    }): {
+        protocol: 'adhdev.mesh.ledger.slice.v1';
+        meshId: string;
+        entries: Array<{
+            id: string;
+            meshId: string;
+            timestamp: string;
+            kind: string;
+            nodeId: string | null;
+            sessionId: string | null;
+            providerType: string | null;
+            payload: unknown;
+        }>;
+        cursor: {
+            afterId: string | null;
+            nextAfterId: string | null;
+            limit: number;
+            hasMore: boolean;
+        };
+        sourceOfTruth: {
+            kind: 'local_sqlite';
+            table: 'mesh_event_ledger';
+            bounded: true;
+            maxLimit: number;
+        };
+    };
+    insertPendingEvent(event: {
+        id: string;
+        meshId: string;
+        coordinatorDaemonId?: string | null;
+        event: string;
+        payload?: unknown;
+        fingerprint?: string | null;
+        queuedAt: number;
+    }): boolean;
+    drainPendingEvents(meshId: string, coordinatorDaemonId?: string | null): Array<{
+        id: string;
+        event: string;
+        payload: unknown;
+    }>;
+    /** Non-destructive peek — returns undrained events without marking them drained. */
+    peekPendingEvents(meshId: string, coordinatorDaemonId?: string | null): Array<{
+        id: string;
+        event: string;
+        payload: unknown;
+    }>;
+    hasPendingEventFingerprint(meshId: string, fingerprint: string): boolean;
+    upsertMission(mission: {
+        id: string;
+        meshId: string;
+        title: string;
+        goal?: string;
+        status?: string;
+    }): void;
+    getMission(meshId: string, missionId: string): {
+        id: string;
+        meshId: string;
+        title: string;
+        goal: string;
+        status: string;
+        createdAt: string;
+        updatedAt: string;
+    } | null;
+    getMissions(meshId: string, statuses?: string[]): Array<{
+        id: string;
+        meshId: string;
+        title: string;
+        goal: string;
+        status: string;
+        createdAt: string;
+        updatedAt: string;
+    }>;
+    /** Remove all missions for a mesh — mesh deletion / test cleanup. */
+    clearMissionsForMesh(meshId: string): number;
+    /** Remove all pending-event rows (drained included) for a mesh — mesh deletion / test cleanup. */
+    clearPendingEventsForMesh(meshId: string): number;
+    pendingEventCount(meshId: string): number;
 }

package/dist/mesh/mesh-task-stats.d.ts

@@ -0,0 +1,49 @@
+/**
+ * M7: Operational stats (time/attempts) derived from existing truth.
+ *
+ * No cost/token accounting — ADHDev observes PTY/CDP and cannot see API
+ * tokens (explicit non-goal). Everything here is derived at query time from
+ * the SQLite ledger and queue rows; there is no separate aggregate table.
+ * Tasks with missing ledger evidence report incompleteEvidence instead of
+ * estimated numbers.
+ */
+export interface MeshTaskStats {
+    taskId: string;
+    status: string;
+    dispatchedAt: string | null;
+    terminalAt: string | null;
+    terminalKind: 'task_completed' | 'task_failed' | null;
+    /** dispatched → terminal wall clock; null when evidence is incomplete. */
+    durationMs: number | null;
+    /** Number of task_dispatched ledger entries observed for this task. */
+    dispatchCount: number;
+    /** Queue requeueCount (0 when the row is gone or never requeued). */
+    requeueCount: number;
+    /** True when dispatch or terminal ledger evidence is missing — numbers are withheld, never estimated. */
+    incompleteEvidence?: true;
+}
+export interface MeshMissionStats {
+    missionId: string;
+    taskCount: number;
+    completed: number;
+    failed: number;
+    /** Sum of per-task durations with complete evidence. */
+    totalDurationMs: number;
+    /** First dispatch → last terminal across the mission's tasks; null without complete endpoints. */
+    wallClockMs: number | null;
+    /** Total requeue attempts across the mission's tasks. */
+    retries: number;
+    /** Task ids whose ledger evidence was incomplete (excluded from sums). */
+    incompleteTaskIds: string[];
+}
+/**
+ * Compute per-task stats from ledger entries. Scans a bounded tail window —
+ * stats are an operational view of recent work, not a full historical report.
+ */
+export declare function computeMeshTaskStats(meshId: string, opts?: {
+    taskIds?: string[];
+    missionId?: string;
+    tail?: number;
+}): MeshTaskStats[];
+/** Mission rollup — derived from per-task stats, no stored aggregates. */
+export declare function computeMeshMissionStats(meshId: string, missionId: string): MeshMissionStats;

package/dist/mesh/mesh-work-queue.d.ts

@@ -27,6 +27,20 @@ export interface MeshWorkQueueEntry {
     targetSessionId?: string;
     /** If specified, a node must expose all tags before it can claim the task. */
     requiredTags?: string[];
+    /**
+     * M1: ids of tasks that must reach 'completed' before this task is claimable.
+     * Forward references (ids not yet enqueued) are allowed for batch flows and
+     * simply keep the task waiting until the referenced task exists and completes.
+     */
+    dependsOn?: string[];
+    /** M1/M3: mission this task belongs to (joins mesh_missions). */
+    missionId?: string;
+    /**
+     * M1: why this task is held back (e.g. "dependency_failed:<taskId>").
+     * Only set by the system on dependency failure under the 'block' policy;
+     * waiting-on-dependency state is computed at view time, not stored.
+     */
+    blockedReason?: string;
     /** The node that actually claimed and is executing the task */
     assignedNodeId?: string;
     /** The session currently executing the task */
@@ -38,6 +52,8 @@ export interface MeshWorkQueueEntry {
     requeueReason?: string;
     requeuedAt?: string;
     requeueCount?: number;
+    /** Max automatic requeue attempts. When requeueCount reaches this, task is auto-failed. */
+    maxRetries?: number;
     /** Last automatic queue session spin-up attempt, for mesh_view_queue/debug visibility. */
     autoLaunch?: {
         status: 'skipped' | 'started' | 'failed' | 'completed';
@@ -59,8 +75,16 @@ export declare function normalizeMeshCapabilityTags(value: unknown): string[];
 export declare function buildMeshNodeCapabilityTags(node: {
     capabilities?: unknown;
     policy?: unknown;
+    isLocalWorktree?: unknown;
+    worktreeBranch?: unknown;
 } | undefined, providerType?: string): string[];
 export declare function nodeSatisfiesRequiredTags(requiredTags: unknown, capabilityTags: unknown): boolean;
+/**
+ * M1: detect dependency cycles before enqueue. Walks the dependency graph of
+ * existing queue entries plus the new task's edges. Fail-closed: a cycle
+ * rejects the enqueue entirely. Synchronous and bounded by queue size.
+ */
+export declare function assertNoDependencyCycle(meshId: string, newTaskId: string, dependsOn: string[]): void;
 /**
  * Add a new task to the mesh queue.
  */
@@ -69,6 +93,12 @@ export declare function enqueueTask(meshId: string, message: string, opts?: {
     targetSessionId?: string;
     taskMode?: MeshTaskMode | string;
     requiredTags?: string[];
+    /** M1: tasks that must complete before this one is claimable. */
+    dependsOn?: string[];
+    /** M1/M3: mission this task belongs to. */
+    missionId?: string;
+    /** Explicit task id for batch/template flows (M5). Random UUID when omitted. */
+    id?: string;
 } & MeshQueueMutationOptions): MeshWorkQueueEntry;
 /**
  * Get all tasks in the queue, optionally filtered by status.
@@ -81,6 +111,7 @@ export declare function getMeshQueueRevision(meshId: string): string;
  * Find the next pending task that this node is allowed to claim, and mark it as assigned.
  */
 export declare function claimNextTask(meshId: string, nodeId: string, sessionId: string, capabilityTags?: string[]): MeshWorkQueueEntry | null;
+export type DependencyFailurePolicy = 'block' | 'cancel';
 /**
  * Update the status of a specific task.
  * Used when a session completes, fails, or stalls.
@@ -97,12 +128,30 @@ export declare function cancelTask(meshId: string, taskId: string, opts?: {
  * Return a queue task to pending for retry. By default, dead session targeting
  * and assigned ownership are cleared so stale assignments do not strand again.
  */
+export type RequeueResult = {
+    status: 'requeued';
+    entry: MeshWorkQueueEntry;
+} | {
+    status: 'failed_max_retries';
+    entry: MeshWorkQueueEntry;
+    maxRetries: number;
+    requeueCount: number;
+} | {
+    status: 'not_found';
+};
 export declare function requeueTask(meshId: string, taskId: string, opts?: {
     reason?: string;
     targetNodeId?: string;
     targetSessionId?: string;
     clearTargetNode?: boolean;
     clearTargetSession?: boolean;
+    /**
+     * Override the retry cap for this call. Use only for explicit operator actions.
+     * If true, the task is requeued even when requeueCount >= maxRetries.
+     */
+    force?: boolean;
+    /** Per-task retry cap override. Falls back to mesh policy maxTaskRetries (default 1). */
+    maxRetries?: number;
 } & MeshQueueMutationOptions): MeshWorkQueueEntry | null;
 /**
  * Update the status of the task currently assigned to a specific session.
@@ -110,6 +159,20 @@ export declare function requeueTask(meshId: string, taskId: string, opts?: {
 export declare function updateSessionTaskStatus(meshId: string, sessionId: string, status: MeshTaskStatus, opts?: {
     occurredAt?: string;
 }): MeshWorkQueueEntry | null;
+/**
+ * M1-3: true when at least one pending task is waiting on the given task.
+ * Used by the completion event path to decide whether to wake the queue.
+ */
+export declare function hasPendingDependents(meshId: string, taskId: string): boolean;
+/**
+ * M1-4: view-time dependency state for a task — unmet dependency ids and
+ * whether the task is currently claimable from a dependency standpoint.
+ * Not stored (truth stays in task statuses).
+ */
+export declare function describeTaskDependencyState(entry: Pick<MeshWorkQueueEntry, 'dependsOn' | 'blockedReason'>, statusById: Map<string, MeshTaskStatus | string>): {
+    waitingOn: string[];
+    dependenciesSatisfied: boolean;
+};
 export interface MeshWorkQueueStats {
     total: number;
     active: number;
@@ -154,3 +217,22 @@ export declare function getActiveDirectDispatches(meshId: string): DirectDispatc
 export declare function updateDirectDispatchStatus(meshId: string, sessionId: string, status: 'acked' | 'completed' | 'failed' | 'stale'): void;
 export declare function cleanupTerminalDirectDispatches(olderThanMs?: number): void;
 export declare function markStaleDirectDispatches(meshId: string, olderThanMs?: number): void;
+export type MeshToolCallRateResult = {
+    rateLimitExceeded: boolean;
+    callsInWindow: number;
+    advisory: string | null;
+};
+/**
+ * Record a coordinator tool call and return a rate-limit advisory when the
+ * call rate for that tool exceeds the allowed threshold.
+ *
+ * Defaults: 10-second sliding window, max 5 calls before advisory is raised.
+ * Returns { rateLimitExceeded: false } on any store error so callers are not blocked.
+ */
+export declare function recordMeshToolCall(opts: {
+    meshId: string;
+    tool: string;
+    sessionId?: string | null;
+    windowMs?: number;
+    maxCalls?: number;
+}): MeshToolCallRateResult;

package/dist/mesh/refine-config.d.ts

@@ -23,8 +23,18 @@ export interface RepoMeshRefineConfig {
     validation?: {
         required?: boolean;
         /**
-         * Optional dependency/bootstrap commands that Refinery runs before
-         * validation commands. Refinery never infers installs on its own.
+         * M2-2 (v2): how Refinery sources its bootstrap stage.
+         *   'inherit' (default) — consume the worktree_bootstrap config/state:
+         *     skip when the node's bootstrap is 'ready' (staleInputs unchanged),
+         *     run the worktree_bootstrap definition when stale/never-ran.
+         *   'skip' — no bootstrap stage at all (validation commands run as-is).
+         */
+        bootstrap?: 'inherit' | 'skip';
+        /**
+         * DEPRECATED (M2-2): define bootstrap once in
+         * .adhdev/worktree_bootstrap.json instead. Still honored when no
+         * worktree_bootstrap config exists, with a deprecation warning; when
+         * both exist the worktree_bootstrap config wins.
          */
         bootstrapCommands?: RepoMeshRefineValidationCommandConfig[];
         commands?: RepoMeshRefineValidationCommandConfig[];
@@ -51,9 +61,13 @@ export interface MeshRefineConfigLoadResult {
 export interface MeshRefineValidationPlan {
     source: string;
     sourceType: MeshRefineConfigLoadResult['sourceType'];
+    /** M2-2: how the bootstrap stage is sourced ('inherit' consumes worktree_bootstrap; 'skip' disables it). */
+    bootstrapMode: 'inherit' | 'skip';
     bootstrapCommands: MeshRefineValidationCommandPlan[];
     commands: MeshRefineValidationCommandPlan[];
     rejectedCommands: Array<Record<string, unknown>>;
+    /** M2-2: deprecation notices (e.g. validation.bootstrapCommands present). */
+    deprecationWarnings: string[];
     suggestions: RepoMeshRefineValidationCommandConfig[];
     suggestedConfig?: RepoMeshRefineConfig;
     unavailableReason?: string;
@@ -82,6 +96,11 @@ export declare const MESH_REFINE_CONFIG_SCHEMA: {
                     readonly type: "boolean";
                     readonly default: true;
                 };
+                readonly bootstrap: {
+                    readonly enum: readonly ["inherit", "skip"];
+                    readonly default: "inherit";
+                    readonly description: "M2-2 (v2): 'inherit' consumes the worktree_bootstrap config/state (skip when ready, rerun when stale); 'skip' disables the bootstrap stage entirely.";
+                };
                 readonly commands: {
                     readonly type: "array";
                     readonly minItems: 1;
@@ -129,6 +148,7 @@ export declare const MESH_REFINE_CONFIG_SCHEMA: {
                 readonly bootstrapCommands: {
                     readonly type: "array";
                     readonly maxItems: 4;
+                    readonly description: "DEPRECATED: define bootstrap once in .adhdev/worktree_bootstrap.json. Honored only when no worktree_bootstrap config exists (with a deprecation warning); worktree_bootstrap wins when both exist.";
                     readonly items: {
                         readonly type: "object";
                         readonly additionalProperties: false;
@@ -184,6 +204,8 @@ export declare function validateMeshRefineConfig(config: unknown, source?: strin
     bootstrapCommands: MeshRefineValidationCommandPlan[];
     commands: MeshRefineValidationCommandPlan[];
     rejectedCommands: Array<Record<string, unknown>>;
+    bootstrapMode: 'inherit' | 'skip';
+    deprecationWarnings: string[];
 };
 export declare function loadMeshRefineConfig(mesh: any, workspace: string): MeshRefineConfigLoadResult;
 export declare function suggestMeshRefineConfig(mesh: any, workspace: string): {

package/dist/mesh/worktree-bootstrap-config.d.ts

@@ -18,6 +18,15 @@ export interface WorktreeBootstrapState extends MeshAsyncJobLifecycle {
     exitCode?: number | null;
     commandsRun?: Array<Record<string, unknown>>;
     staleInputs?: string[];
+    /**
+     * M2-1: sha256 per staleInputs path recorded when the bootstrap reached
+     * 'ready'. evaluateWorktreeBootstrapState compares current file hashes
+     * against this to detect staleness (e.g. base merge changed a lockfile).
+     * Missing files hash to the literal 'absent'.
+     */
+    staleInputsDigest?: Record<string, string>;
+    /** M2-1: why an evaluated state resolved to stale (digest_mismatch | never_ran). */
+    staleReason?: string;
 }
 export interface WorktreeBootstrapConfigLoadResult {
     config?: RepoMeshWorktreeBootstrapConfig;
@@ -110,4 +119,17 @@ export declare function validateMeshWorktreeBootstrapConfig(config: unknown, sou
     rejectedCommands: Array<Record<string, unknown>>;
 };
 export declare function loadMeshWorktreeBootstrapConfig(mesh: any, workspace: string): WorktreeBootstrapConfigLoadResult;
+/** M2-1: hash staleInputs files so 'ready' can be invalidated when they change. */
+export declare function computeStaleInputsDigest(workspace: string, staleInputs: string[] | undefined): Record<string, string>;
+/**
+ * M2-1: the official bootstrap state contract. Resolves the effective state
+ * for a node workspace from config presence + the persisted last-run state +
+ * a staleInputs digest comparison. Read-only — never runs commands.
+ *
+ *   ready          — last run succeeded and staleInputs are unchanged
+ *   stale          — never ran, or a staleInputs file changed since 'ready'
+ *   running/failed — persisted lifecycle state passes through
+ *   not_configured / disabled / (invalid → failed) — from config resolution
+ */
+export declare function evaluateWorktreeBootstrapState(mesh: any, workspace: string, persisted?: WorktreeBootstrapState | null): WorktreeBootstrapState;
 export declare function runMeshWorktreeBootstrap(mesh: any, workspace: string): Promise<WorktreeBootstrapState>;

package/dist/providers/acp-provider-instance.d.ts

@@ -44,6 +44,8 @@ export declare class AcpProviderInstance implements ProviderInstance {
     private partialBlocks;
     /** Tool calls collected during current turn */
     private turnToolCalls;
+    /** Guard: prevent concurrent sendPrompt calls from racing on shared state */
+    private _sendPromptInFlight;
     private errorMessage;
     private errorReason;
     private stderrBuffer;

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

@@ -136,8 +136,16 @@ export declare class SpecDriver {
     private lastModalAt;
     /** The modal state snapshot held across busy blips. */
     private lastModalState;
+    /** Timestamp of when we last *exited* a modal state (approval/picker → idle
+     *  or directly via completion_idle_after).  Used to suppress completion_idle_after
+     *  firings that were queued before the modal appeared and expire immediately
+     *  after the modal is dismissed — without this the agent appears idle even
+     *  though it is still generating. */
+    private lastModalExitAt;
     private completionIdleFirstSeenAt;
     private completionIdleKey;
+    /** Previous screen lines — passed to evaluate() for `changed` condition detection. */
+    private prevScreenLines;
     /** Timer that re-runs evaluate() once the hold window expires. Needed
      *  because the PTY stops emitting once the agent finishes; without an
      *  explicit wake-up there's nothing to trigger the busy → idle

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

@@ -45,11 +45,10 @@ export interface SpecEvaluation {
     trace: TraceEntry[];
 }
 export declare function evaluate(spec: CliSpec, screenText: string, 
-/** Optional cursor position (0-based row and col). When supplied, states
- *  with cursor_row_min/max or cursor_col_min/max predicates are filtered.
- *  When omitted, cursor predicates are ignored and evaluation is text-only
- *  (backward-compatible with all existing specs and call sites). */
+/** Optional cursor position (0-based row and col). */
 cursor?: {
     row: number;
     col: number;
-}): SpecEvaluation;
+}, 
+/** Optional previous screen lines for `changed` condition detection. */
+prevLines?: string[]): SpecEvaluation;

package/dist/providers/spec/loader.d.ts

@@ -10,5 +10,6 @@ export interface SpecLoadError {
     sourcePath: string;
 }
 export declare function loadSpec(sourcePath: string): SpecLoadResult | SpecLoadError;
+export declare function migrateV1toV3(raw: any): any;
 /** Convenience: look up a provider's spec.json next to its provider dir. */
 export declare function resolveSpecPath(providerDir: string): string;