@karmaniverous/jeeves-meta 0.16.0 → 0.16.1

package/dist/cli/jeeves-meta/index.js

@@ -975,16 +975,20 @@ class GatewayExecutor {
                 : '';
         return text && text.trim() !== 'ANNOUNCE_SKIP' ? text : undefined;
     }
-    /** Check history messages for terminal completion. */
+    /**
+     * Check history messages for timeout detection.
+     *
+     * Does NOT determine completion — session completion is authoritative
+     * (via sessions_list). History stop reasons can false-positive on
+     * sessions_yield artifacts (#200).
+     */
     static checkHistoryCompletion(messages) {
         if (messages.length === 0)
-            return { done: false, timedOut: false };
+            return { timedOut: false };
         const last = messages[messages.length - 1];
         if (last.role !== 'assistant' || !last.stopReason)
-            return { done: false, timedOut: false };
-        if (last.stopReason === 'toolUse' || last.stopReason === 'error')
-            return { done: false, timedOut: false };
-        return { done: true, timedOut: last.stopReason === 'timeout' };
+            return { timedOut: false };
+        return { timedOut: last.stopReason === 'timeout' };
     }
     /** Invoke a gateway tool via the /tools/invoke HTTP endpoint. */
     async invoke(tool, args, sessionKey) {
@@ -1147,12 +1151,14 @@ class GatewayExecutor {
                     historyResult.result?.messages ??
                     [];
                 const msgArray = messages;
-                // Check 1: terminal stop reason in history
-                const { done: historyDone, timedOut: historyTimedOut } = GatewayExecutor.checkHistoryCompletion(msgArray);
+                // Check 1: history-based timeout detection (stop reason)
+                const { timedOut: historyTimedOut } = GatewayExecutor.checkHistoryCompletion(msgArray);
                 // Check 2: session completion status via sessions_list
+                // Gate on session completion only — history stop reasons can
+                // false-positive on sessions_yield artifacts (#200).
                 const sessionInfo = await this.getSessionInfo(sessionKey);
                 const timedOut = sessionInfo.timedOut || historyTimedOut;
-                if (historyDone || sessionInfo.completed) {
+                if (sessionInfo.completed) {
                     const tokens = sessionInfo.tokens;
                     // Gateway-side timeout detected — check staging file for recovery
                     if (timedOut) {
@@ -3167,36 +3173,33 @@ class ProgressReporter {
 }
 
 /**
- * Hybrid 3-layer synthesis queue.
+ * Synthesis queue.
  *
  * Layer 1: Current — the single item currently executing (at most one).
- * Layer 2: Overrides — items manually enqueued via POST /synthesize with path.
- *          FIFO among overrides, ahead of automatic candidates.
- * Layer 3: Automatic — computed on read, not persisted. All metas with a
- *          pending phase, ranked by scheduler priority.
- *
- * Legacy: `pending` array is the union of overrides + automatic.
+ * Layer 2: Pending — items enqueued via POST /synthesize (targeted) or
+ *          scheduler tick (automatic). FIFO, ahead of automatic candidates.
+ * Layer 3: Automatic — computed on read (GET /queue), not persisted. All
+ *          metas with a pending phase, ranked by scheduler priority.
  *
  * @module queue
  */
 const DEPTH_WARNING_THRESHOLD = 3;
+/** Strip trailing .meta suffix for consistent path comparison. */
+function normQueuePath(p) {
+    return p.endsWith('.meta') ? p.slice(0, -5).replace(/[/\\]$/, '') : p;
+}
 /**
- * Hybrid 3-layer synthesis queue.
+ * Synthesis queue.
  *
- * Only one synthesis runs at a time. Override items (explicit triggers)
- * take priority over automatic candidates.
+ * Only one synthesis runs at a time. Explicitly enqueued items
+ * take priority over automatic (computed-on-read) candidates.
  */
 class SynthesisQueue {
-    /** Legacy queue (used by processQueue for backward compat). */
-    queue = [];
-    currentItem = null;
+    entries = [];
+    currentPhaseItem = null;
     processing = false;
     logger;
     onEnqueueCallback = null;
-    /** Explicit override entries (3-layer model). */
-    overrideEntries = [];
-    /** Currently executing item with phase info (3-layer model). */
-    currentPhaseItem = null;
     constructor(logger) {
         this.logger = logger;
     }
@@ -3204,52 +3207,67 @@ class SynthesisQueue {
     onEnqueue(callback) {
         this.onEnqueueCallback = callback;
     }
-    // ── Override layer (3-layer model) ─────────────────────────────────
+    // ── Enqueue / dequeue ──────────────────────────────────────────────
     /**
-     * Add an explicit override entry (from POST /synthesize with path).
+     * Add an entry to the queue.
      * Deduped by path. Returns position and whether already queued.
      */
-    enqueueOverride(path) {
+    enqueue(path) {
+        const norm = normQueuePath(path);
         // Check if currently executing
-        if (this.currentPhaseItem?.path === path ||
-            this.currentItem?.path === path) {
+        if (this.currentPhaseItem &&
+            normQueuePath(this.currentPhaseItem.path) === norm) {
             return { position: 0, alreadyQueued: true };
         }
-        // Check if already in overrides
-        const existing = this.overrideEntries.findIndex((e) => e.path === path);
+        // Check if already in queue
+        const existing = this.entries.findIndex((e) => normQueuePath(e.path) === norm);
         if (existing !== -1) {
             return { position: existing, alreadyQueued: true };
         }
-        this.overrideEntries.push({
+        this.entries.push({
             path,
             enqueuedAt: new Date().toISOString(),
         });
-        const position = this.overrideEntries.length - 1;
-        if (this.overrideEntries.length > DEPTH_WARNING_THRESHOLD) {
-            this.logger.warn({ depth: this.overrideEntries.length }, 'Override queue depth exceeds threshold');
+        const position = this.entries.length - 1;
+        if (this.entries.length > DEPTH_WARNING_THRESHOLD) {
+            this.logger.warn({ depth: this.entries.length }, 'Queue depth exceeds threshold');
         }
         this.onEnqueueCallback?.();
         return { position, alreadyQueued: false };
     }
-    /** Dequeue the next override entry, or undefined if empty. */
-    dequeueOverride() {
-        return this.overrideEntries.shift();
+    /** Dequeue the next entry, or undefined if empty. */
+    dequeue() {
+        return this.entries.shift();
+    }
+    /** Get all queued entries (shallow copy). */
+    get items() {
+        return [...this.entries];
     }
-    /** Get all override entries (shallow copy). */
-    get overrides() {
-        return [...this.overrideEntries];
+    /** Number of items waiting in the queue (excludes current). */
+    get depth() {
+        return this.entries.length;
     }
-    /** Clear all override entries. Returns count removed. */
-    clearOverrides() {
-        const count = this.overrideEntries.length;
-        this.overrideEntries = [];
+    /**
+     * Remove all pending items from the queue.
+     * Does not affect the currently-running item.
+     *
+     * @returns The number of items removed.
+     */
+    clear() {
+        const count = this.entries.length;
+        this.entries = [];
         return count;
     }
-    /** Check if a path is in the override layer. */
-    hasOverride(path) {
-        return this.overrideEntries.some((e) => e.path === path);
+    /** Check whether a path is in the queue or currently being synthesized. */
+    has(path) {
+        const norm = normQueuePath(path);
+        if (this.currentPhaseItem &&
+            normQueuePath(this.currentPhaseItem.path) === norm) {
+            return true;
+        }
+        return this.entries.some((e) => normQueuePath(e.path) === norm);
     }
-    // ── Current-item tracking (3-layer model) ──────────────────────────
+    // ── Current-item tracking ──────────────────────────────────────────
     /** Set the currently executing phase item. */
     setCurrentPhase(path, phase) {
         this.currentPhaseItem = {
@@ -3266,129 +3284,21 @@ class SynthesisQueue {
     get currentPhase() {
         return this.currentPhaseItem;
     }
-    // ── Legacy queue interface (preserved for backward compat) ─────────
-    /**
-     * Add a path to the synthesis queue.
-     *
-     * @param path - Meta path to synthesize.
-     * @param priority - If true, insert at front of queue.
-     * @returns Position and whether the path was already queued.
-     */
-    enqueue(path, priority = false) {
-        if (this.currentItem?.path === path) {
-            return { position: 0, alreadyQueued: true };
-        }
-        const existingIndex = this.queue.findIndex((item) => item.path === path);
-        if (existingIndex !== -1) {
-            return { position: existingIndex, alreadyQueued: true };
-        }
-        const item = {
-            path,
-            priority,
-            enqueuedAt: new Date().toISOString(),
-        };
-        if (priority) {
-            this.queue.unshift(item);
-        }
-        else {
-            this.queue.push(item);
-        }
-        if (this.queue.length > DEPTH_WARNING_THRESHOLD) {
-            this.logger.warn({ depth: this.queue.length }, 'Queue depth exceeds threshold');
-        }
-        const position = this.queue.findIndex((i) => i.path === path);
-        this.onEnqueueCallback?.();
-        return { position, alreadyQueued: false };
-    }
-    /** Remove and return the next item from the queue. */
-    dequeue() {
-        const item = this.queue.shift();
-        if (item) {
-            this.currentItem = item;
-        }
-        return item;
-    }
-    /** Mark the currently-running synthesis as complete. */
-    complete() {
-        this.currentItem = null;
-    }
-    /** Number of items waiting in the queue (excludes current). */
-    get depth() {
-        return this.queue.length;
-    }
-    /** The item currently being synthesized, or null. */
-    get current() {
-        return this.currentItem;
-    }
-    /** A shallow copy of the queued items. */
-    get items() {
-        return [...this.queue];
-    }
-    /** A shallow copy of the pending items (alias for items). */
-    get pending() {
-        return [...this.queue];
-    }
-    /**
-     * Remove all pending items from the queue.
-     * Does not affect the currently-running item.
-     *
-     * @returns The number of items removed.
-     */
-    clear() {
-        const count = this.queue.length;
-        this.queue = [];
-        return count;
-    }
-    /** Check whether a path is in the queue or currently being synthesized. */
-    has(path) {
-        if (this.currentItem?.path === path)
-            return true;
-        if (this.currentPhaseItem?.path === path)
-            return true;
-        return (this.queue.some((item) => item.path === path) ||
-            this.overrideEntries.some((e) => e.path === path));
-    }
-    /** Get the 0-indexed position of a path in the queue. */
-    getPosition(path) {
-        // Check overrides first
-        const overrideIdx = this.overrideEntries.findIndex((e) => e.path === path);
-        if (overrideIdx !== -1)
-            return overrideIdx;
-        const index = this.queue.findIndex((item) => item.path === path);
-        return index === -1 ? null : index;
-    }
-    /** Dequeue the next item: overrides first, then legacy queue. */
-    nextItem() {
-        const override = this.dequeueOverride();
-        if (override)
-            return { path: override.path, source: 'override' };
-        const item = this.dequeue();
-        if (item)
-            return { path: item.path, source: 'legacy' };
-        return undefined;
-    }
+    // ── Queue state ────────────────────────────────────────────────────
     /** Return a snapshot of queue state for the /status endpoint. */
     getState() {
         return {
-            depth: this.queue.length + this.overrideEntries.length,
-            items: [
-                ...this.overrideEntries.map((e) => ({
-                    path: e.path,
-                    priority: true,
-                    enqueuedAt: e.enqueuedAt,
-                })),
-                ...this.queue.map((item) => ({
-                    path: item.path,
-                    priority: item.priority,
-                    enqueuedAt: item.enqueuedAt,
-                })),
-            ],
+            depth: this.entries.length,
+            items: this.entries.map((e) => ({
+                path: e.path,
+                enqueuedAt: e.enqueuedAt,
+            })),
         };
     }
+    // ── Processing ─────────────────────────────────────────────────────
     /**
-     * Process queued items one at a time until all queues are empty.
+     * Process queued items one at a time until the queue is empty.
      *
-     * Override entries are processed first (FIFO), then legacy queue items.
      * Re-entry is prevented: if already processing, the call returns
      * immediately. Errors are logged and do not block subsequent items.
      *
@@ -3399,7 +3309,7 @@ class SynthesisQueue {
             return;
         this.processing = true;
         try {
-            let next = this.nextItem();
+            let next = this.dequeue();
             while (next) {
                 try {
                     await synthesizeFn(next.path);
@@ -3408,9 +3318,7 @@ class SynthesisQueue {
                     this.logger.error({ path: next.path, err }, 'Synthesis failed');
                 }
                 this.clearCurrentPhase();
-                if (next.source === 'legacy')
-                    this.complete();
-                next = this.nextItem();
+                next = this.dequeue();
             }
         }
         finally {
@@ -3964,7 +3872,6 @@ class Scheduler {
             this.logger.debug({ backoffMultiplier: this.backoffMultiplier }, 'No ready phases found, increasing backoff');
             return;
         }
-        // Enqueue using the legacy queue path (backward compat with processQueue)
         this.queue.enqueue(candidate.path);
         this.logger.info({ path: candidate.path, phase: candidate.phase, band: candidate.band }, 'Enqueued phase candidate');
         // Opportunistic watcher restart detection
@@ -4563,8 +4470,8 @@ function registerPreviewRoute(app, deps) {
 /**
  * Queue management and abort routes.
  *
- * - GET /queue — 3-layer queue model (current, overrides, automatic, pending)
- * - POST /queue/clear — remove override entries only
+ * - GET /queue — 3-layer queue model (current, pending, automatic)
+ * - POST /queue/clear — remove pending entries
  * - POST /synthesize/abort — abort the current synthesis
  *
  * @module routes/queue
@@ -4574,24 +4481,24 @@ function registerQueueRoutes(app, deps) {
     const { queue } = deps;
     app.get(getEndpoint('queue').path, async () => {
         const currentPhase = queue.currentPhase;
-        const overrides = queue.overrides;
-        // Compute owedPhase for each override entry by reading meta state
-        const enrichedOverrides = await Promise.all(overrides.map(async (o) => {
+        const pending = queue.items;
+        // Compute owedPhase for each pending entry by reading meta state
+        const enrichedPending = await Promise.all(pending.map(async (entry) => {
             try {
-                const metaDir = resolveMetaDir(o.path);
+                const metaDir = resolveMetaDir(entry.path);
                 const meta = await readMetaJson(metaDir);
                 const ps = derivePhaseState(meta);
                 return {
-                    path: o.path,
+                    path: entry.path,
                     owedPhase: getOwedPhase(ps),
-                    enqueuedAt: o.enqueuedAt,
+                    enqueuedAt: entry.enqueuedAt,
                 };
             }
             catch {
                 return {
-                    path: o.path,
+                    path: entry.path,
                     owedPhase: null,
-                    enqueuedAt: o.enqueuedAt,
+                    enqueuedAt: entry.enqueuedAt,
                 };
             }
         }));
@@ -4612,21 +4519,6 @@ function registerQueueRoutes(app, deps) {
         catch {
             // If listing fails, automatic stays empty
         }
-        // Legacy: pending is the union of overrides + automatic + legacy queue items
-        const pendingItems = [
-            ...enrichedOverrides.map((o) => ({
-                path: o.path,
-                owedPhase: o.owedPhase,
-            })),
-            ...automatic.map((a) => ({
-                path: a.path,
-                owedPhase: a.owedPhase,
-            })),
-            ...queue.pending.map((item) => ({
-                path: item.path,
-                owedPhase: null,
-            })),
-        ];
         return {
             current: currentPhase
                 ? {
@@ -4634,58 +4526,45 @@ function registerQueueRoutes(app, deps) {
                     phase: currentPhase.phase,
                     startedAt: currentPhase.startedAt,
                 }
-                : queue.current
-                    ? {
-                        path: queue.current.path,
-                        phase: null,
-                        startedAt: queue.current.enqueuedAt,
-                    }
-                    : null,
-            overrides: enrichedOverrides,
+                : null,
+            pending: enrichedPending,
             automatic,
-            pending: pendingItems,
-            // Legacy state
-            state: queue.getState(),
         };
     });
     app.post(getEndpoint('queueClear').path, () => {
-        const removed = queue.clearOverrides();
+        const removed = queue.clear();
         return { cleared: removed };
     });
     app.post(getEndpoint('abort').path, async (_request, reply) => {
-        // Check 3-layer current first
         const currentPhase = queue.currentPhase;
-        const current = currentPhase ?? queue.current;
-        if (!current) {
+        if (!currentPhase) {
             return reply.status(200).send({ status: 'idle' });
         }
         // Abort the executor
         deps.executor?.abort();
-        const metaDir = resolveMetaDir(current.path);
-        const phase = currentPhase?.phase ?? null;
+        const metaDir = resolveMetaDir(currentPhase.path);
+        const { phase } = currentPhase;
         // Transition running phase to failed and write _error to meta.json
-        if (phase) {
-            try {
-                const meta = await readMetaJson(metaDir);
-                let ps = derivePhaseState(meta);
-                ps = phaseFailed(ps, phase);
-                const updated = {
-                    ...meta,
-                    _phaseState: ps,
-                    _error: {
-                        step: phase,
-                        code: 'ABORT',
-                        message: 'Aborted by operator',
-                    },
-                };
-                const lockPath = join(metaDir, '.lock');
-                const metaJsonPath = join(metaDir, 'meta.json');
-                await writeFile(lockPath, JSON.stringify(updated, null, 2) + '\n');
-                await copyFile(lockPath, metaJsonPath);
-            }
-            catch {
-                // Best-effort — meta may be unreadable
-            }
+        try {
+            const meta = await readMetaJson(metaDir);
+            let ps = derivePhaseState(meta);
+            ps = phaseFailed(ps, phase);
+            const updated = {
+                ...meta,
+                _phaseState: ps,
+                _error: {
+                    step: phase,
+                    code: 'ABORT',
+                    message: 'Aborted by operator',
+                },
+            };
+            const lockPath = join(metaDir, '.lock');
+            const metaJsonPath = join(metaDir, 'meta.json');
+            await writeFile(lockPath, JSON.stringify(updated, null, 2) + '\n');
+            await copyFile(lockPath, metaJsonPath);
+        }
+        catch {
+            // Best-effort — meta may be unreadable
         }
         // Release the lock for the current meta path
         try {
@@ -4694,11 +4573,11 @@ function registerQueueRoutes(app, deps) {
         catch {
             // Lock may already be released
         }
-        deps.logger.info({ path: current.path }, 'Synthesis aborted');
+        deps.logger.info({ path: currentPhase.path }, 'Synthesis aborted');
         return {
             status: 'aborted',
-            path: current.path,
-            ...(phase ? { phase } : {}),
+            path: currentPhase.path,
+            phase,
         };
     });
 }
@@ -4809,9 +4688,9 @@ async function checkWatcher(url) {
 function deriveServiceState(deps) {
     if (deps.shuttingDown)
         return 'stopping';
-    if (deps.queue.current || deps.queue.currentPhase)
+    if (deps.queue.currentPhase)
         return 'synthesizing';
-    if (deps.queue.depth > 0 || deps.queue.overrides.length > 0)
+    if (deps.queue.depth > 0)
         return 'waiting';
     return 'idle';
 }
@@ -4863,7 +4742,7 @@ function registerStatusRoute(app, deps) {
             }
             return {
                 serviceState: deriveServiceState(deps),
-                currentTarget: queue.current?.path ?? queue.currentPhase?.path ?? null,
+                currentTarget: queue.currentPhase?.path ?? null,
                 queue: queue.getState(),
                 stats: {
                     totalSyntheses: stats.totalSyntheses,
@@ -4951,7 +4830,7 @@ function registerSynthesizeRoute(app, deps) {
                     alreadyQueued: false,
                 });
             }
-            const result = queue.enqueueOverride(targetPath);
+            const result = queue.enqueue(targetPath);
             return reply.code(202).send({
                 status: 'queued',
                 path: targetPath,
@@ -4982,8 +4861,9 @@ function registerSynthesizeRoute(app, deps) {
         const stalest = winner.node.metaPath;
         const enqueueResult = queue.enqueue(stalest);
         return reply.code(202).send({
-            status: 'accepted',
+            status: 'queued',
             path: stalest,
+            owedPhase: winner.owedPhase,
             queuePosition: enqueueResult.position,
             alreadyQueued: enqueueResult.alreadyQueued,
         });
@@ -5132,26 +5012,14 @@ function registerShutdownHandlers(deps) {
             deps.logger.info('Scheduler stopped');
         }
         // 2. Release lock for in-progress synthesis
-        const current = deps.queue.current;
-        if (current) {
-            try {
-                releaseLock(current.path);
-                deps.logger.info({ path: current.path }, 'Released lock for in-progress synthesis');
-            }
-            catch {
-                deps.logger.warn({ path: current.path }, 'Failed to release lock during shutdown');
-            }
-        }
-        // Release lock for in-progress override synthesis (only when it
-        // differs from the legacy current item to avoid double-release)
         const currentPhase = deps.queue.currentPhase;
-        if (currentPhase && currentPhase.path !== current?.path) {
+        if (currentPhase) {
             try {
                 releaseLock(resolveMetaDir(currentPhase.path));
-                deps.logger.info({ path: currentPhase.path }, 'Released lock for in-progress override synthesis');
+                deps.logger.info({ path: currentPhase.path }, 'Released lock for in-progress synthesis');
             }
             catch {
-                deps.logger.warn({ path: currentPhase.path }, 'Failed to release override lock during shutdown');
+                deps.logger.warn({ path: currentPhase.path }, 'Failed to release lock during shutdown');
             }
         }
         // 3. Close server

package/dist/executor/GatewayExecutor.d.ts

@@ -40,7 +40,13 @@ export declare class GatewayExecutor implements MetaExecutor {
     private readStagingFile;
     /** Extract plain text from a message content field, skipping ANNOUNCE_SKIP sentinels. */
     private static extractMessageText;
-    /** Check history messages for terminal completion. */
+    /**
+     * Check history messages for timeout detection.
+     *
+     * Does NOT determine completion — session completion is authoritative
+     * (via sessions_list). History stop reasons can false-positive on
+     * sessions_yield artifacts (#200).
+     */
     private static checkHistoryCompletion;
     /** Invoke a gateway tool via the /tools/invoke HTTP endpoint. */
     private invoke;

package/dist/index.d.ts

@@ -23,7 +23,7 @@ export { formatProgressEvent, type ProgressEvent, type ProgressPhase, ProgressRe
 export { actualStaleness, computeEffectiveStaleness, hasSteerChanged, isArchitectTriggered, isStale, MAX_STALENESS_SECONDS, type StalenessCandidate, } from './scheduling/index.js';
 export { type MetaConfig, metaConfigSchema, type MetaError, metaErrorSchema, type MetaJson, metaJsonSchema, type ServiceConfig, serviceConfigSchema, } from './schema/index.js';
 export { Scheduler } from './scheduler/index.js';
-export { type EnqueueResult, type QueueItem, type QueueState, SynthesisQueue, } from './queue/index.js';
+export { type CurrentItem, type EnqueueResult, type QueueEntry, type QueueState, SynthesisQueue, } from './queue/index.js';
 export { registerRoutes, type RouteDeps, type ServiceStats, } from './routes/index.js';
 export { RuleRegistrar } from './rules/index.js';
 export { verifyRuleApplication } from './rules/verify.js';