@karmaniverous/jeeves-meta 0.14.0 → 0.15.1

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

@@ -8917,22 +8917,6 @@ async function isStale(scopePrefix, meta, watcher) {
 }
 /** Maximum staleness for never-synthesized metas (1 year in seconds). */
 const MAX_STALENESS_SECONDS = 365 * 86_400;
-/**
- * Compute actual staleness in seconds (now minus _generatedAt).
- *
- * Never-synthesized metas are capped at {@link MAX_STALENESS_SECONDS}
- * (1 year) so that depth weighting can differentiate them. Without
- * bounding, `Infinity * depthFactor` = `Infinity` for all depths.
- *
- * @param meta - Current meta.json content.
- * @returns Staleness in seconds, capped at 1 year for never-synthesized metas.
- */
-function actualStaleness(meta) {
-    if (!meta._generatedAt)
-        return MAX_STALENESS_SECONDS;
-    const generatedMs = new Date(meta._generatedAt).getTime();
-    return Math.min((Date.now() - generatedMs) / 1000, MAX_STALENESS_SECONDS);
-}
 /**
  * Check whether the architect step should be triggered.
  *
@@ -9307,12 +9291,12 @@ class GatewayExecutor {
         return data;
     }
     /** Look up totalTokens for a session via sessions_list. */
-    async getSessionTokens(sessionKey, invokeSessionKey) {
+    async getSessionTokens(sessionKey) {
         try {
             const result = await this.invoke('sessions_list', {
                 limit: 20,
                 messageLimit: 0,
-            }, invokeSessionKey);
+            });
             const sessions = (result.result?.details?.sessions ??
                 result.result?.sessions ??
                 []);
@@ -9323,6 +9307,10 @@ class GatewayExecutor {
             return undefined;
         }
     }
+    /** Whether this executor has been aborted by the operator. */
+    get aborted() {
+        return this.controller.signal.aborted;
+    }
     /** Abort the currently running spawn, if any. */
     abort() {
         this.controller.abort();
@@ -9340,7 +9328,6 @@ class GatewayExecutor {
         // Generate unique output path for file-based output
         const outputId = randomUUID();
         const outputPath = this.workspaceDir + '/output-' + outputId + '.json';
-        const invokeSessionKey = 'agent:main:meta-invoke:' + outputId;
         // Append file output instruction to the task
         const taskWithOutput = task +
             '\n\n## OUTPUT DELIVERY\n\n' +
@@ -9358,7 +9345,7 @@ class GatewayExecutor {
             runTimeoutSeconds: timeoutSeconds,
             ...(options?.thinking ? { thinking: options.thinking } : {}),
             ...(options?.model ? { model: options.model } : {}),
-        }, invokeSessionKey);
+        });
         const details = (spawnResult.result?.details ?? spawnResult.result);
         const sessionKey = details?.childSessionKey ?? details?.sessionKey;
         if (typeof sessionKey !== 'string' || !sessionKey) {
@@ -9378,7 +9365,7 @@ class GatewayExecutor {
                     sessionKey,
                     limit: 5,
                     includeTools: false,
-                }, invokeSessionKey);
+                });
                 const messages = historyResult.result?.details?.messages ??
                     historyResult.result?.messages ??
                     [];
@@ -9391,7 +9378,7 @@ class GatewayExecutor {
                         lastMsg.stopReason !== 'toolUse' &&
                         lastMsg.stopReason !== 'error') {
                         // Fetch token usage from session metadata
-                        const tokens = await this.getSessionTokens(sessionKey, invokeSessionKey);
+                        const tokens = await this.getSessionTokens(sessionKey);
                         // Read output from file (sub-agent wrote it via Write tool)
                         if (existsSync(outputPath)) {
                             try {
@@ -9941,26 +9928,6 @@ function buildCriticTask(ctx, meta, config) {
     return compileTemplate(sections.join('\n'), buildTemplateContext(ctx, meta, config));
 }
 
-/**
- * Exponential moving average helper for token tracking.
- *
- * @module ema
- */
-const DEFAULT_DECAY = 0.3;
-/**
- * Compute exponential moving average.
- *
- * @param current - New observation.
- * @param previous - Previous EMA value, or undefined for first observation.
- * @param decay - Decay factor (0-1). Higher = more weight on new value. Default 0.3.
- * @returns Updated EMA.
- */
-function computeEma(current, previous, decay = DEFAULT_DECAY) {
-    if (previous === undefined)
-        return current;
-    return decay * current + (1 - decay) * previous;
-}
-
 /**
  * Structured error from a synthesis step failure.
  *
@@ -9984,8 +9951,24 @@ const metaErrorSchema = z.object({
  *
  * @module schema/meta
  */
+/** Valid states for a synthesis phase. */
+const phaseStatuses = [
+    'fresh',
+    'stale',
+    'pending',
+    'running',
+    'failed',
+];
+/** Zod schema for a per-phase status value. */
+const phaseStatusSchema = z.enum(phaseStatuses);
+/** Zod schema for the per-meta phase state record. */
+const phaseStateSchema = z.object({
+    architect: phaseStatusSchema,
+    builder: phaseStatusSchema,
+    critic: phaseStatusSchema,
+});
 /** Zod schema for the reserved (underscore-prefixed) meta.json properties. */
-const metaJsonSchema = z
+z
     .object({
     /** Stable identity. Auto-generated on first synthesis if not provided. */
     _id: z.uuid().optional(),
@@ -10064,105 +10047,15 @@ const metaJsonSchema = z
     _error: metaErrorSchema.optional(),
     /** When true, this meta is skipped during staleness scheduling. Manual trigger still works. */
     _disabled: z.boolean().optional(),
+    /**
+     * Per-phase state machine record. Engine-managed.
+     * Keyed by phase name (architect, builder, critic) with status values.
+     * Persisted to survive ticks; derived on first load for back-compat.
+     */
+    _phaseState: phaseStateSchema.optional(),
 })
     .loose();
 
-/**
- * Merge synthesis results into meta.json.
- *
- * Preserves human-set fields (_id, _steer, _depth).
- * Writes engine fields (_generatedAt, _structureHash, etc.).
- * Validates against schema before writing.
- *
- * @module orchestrator/merge
- */
-/**
- * Merge results into meta.json and write atomically.
- *
- * @param options - Merge options.
- * @returns The updated MetaJson.
- * @throws If validation fails (malformed output).
- */
-async function mergeAndWrite(options) {
-    const merged = {
-        // Preserve human-set fields (auto-generate _id on first synthesis)
-        _id: options.current._id ?? randomUUID(),
-        _steer: options.current._steer,
-        _depth: options.current._depth,
-        _emphasis: options.current._emphasis,
-        // Engine fields
-        _architect: options.architect,
-        _builder: options.builder,
-        _critic: options.critic,
-        _generatedAt: options.stateOnly
-            ? options.current._generatedAt
-            : new Date().toISOString(),
-        _structureHash: options.structureHash,
-        _synthesisCount: options.synthesisCount,
-        // Token tracking
-        _architectTokens: options.architectTokens,
-        _builderTokens: options.builderTokens,
-        _criticTokens: options.criticTokens,
-        _architectTokensAvg: options.architectTokens !== undefined
-            ? computeEma(options.architectTokens, options.current._architectTokensAvg)
-            : options.current._architectTokensAvg,
-        _builderTokensAvg: options.builderTokens !== undefined
-            ? computeEma(options.builderTokens, options.current._builderTokensAvg)
-            : options.current._builderTokensAvg,
-        _criticTokensAvg: options.criticTokens !== undefined
-            ? computeEma(options.criticTokens, options.current._criticTokensAvg)
-            : options.current._criticTokensAvg,
-        // Content from builder (stateOnly preserves previous content)
-        _content: options.stateOnly
-            ? options.current._content
-            : (options.builderOutput?.content ?? options.current._content),
-        // Feedback from critic
-        _feedback: options.feedback ?? options.current._feedback,
-        // Progressive state
-        _state: options.state,
-        // Error handling
-        _error: options.error ?? undefined,
-        // Spread structured fields from builder
-        ...options.builderOutput?.fields,
-    };
-    // Clean up undefined optional fields
-    if (merged._steer === undefined)
-        delete merged._steer;
-    if (merged._depth === undefined)
-        delete merged._depth;
-    if (merged._emphasis === undefined)
-        delete merged._emphasis;
-    if (merged._architectTokens === undefined)
-        delete merged._architectTokens;
-    if (merged._builderTokens === undefined)
-        delete merged._builderTokens;
-    if (merged._criticTokens === undefined)
-        delete merged._criticTokens;
-    if (merged._architectTokensAvg === undefined)
-        delete merged._architectTokensAvg;
-    if (merged._builderTokensAvg === undefined)
-        delete merged._builderTokensAvg;
-    if (merged._criticTokensAvg === undefined)
-        delete merged._criticTokensAvg;
-    if (merged._state === undefined)
-        delete merged._state;
-    if (merged._error === undefined)
-        delete merged._error;
-    if (merged._content === undefined)
-        delete merged._content;
-    if (merged._feedback === undefined)
-        delete merged._feedback;
-    // Validate
-    const result = metaJsonSchema.safeParse(merged);
-    if (!result.success) {
-        throw new Error(`Meta validation failed: ${result.error.message}`);
-    }
-    // Write to specified path (lock staging) or default meta.json
-    const filePath = options.outputPath ?? join(options.metaPath, 'meta.json');
-    await writeFile(filePath, JSON.stringify(result.data, null, 2) + '\n');
-    return result.data;
-}
-
 /**
  * Build a minimal MetaNode from a known meta path using watcher walk.
  *
@@ -10343,43 +10236,6 @@ function computeStructureHash(filePaths) {
     return createHash('sha256').update(content).digest('hex');
 }
 
-/**
- * Lock-staged cycle finalization: write to .lock, copy to meta.json, archive, prune.
- *
- * @module orchestrator/finalizeCycle
- */
-/** Finalize a cycle using lock staging: write to .lock → copy to meta.json + archive → delete .lock. */
-async function finalizeCycle(opts) {
-    const lockPath = join(opts.metaPath, '.lock');
-    const metaJsonPath = join(opts.metaPath, 'meta.json');
-    // Stage: write merged result to .lock (sequential — ordering matters)
-    const updated = await mergeAndWrite({
-        metaPath: opts.metaPath,
-        current: opts.current,
-        architect: opts.architect,
-        builder: opts.builder,
-        critic: opts.critic,
-        builderOutput: opts.builderOutput,
-        feedback: opts.feedback,
-        structureHash: opts.structureHash,
-        synthesisCount: opts.synthesisCount,
-        error: opts.error,
-        architectTokens: opts.architectTokens,
-        builderTokens: opts.builderTokens,
-        criticTokens: opts.criticTokens,
-        outputPath: lockPath,
-        state: opts.state,
-        stateOnly: opts.stateOnly,
-    });
-    // Commit: copy .lock → meta.json
-    await copyFile(lockPath, metaJsonPath);
-    // Archive + prune from the committed meta.json (sequential)
-    await createSnapshot(opts.metaPath, updated);
-    await pruneArchive(opts.metaPath, opts.config.maxArchive);
-    // .lock is cleaned up by the finally block (releaseLock)
-    return updated;
-}
-
 /**
  * Parse subprocess outputs for each synthesis step.
  *
@@ -10478,162 +10334,441 @@ function parseCriticOutput(output) {
 }
 
 /**
- * Timeout recovery — salvage partial builder state after a SpawnTimeoutError.
+ * Pure phase-state transition functions.
+ *
+ * Implements every row of the §8 "Transitions and invalidation cascade" table.
+ * No I/O — pure functions over PhaseState and documented inputs.
  *
- * @module orchestrator/timeoutRecovery
+ * @module phaseState/phaseTransitions
+ */
+/**
+ * Create a fresh (fully-complete) phase state.
+ */
+function freshPhaseState() {
+    return { architect: 'fresh', builder: 'fresh', critic: 'fresh' };
+}
+/**
+ * Create a phase state for a never-synthesized meta (all pending from architect).
  */
+function initialPhaseState() {
+    return { architect: 'pending', builder: 'stale', critic: 'stale' };
+}
 /**
- * Attempt to recover partial state from a timed-out builder spawn.
+ * Enforce the per-meta invariant: at most one phase is pending or running,
+ * and it is the first non-fresh phase in pipeline order.
  *
- * Returns an {@link OrchestrateResult} if state was salvaged, or `null`
- * if the caller should fall through to a hard failure.
+ * Stale phases that become the first non-fresh phase are promoted to pending.
  */
-async function attemptTimeoutRecovery(opts) {
-    const { err, currentMeta, metaPath, config, builderBrief, structureHash, synthesisCount, } = opts;
-    let partialOutput = null;
-    try {
-        const raw = await readFile(err.outputPath, 'utf8');
-        partialOutput = parseBuilderOutput(raw);
+function enforceInvariant(state) {
+    const result = { ...state };
+    let foundNonFresh = false;
+    for (const phase of ['architect', 'builder', 'critic']) {
+        const s = result[phase];
+        if (s === 'fresh')
+            continue;
+        if (!foundNonFresh) {
+            foundNonFresh = true;
+            // First non-fresh: if stale, promote to pending
+            if (s === 'stale') {
+                result[phase] = 'pending';
+            }
+            // pending, running, failed stay as-is
+        }
+        else {
+            // Subsequent non-fresh: must not be pending or running
+            if (s === 'pending') {
+                result[phase] = 'stale';
+            }
+            // running in non-first position would be a bug, but don't mask it
+        }
     }
-    catch {
-        // Could not read partial output — fall through to hard failure
-    }
-    if (partialOutput?.state !== undefined) {
-        const currentState = JSON.stringify(currentMeta._state);
-        const newState = JSON.stringify(partialOutput.state);
-        if (newState !== currentState) {
-            const timeoutError = {
-                step: 'builder',
-                code: 'TIMEOUT',
-                message: err.message,
-            };
-            await finalizeCycle({
-                metaPath,
-                current: currentMeta,
-                config,
-                architect: currentMeta._architect ?? '',
-                builder: builderBrief,
-                critic: currentMeta._critic ?? '',
-                builderOutput: null,
-                feedback: null,
-                structureHash,
-                synthesisCount,
-                error: timeoutError,
-                state: partialOutput.state,
-                stateOnly: true,
-            });
-            return {
-                synthesized: true,
-                metaPath,
-                error: timeoutError,
-            };
+    return result;
+}
+// ── Phase success transitions ──────────────────────────────────────────
+/**
+ * Architect completes successfully.
+ * architect → fresh; builder → pending; critic → stale.
+ */
+function architectSuccess(state) {
+    return enforceInvariant({
+        architect: 'fresh',
+        builder: state.builder === 'failed' ? 'failed' : 'pending',
+        critic: state.critic === 'fresh' ? 'stale' : state.critic,
+    });
+}
+/**
+ * Builder completes successfully.
+ * builder → fresh; critic → pending.
+ */
+function builderSuccess(state) {
+    return enforceInvariant({
+        ...state,
+        builder: 'fresh',
+        critic: state.critic === 'failed' ? 'failed' : 'pending',
+    });
+}
+/**
+ * Critic completes successfully.
+ * critic → fresh. Meta becomes fully fresh.
+ */
+function criticSuccess(state) {
+    return enforceInvariant({
+        ...state,
+        critic: 'fresh',
+    });
+}
+// ── Failure transition ─────────────────────────────────────────────────
+/**
+ * A phase fails (error, timeout, or abort).
+ * Target phase → failed; upstream and downstream unchanged.
+ */
+function phaseFailed(state, phase) {
+    return enforceInvariant({
+        ...state,
+        [phase]: 'failed',
+    });
+}
+// ── Surgical retry ─────────────────────────────────────────────────────
+/**
+ * Retry a failed phase: failed → pending.
+ * Only valid when the phase is currently failed.
+ */
+function retryPhase(state, phase) {
+    if (state[phase] !== 'failed')
+        return state;
+    return enforceInvariant({
+        ...state,
+        [phase]: 'pending',
+    });
+}
+/**
+ * Retry all failed phases: each failed phase → pending.
+ * Used by scheduler ticks and queue reads to auto-promote failed phases.
+ */
+function retryAllFailed(state) {
+    let result = state;
+    for (const phase of ['architect', 'builder', 'critic']) {
+        if (result[phase] === 'failed') {
+            result = retryPhase(result, phase);
         }
     }
+    return result;
+}
+// ── Running transition ─────────────────────────────────────────────────
+/**
+ * Mark a phase as running (scheduler picks it).
+ */
+function phaseRunning(state, phase) {
+    return {
+        ...state,
+        [phase]: 'running',
+    };
+}
+// ── Query helpers ──────────────────────────────────────────────────────
+/**
+ * Get the owed phase: first non-fresh phase in pipeline order, or null.
+ */
+function getOwedPhase(state) {
+    for (const phase of ['architect', 'builder', 'critic']) {
+        if (state[phase] !== 'fresh')
+            return phase;
+    }
     return null;
 }
+/**
+ * Check if a meta is fully fresh (all phases fresh).
+ */
+function isFullyFresh(state) {
+    return (state.architect === 'fresh' &&
+        state.builder === 'fresh' &&
+        state.critic === 'fresh');
+}
+/**
+ * Get the scheduler priority band for a meta's owed phase.
+ * 1 = critic (highest), 2 = builder, 3 = architect, null = fully fresh.
+ */
+function getPriorityBand(state) {
+    const owed = getOwedPhase(state);
+    if (!owed)
+        return null;
+    if (owed === 'critic')
+        return 1;
+    if (owed === 'builder')
+        return 2;
+    return 3;
+}
 
 /**
- * Single-node synthesis pipeline — architect, builder, critic.
+ * Backward-compatible derivation of _phaseState from existing meta fields.
  *
- * @module orchestrator/synthesizeNode
+ * When a meta is loaded from disk without _phaseState, this reconstructs
+ * the phase state from _content, _builder, _state, _error.step, and
+ * the architect-invalidating inputs.
+ *
+ * @module phaseState/derivePhaseState
  */
-/** Run the architect/builder/critic pipeline on a single node. */
-async function synthesizeNode(node, currentMeta, config, executor, watcher, onProgress, logger) {
-    // Step 5-6: Steer change detection
-    const latestArchive = await readLatestArchive(node.metaPath);
-    const steerChanged = hasSteerChanged(currentMeta._steer, latestArchive?._steer, Boolean(latestArchive));
-    // Step 7: Compute context (includes scope files and delta files)
-    const ctx = await buildContextPackage(node, currentMeta, watcher, logger);
-    // Skip empty-scope entities that have no prior content.
-    // Without scope files, child metas, or cross-refs there is nothing for
-    // the architect/builder to work with and the cycle will either time out
-    // or produce empty output.
-    const hasScope = ctx.scopeFiles.length > 0 ||
-        Object.keys(ctx.childMetas).length > 0 ||
-        Object.keys(ctx.crossRefMetas).length > 0;
-    if (!hasScope && !currentMeta._content) {
-        // Bump _generatedAt so this entity doesn't keep winning the staleness
-        // race every cycle. It will be re-evaluated when files appear.
-        // Uses lock-staging for atomic write consistency.
-        currentMeta._generatedAt = new Date().toISOString();
-        const lockPath = join(node.metaPath, '.lock');
-        const metaJsonPath = join(node.metaPath, 'meta.json');
-        await writeFile(lockPath, JSON.stringify(currentMeta, null, 2));
-        await copyFile(lockPath, metaJsonPath);
-        logger?.debug({ path: node.ownerPath }, 'Skipping empty-scope entity');
-        return { synthesized: false };
-    }
-    // Step 5 (deferred): Structure hash from context scope files
-    const newStructureHash = computeStructureHash(ctx.scopeFiles);
-    const structureChanged = newStructureHash !== currentMeta._structureHash;
-    // Step 8: Architect (conditional)
-    const architectTriggered = isArchitectTriggered(currentMeta, structureChanged, steerChanged, config.architectEvery);
-    let builderBrief = currentMeta._builder ?? '';
-    let synthesisCount = currentMeta._synthesisCount ?? 0;
-    let stepError = null;
-    let architectTokens;
-    let builderTokens;
-    let criticTokens;
-    // Shared base options for all finalizeCycle calls.
-    // Note: synthesisCount is excluded because it mutates during the pipeline.
-    const baseFinalizeOptions = {
-        metaPath: node.metaPath,
-        current: currentMeta,
-        config,
-        architect: currentMeta._architect ?? '',
-        critic: currentMeta._critic ?? '',
-        structureHash: newStructureHash,
-    };
-    if (architectTriggered) {
-        try {
-            await onProgress?.({
-                type: 'phase_start',
-                path: node.ownerPath,
-                phase: 'architect',
-            });
-            const phaseStart = Date.now();
-            const architectTask = buildArchitectTask(ctx, currentMeta, config);
-            const architectResult = await executor.spawn(architectTask, {
-                thinking: config.thinking,
-                timeout: config.architectTimeout,
-                label: 'meta-architect',
-            });
-            builderBrief = parseArchitectOutput(architectResult.output);
-            architectTokens = architectResult.tokens;
-            synthesisCount = 0;
-            await onProgress?.({
-                type: 'phase_complete',
-                path: node.ownerPath,
-                phase: 'architect',
-                tokens: architectTokens,
-                durationMs: Date.now() - phaseStart,
-            });
-        }
-        catch (err) {
-            stepError = toMetaError('architect', err);
-            if (!currentMeta._builder) {
-                // No cached builder — cycle fails
-                await finalizeCycle({
-                    ...baseFinalizeOptions,
-                    builder: '',
-                    builderOutput: null,
-                    feedback: null,
-                    synthesisCount,
-                    error: stepError,
-                    architectTokens,
-                });
-                return {
-                    synthesized: true,
-                    metaPath: node.metaPath,
-                    error: stepError,
-                };
+/**
+ * Derive _phaseState from existing meta fields.
+ *
+ * If the meta already has _phaseState, returns it as-is.
+ *
+ * Otherwise, reconstructs from available fields:
+ * - Never-synthesized meta (no _content, no _builder): all phases start pending/stale.
+ * - Errored meta: the failed phase is mapped from _error.step.
+ * - Mid-cycle meta with cached _builder but no _content: builder pending.
+ * - Fully-fresh meta: all phases fresh.
+ * - Meta with stale architect inputs: architect pending, downstream stale.
+ *
+ * @param meta - The meta.json content.
+ * @param inputs - Optional derivation inputs. If not provided, a simpler
+ *   heuristic is used (no architect invalidation check).
+ * @returns The derived PhaseState.
+ */
+function derivePhaseState(meta, inputs) {
+    // Already has _phaseState — use it
+    if (meta._phaseState)
+        return meta._phaseState;
+    // Check for errors first — _error.step maps directly to failed phase
+    if (meta._error) {
+        const failedPhase = meta._error.step;
+        const state = freshPhaseState();
+        state[failedPhase] = 'failed';
+        // If architect failed and no _builder, downstream is stale
+        if (failedPhase === 'architect') {
+            if (!meta._builder) {
+                state.builder = 'stale';
+                state.critic = 'stale';
             }
-            // Has cached builder — continue with existing
         }
+        // If builder failed, critic is stale
+        if (failedPhase === 'builder') {
+            state.critic = 'stale';
+        }
+        return state;
+    }
+    // Never synthesized: no _content AND no _builder (and no error)
+    if (!meta._content && !meta._builder) {
+        return initialPhaseState();
+    }
+    // Check architect invalidation (when inputs are provided)
+    if (inputs) {
+        const architectInvalidated = inputs.structureChanged ||
+            inputs.steerChanged ||
+            inputs.architectChanged ||
+            inputs.crossRefsChanged ||
+            (meta._synthesisCount ?? 0) >= inputs.architectEvery;
+        if (architectInvalidated) {
+            return {
+                architect: 'pending',
+                builder: 'stale',
+                critic: 'stale',
+            };
+        }
+    }
+    // Has _builder but no _content: builder is pending
+    if (meta._builder && !meta._content) {
+        return {
+            architect: 'fresh',
+            builder: 'pending',
+            critic: 'stale',
+        };
     }
-    // Step 9: Builder
-    const metaForBuilder = { ...currentMeta, _builder: builderBrief };
-    let builderOutput;
+    // Has _content but no _feedback: critic is pending
+    if (meta._content && !meta._feedback) {
+        return {
+            architect: 'fresh',
+            builder: 'fresh',
+            critic: 'pending',
+        };
+    }
+    // Default: fully fresh
+    return freshPhaseState();
+}
+
+/**
+ * Corpus-wide phase scheduler.
+ *
+ * Selects the highest-priority ready phase across all metas.
+ * Priority: critic (band 1) \> builder (band 2) \> architect (band 3).
+ * Tiebreak within band: weighted staleness (§3.9).
+ *
+ * @module phaseState/phaseScheduler
+ */
+/**
+ * Build phase candidates from listMetas entries.
+ *
+ * Derives phase state and auto-retries failed phases for each entry.
+ * Used by orchestratePhase, queue route, and status route.
+ */
+function buildPhaseCandidates(entries) {
+    return entries.map((entry) => ({
+        node: entry.node,
+        meta: entry.meta,
+        phaseState: retryAllFailed(derivePhaseState(entry.meta)),
+        actualStaleness: entry.stalenessSeconds,
+        locked: entry.locked,
+        disabled: entry.disabled,
+    }));
+}
+/**
+ * Rank all eligible phase candidates by priority.
+ *
+ * Filters to pending phases, computes effective staleness, and sorts by
+ * band (ascending: critic first) then effective staleness (descending).
+ *
+ * Used by selectPhaseCandidate (returns first) and the queue route (returns all).
+ */
+function rankPhaseCandidates(metas, depthWeight) {
+    // Filter to metas with a pending (scheduler-eligible) phase
+    const eligible = metas.filter((m) => {
+        if (m.locked)
+            return false;
+        if (m.disabled && !m.isOverride)
+            return false;
+        const owed = getOwedPhase(m.phaseState);
+        if (!owed)
+            return false;
+        return m.phaseState[owed] === 'pending';
+    });
+    if (eligible.length === 0)
+        return [];
+    // Compute effective staleness for tiebreaking
+    const withStaleness = computeEffectiveStaleness(eligible.map((m) => ({
+        node: m.node,
+        meta: m.meta,
+        actualStaleness: m.actualStaleness,
+    })), depthWeight);
+    // Build candidates with band info
+    const candidates = withStaleness.map((ws, i) => {
+        const m = eligible[i];
+        const owedPhase = getOwedPhase(m.phaseState);
+        return {
+            node: ws.node,
+            meta: ws.meta,
+            phaseState: m.phaseState,
+            owedPhase,
+            band: getPriorityBand(m.phaseState),
+            actualStaleness: ws.actualStaleness,
+            effectiveStaleness: ws.effectiveStaleness,
+        };
+    });
+    // Sort by band (ascending = critic first) then effective staleness (descending)
+    candidates.sort((a, b) => {
+        if (a.band !== b.band)
+            return a.band - b.band;
+        return b.effectiveStaleness - a.effectiveStaleness;
+    });
+    return candidates;
+}
+/**
+ * Select the best phase candidate across the corpus.
+ *
+ * @param metas - Array of (node, meta, phaseState, stalenessSeconds) tuples.
+ * @param depthWeight - Config depthWeight for staleness tiebreak.
+ * @returns The winning candidate, or null if no phase is ready.
+ */
+function selectPhaseCandidate(metas, depthWeight) {
+    return rankPhaseCandidates(metas, depthWeight)[0] ?? null;
+}
+
+/**
+ * Per-phase executors for the phase-state machine.
+ *
+ * Each function runs exactly one phase on one meta, updates _phaseState
+ * via pure transitions, and persists via the lock-staged write.
+ *
+ * @module orchestrator/runPhase
+ */
+/** Write updated meta with phase state via lock staging. */
+async function persistPhaseState(base, phaseState, updates) {
+    const lockPath = join(base.metaPath, '.lock');
+    const metaJsonPath = join(base.metaPath, 'meta.json');
+    const merged = {
+        ...base.current,
+        ...updates,
+        _phaseState: phaseState,
+        _structureHash: base.structureHash,
+    };
+    // Clean undefined
+    if (merged._error === undefined)
+        delete merged._error;
+    await writeFile(lockPath, JSON.stringify(merged, null, 2) + '\n');
+    await copyFile(lockPath, metaJsonPath);
+    return merged;
+}
+/**
+ * Handle phase failure (abort or error).
+ *
+ * Shared error path for all three phase executors. When the executor was
+ * aborted, returns immediately without persisting (abort route handles it).
+ * Otherwise, transitions the phase to failed and persists the error.
+ */
+async function handlePhaseFailure(phase, err, executor, ps, base, additionalUpdates) {
+    if (executor.aborted) {
+        return {
+            executed: true,
+            phaseState: phaseFailed(ps, phase),
+            error: { step: phase, code: 'ABORT', message: 'Aborted by operator' },
+        };
+    }
+    const error = toMetaError(phase, err);
+    const failedPs = phaseFailed(ps, phase);
+    await persistPhaseState(base, failedPs, {
+        _error: error,
+        ...additionalUpdates,
+    });
+    return { executed: true, phaseState: failedPs, error };
+}
+// ── Architect executor ─────────────────────────────────────────────────
+async function runArchitect(node, currentMeta, phaseState, config, executor, watcher, structureHash, onProgress, logger) {
+    let ps = phaseRunning(phaseState, 'architect');
+    const ctx = await buildContextPackage(node, currentMeta, watcher, logger);
+    try {
+        await onProgress?.({
+            type: 'phase_start',
+            path: node.ownerPath,
+            phase: 'architect',
+        });
+        const phaseStart = Date.now();
+        const architectTask = buildArchitectTask(ctx, currentMeta, config);
+        const result = await executor.spawn(architectTask, {
+            thinking: config.thinking,
+            timeout: config.architectTimeout,
+            label: 'meta-architect',
+        });
+        const builderBrief = parseArchitectOutput(result.output);
+        const architectTokens = result.tokens;
+        // Architect success: architect → fresh, _synthesisCount → 0
+        ps = architectSuccess(ps);
+        const updatedMeta = await persistPhaseState({ metaPath: node.metaPath, current: currentMeta, config, structureHash }, ps, {
+            _builder: builderBrief,
+            _architect: currentMeta._architect ?? config.defaultArchitect ?? '',
+            _synthesisCount: 0,
+            _architectTokens: architectTokens,
+            _generatedAt: new Date().toISOString(),
+            _error: undefined,
+        });
+        await onProgress?.({
+            type: 'phase_complete',
+            path: node.ownerPath,
+            phase: 'architect',
+            tokens: architectTokens,
+            durationMs: Date.now() - phaseStart,
+        });
+        return { executed: true, phaseState: ps, updatedMeta };
+    }
+    catch (err) {
+        return handlePhaseFailure('architect', err, executor, ps, {
+            metaPath: node.metaPath,
+            current: currentMeta,
+            structureHash,
+        });
+    }
+}
+// ── Builder executor ───────────────────────────────────────────────────
+async function runBuilder(node, currentMeta, phaseState, config, executor, watcher, structureHash, onProgress, logger) {
+    let ps = phaseRunning(phaseState, 'builder');
+    const ctx = await buildContextPackage(node, currentMeta, watcher, logger);
     try {
         await onProgress?.({
             type: 'phase_start',
@@ -10641,15 +10776,24 @@ async function synthesizeNode(node, currentMeta, config, executor, watcher, onPr
             phase: 'builder',
         });
         const builderStart = Date.now();
-        const builderTask = buildBuilderTask(ctx, metaForBuilder, config);
-        const builderResult = await executor.spawn(builderTask, {
+        const builderTask = buildBuilderTask(ctx, currentMeta, config);
+        const result = await executor.spawn(builderTask, {
             thinking: config.thinking,
             timeout: config.builderTimeout,
             label: 'meta-builder',
         });
-        builderOutput = parseBuilderOutput(builderResult.output);
-        builderTokens = builderResult.tokens;
-        synthesisCount++;
+        const builderOutput = parseBuilderOutput(result.output);
+        const builderTokens = result.tokens;
+        // Builder success: builder → fresh, critic → pending
+        ps = builderSuccess(ps);
+        const updatedMeta = await persistPhaseState({ metaPath: node.metaPath, current: currentMeta, config, structureHash }, ps, {
+            _content: builderOutput.content,
+            _state: builderOutput.state,
+            _builderTokens: builderTokens,
+            _generatedAt: new Date().toISOString(),
+            _error: undefined,
+            ...builderOutput.fields,
+        });
         await onProgress?.({
             type: 'phase_complete',
             path: node.ownerPath,
@@ -10657,38 +10801,37 @@ async function synthesizeNode(node, currentMeta, config, executor, watcher, onPr
             tokens: builderTokens,
             durationMs: Date.now() - builderStart,
         });
+        return { executed: true, phaseState: ps, updatedMeta };
     }
     catch (err) {
+        // §4.6 partial _state recovery on timeout
+        let partialState;
         if (err instanceof SpawnTimeoutError) {
-            const recovered = await attemptTimeoutRecovery({
-                err,
-                currentMeta,
-                metaPath: node.metaPath,
-                config,
-                builderBrief,
-                structureHash: newStructureHash,
-                synthesisCount,
-            });
-            if (recovered)
-                return recovered;
-        }
-        stepError = toMetaError('builder', err);
-        await finalizeCycle({
-            ...baseFinalizeOptions,
-            builder: builderBrief,
-            builderOutput: null,
-            feedback: null,
-            synthesisCount,
-            error: stepError,
-        });
-        return { synthesized: true, metaPath: node.metaPath, error: stepError };
+            try {
+                const raw = await readFile(err.outputPath, 'utf8');
+                const partial = parseBuilderOutput(raw);
+                if (partial.state !== undefined &&
+                    JSON.stringify(partial.state) !== JSON.stringify(currentMeta._state)) {
+                    partialState = { _state: partial.state };
+                }
+            }
+            catch {
+                // Could not read partial output — no state recovery
+            }
+        }
+        return handlePhaseFailure('builder', err, executor, ps, {
+            metaPath: node.metaPath,
+            current: currentMeta,
+            structureHash,
+        }, partialState);
     }
-    // Step 10: Critic
-    const metaForCritic = {
-        ...currentMeta,
-        _content: builderOutput.content,
-    };
-    let feedback = null;
+}
+// ── Critic executor ────────────────────────────────────────────────────
+async function runCritic(node, currentMeta, phaseState, config, executor, watcher, structureHash, onProgress, logger) {
+    let ps = phaseRunning(phaseState, 'critic');
+    const ctx = await buildContextPackage(node, currentMeta, watcher, logger);
+    // Build critic task using current meta's _content
+    const metaForCritic = { ...currentMeta };
     try {
         await onProgress?.({
             type: 'phase_start',
@@ -10697,14 +10840,32 @@ async function synthesizeNode(node, currentMeta, config, executor, watcher, onPr
         });
         const criticStart = Date.now();
         const criticTask = buildCriticTask(ctx, metaForCritic, config);
-        const criticResult = await executor.spawn(criticTask, {
+        const result = await executor.spawn(criticTask, {
             thinking: config.thinking,
             timeout: config.criticTimeout,
             label: 'meta-critic',
         });
-        feedback = parseCriticOutput(criticResult.output);
-        criticTokens = criticResult.tokens;
-        stepError = null; // Clear any architect error on full success
+        const feedback = parseCriticOutput(result.output);
+        const criticTokens = result.tokens;
+        // Critic success: critic → fresh
+        ps = criticSuccess(ps);
+        const cycleComplete = isFullyFresh(ps);
+        const updates = {
+            _feedback: feedback,
+            _criticTokens: criticTokens,
+            _error: undefined,
+        };
+        // Full-cycle completion: increment _synthesisCount, archive, emit.
+        // Per spec: architect resets to 0, full-cycle increments on top.
+        if (cycleComplete) {
+            updates._synthesisCount = (currentMeta._synthesisCount ?? 0) + 1;
+        }
+        const updatedMeta = await persistPhaseState({ metaPath: node.metaPath, current: currentMeta, config, structureHash }, ps, updates);
+        // Archive on full-cycle only
+        if (cycleComplete) {
+            await createSnapshot(node.metaPath, updatedMeta);
+            await pruneArchive(node.metaPath, config.maxArchive);
+        }
         await onProgress?.({
             type: 'phase_complete',
             path: node.ownerPath,
@@ -10712,139 +10873,144 @@ async function synthesizeNode(node, currentMeta, config, executor, watcher, onPr
             tokens: criticTokens,
             durationMs: Date.now() - criticStart,
         });
+        return {
+            executed: true,
+            phaseState: ps,
+            updatedMeta,
+            cycleComplete,
+        };
     }
     catch (err) {
-        stepError = stepError ?? toMetaError('critic', err);
-    }
-    // Steps 11-12: Merge, archive, prune
-    await finalizeCycle({
-        ...baseFinalizeOptions,
-        builder: builderBrief,
-        builderOutput,
-        feedback,
-        synthesisCount,
-        error: stepError,
-        architectTokens,
-        builderTokens,
-        criticTokens,
-        state: builderOutput.state,
-    });
-    return {
-        synthesized: true,
-        metaPath: node.metaPath,
-        error: stepError ?? undefined,
-    };
+        return handlePhaseFailure('critic', err, executor, ps, {
+            metaPath: node.metaPath,
+            current: currentMeta,
+            structureHash,
+        });
+    }
 }
 
 /**
- * Main orchestration entry point — discovery, scheduling, candidate selection.
+ * Phase-aware orchestration entry point.
+ *
+ * Replaces the old staleness-based orchestrate() with phase-state-machine
+ * scheduling: each tick discovers all metas, computes invalidation,
+ * auto-retries failed phases, selects the best phase candidate, and
+ * executes exactly one phase.
  *
- * @module orchestrator/orchestrate
+ * @module orchestrator/orchestratePhase
  */
-async function orchestrateOnce(config, executor, watcher, targetPath, onProgress, logger) {
-    // When targetPath is provided, skip the expensive full discovery scan.
-    // Build a minimal node from the filesystem instead.
+/** Phase runner dispatch map — avoids repeating the same switch/case. */
+const phaseRunners = {
+    architect: runArchitect,
+    builder: runBuilder,
+    critic: runCritic,
+};
+/**
+ * Run a single phase-aware orchestration tick.
+ *
+ * When targetPath is provided (override entry), runs the owed phase for
+ * that specific meta. Otherwise, discovers all metas, computes invalidation,
+ * and selects the best phase candidate corpus-wide.
+ */
+async function orchestratePhase(config, executor, watcher, targetPath, onProgress, logger) {
+    // ── Targeted path (override entry) ──
     if (targetPath) {
-        const normalizedTarget = normalizePath(targetPath);
-        const targetMetaJson = join(normalizedTarget, 'meta.json');
-        if (!existsSync(targetMetaJson))
-            return { synthesized: false };
-        const node = await buildMinimalNode(normalizedTarget, watcher);
-        if (!acquireLock(node.metaPath))
-            return { synthesized: false };
-        try {
-            const currentMeta = await readMetaJson(normalizedTarget);
-            return await synthesizeNode(node, currentMeta, config, executor, watcher, onProgress, logger);
-        }
-        finally {
-            releaseLock(node.metaPath);
-        }
+        return orchestrateTargeted(config, executor, watcher, targetPath, onProgress, logger);
     }
-    // Full discovery path (scheduler-driven, no specific target)
-    // Step 1: Discover via watcher walk
-    const discoveryStart = Date.now();
-    const metaPaths = await discoverMetas(watcher);
-    logger?.debug({ paths: metaPaths.length, durationMs: Date.now() - discoveryStart }, 'discovery complete');
-    if (metaPaths.length === 0)
-        return { synthesized: false };
-    // Read meta.json for each discovered meta
-    const metas = new Map();
-    for (const mp of metaPaths) {
-        try {
-            metas.set(normalizePath(mp), await readMetaJson(mp));
-        }
-        catch {
-            // Skip metas with unreadable meta.json
-            continue;
-        }
+    // ── Corpus-wide discovery + phase selection ──
+    let metaResult;
+    try {
+        metaResult = await listMetas(config, watcher);
     }
-    // Only build tree from paths with readable meta.json (excludes orphaned/deleted entries)
-    const validPaths = metaPaths.filter((mp) => metas.has(normalizePath(mp)));
-    if (validPaths.length === 0)
-        return { synthesized: false };
-    const tree = buildOwnershipTree(validPaths);
-    // Steps 3-4: Staleness check + candidate selection
-    const candidates = [];
-    for (const treeNode of tree.nodes.values()) {
-        const meta = metas.get(treeNode.metaPath);
-        if (!meta)
-            continue;
-        const staleness = actualStaleness(meta);
-        if (staleness > 0) {
-            candidates.push({ node: treeNode, meta, actualStaleness: staleness });
-        }
-    }
-    const weighted = computeEffectiveStaleness(candidates, config.depthWeight);
-    // Sort by effective staleness descending
-    const ranked = [...weighted].sort((a, b) => b.effectiveStaleness - a.effectiveStaleness);
-    if (ranked.length === 0)
-        return { synthesized: false };
-    // Find the first candidate with actual changes (if skipUnchanged)
-    let winner = null;
-    for (const candidate of ranked) {
-        if (!acquireLock(candidate.node.metaPath))
-            continue;
-        const verifiedStale = await isStale(getScopePrefix(candidate.node), candidate.meta, watcher);
-        if (!verifiedStale && candidate.meta._generatedAt) {
-            // Bump _generatedAt so it doesn't win next cycle
-            const freshMeta = await readMetaJson(candidate.node.metaPath);
-            freshMeta._generatedAt = new Date().toISOString();
-            await writeFile(join(candidate.node.metaPath, 'meta.json'), JSON.stringify(freshMeta, null, 2));
-            releaseLock(candidate.node.metaPath);
-            if (config.skipUnchanged)
-                continue;
-            return { synthesized: false };
+    catch (err) {
+        logger?.warn({ err }, 'Failed to list metas for phase selection');
+        return { executed: false };
+    }
+    if (metaResult.entries.length === 0)
+        return { executed: false };
+    // Build candidates with phase state (including invalidation + auto-retry)
+    const candidates = buildPhaseCandidates(metaResult.entries);
+    // Select best phase candidate
+    const winner = selectPhaseCandidate(candidates, config.depthWeight);
+    if (!winner) {
+        return { executed: false };
+    }
+    // Acquire lock
+    if (!acquireLock(winner.node.metaPath)) {
+        logger?.debug({ path: winner.node.metaPath }, 'Selected candidate is locked, skipping');
+        return { executed: false };
+    }
+    try {
+        // Re-read meta under lock for freshness
+        const currentMeta = await readMetaJson(winner.node.metaPath);
+        const phaseState = retryAllFailed(derivePhaseState(currentMeta));
+        const owedPhase = getOwedPhase(phaseState);
+        if (!owedPhase || phaseState[owedPhase] !== 'pending') {
+            // Nothing to do (race: became fresh between selection and lock)
+            return { executed: false };
+        }
+        // Compute structure hash for the phase
+        const { scopeFiles } = await getScopeFiles(winner.node, watcher);
+        const structureHash = computeStructureHash(scopeFiles);
+        // skipUnchanged: bump _generatedAt without altering _phaseState
+        if (config.skipUnchanged && currentMeta._generatedAt) {
+            const verifiedStale = await isStale(getScopePrefix(winner.node), currentMeta, watcher);
+            if (!verifiedStale) {
+                await persistPhaseState({
+                    metaPath: winner.node.metaPath,
+                    current: currentMeta,
+                    config,
+                    structureHash,
+                }, phaseState, { _generatedAt: new Date().toISOString() });
+                logger?.debug({ path: winner.node.ownerPath }, 'Skipped unchanged meta, bumped _generatedAt');
+                return { executed: false };
+            }
         }
-        winner = candidate;
-        break;
+        return await executePhase(winner.node, currentMeta, phaseState, owedPhase, config, executor, watcher, structureHash, onProgress, logger);
+    }
+    finally {
+        releaseLock(winner.node.metaPath);
+    }
+}
+/**
+ * Orchestrate a targeted (override) meta path.
+ * Resolves the owed phase at execution time (not enqueue time).
+ */
+async function orchestrateTargeted(config, executor, watcher, targetPath, onProgress, logger) {
+    const normalizedTarget = normalizePath(targetPath);
+    const node = await buildMinimalNode(normalizedTarget, watcher);
+    if (!acquireLock(node.metaPath)) {
+        return { executed: false };
     }
-    if (!winner)
-        return { synthesized: false };
-    const node = winner.node;
     try {
-        const currentMeta = await readMetaJson(node.metaPath);
-        return await synthesizeNode(node, currentMeta, config, executor, watcher, onProgress, logger);
+        const currentMeta = await readMetaJson(normalizedTarget);
+        const phaseState = retryAllFailed(derivePhaseState(currentMeta));
+        const owedPhase = getOwedPhase(phaseState);
+        if (!owedPhase) {
+            // Fully fresh — override is a no-op (silently dropped per spec)
+            return { executed: false, metaPath: normalizedTarget };
+        }
+        // Compute structure hash
+        const { scopeFiles } = await getScopeFiles(node, watcher);
+        const structureHash = computeStructureHash(scopeFiles);
+        return await executePhase(node, currentMeta, phaseState, owedPhase, config, executor, watcher, structureHash, onProgress, logger);
     }
     finally {
-        // Step 13: Release lock
         releaseLock(node.metaPath);
     }
 }
 /**
- * Run a single synthesis cycle.
- *
- * Selects the stalest candidate (or a specific target) and runs the
- * full architect/builder/critic pipeline.
- *
- * @param config - Validated synthesis config.
- * @param executor - Pluggable LLM executor.
- * @param watcher - Watcher HTTP client.
- * @param targetPath - Optional: specific meta/owner path to synthesize instead of stalest candidate.
- * @returns Array with a single result.
+ * Execute exactly one phase on a meta.
  */
-async function orchestrate(config, executor, watcher, targetPath, onProgress, logger) {
-    const result = await orchestrateOnce(config, executor, watcher, targetPath, onProgress, logger);
-    return [result];
+async function executePhase(node, currentMeta, phaseState, phase, config, executor, watcher, structureHash, onProgress, logger) {
+    const result = await phaseRunners[phase](node, currentMeta, phaseState, config, executor, watcher, structureHash, onProgress, logger);
+    return {
+        executed: true,
+        metaPath: node.metaPath,
+        phase,
+        phaseResult: result,
+        cycleComplete: result.cycleComplete,
+    };
 }
 
 /**
@@ -10981,42 +11147,106 @@ class ProgressReporter {
 }
 
 /**
- * Single-threaded synthesis queue with priority support and deduplication.
+ * Hybrid 3-layer 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.
  *
- * The scheduler enqueues the stalest candidate each tick. HTTP-triggered
- * synthesis requests get priority (inserted at front). A path appears at
- * most once in the queue; re-triggering returns the current position.
+ * Legacy: `pending` array is the union of overrides + automatic.
  *
  * @module queue
  */
 const DEPTH_WARNING_THRESHOLD = 3;
 /**
- * Single-threaded synthesis queue.
+ * Hybrid 3-layer synthesis queue.
  *
- * Only one synthesis runs at a time. Priority items are inserted at the
- * front of the queue. Duplicate paths are rejected with their current
- * position returned.
+ * Only one synthesis runs at a time. Override items (explicit triggers)
+ * take priority over automatic candidates.
  */
 class SynthesisQueue {
+    /** Legacy queue (used by processQueue for backward compat). */
     queue = [];
     currentItem = null;
     processing = false;
     logger;
     onEnqueueCallback = null;
-    /**
-     * Create a new SynthesisQueue.
-     *
-     * @param logger - Pino logger instance.
-     */
+    /** Explicit override entries (3-layer model). */
+    overrideEntries = [];
+    /** Currently executing item with phase info (3-layer model). */
+    currentPhaseItem = null;
     constructor(logger) {
         this.logger = logger;
     }
-    /**
-     * Set a callback to invoke when a new (non-duplicate) item is enqueued.
-     */
+    /** Set a callback to invoke when a new (non-duplicate) item is enqueued. */
     onEnqueue(callback) {
         this.onEnqueueCallback = callback;
     }
+    // ── Override layer (3-layer model) ─────────────────────────────────
+    /**
+     * Add an explicit override entry (from POST /synthesize with path).
+     * Deduped by path. Returns position and whether already queued.
+     */
+    enqueueOverride(path) {
+        // Check if currently executing
+        if (this.currentPhaseItem?.path === path ||
+            this.currentItem?.path === path) {
+            return { position: 0, alreadyQueued: true };
+        }
+        // Check if already in overrides
+        const existing = this.overrideEntries.findIndex((e) => e.path === path);
+        if (existing !== -1) {
+            return { position: existing, alreadyQueued: true };
+        }
+        this.overrideEntries.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');
+        }
+        this.onEnqueueCallback?.();
+        return { position, alreadyQueued: false };
+    }
+    /** Dequeue the next override entry, or undefined if empty. */
+    dequeueOverride() {
+        return this.overrideEntries.shift();
+    }
+    /** Get all override entries (shallow copy). */
+    get overrides() {
+        return [...this.overrideEntries];
+    }
+    /** Clear all override entries. Returns count removed. */
+    clearOverrides() {
+        const count = this.overrideEntries.length;
+        this.overrideEntries = [];
+        return count;
+    }
+    /** Check if a path is in the override layer. */
+    hasOverride(path) {
+        return this.overrideEntries.some((e) => e.path === path);
+    }
+    // ── Current-item tracking (3-layer model) ──────────────────────────
+    /** Set the currently executing phase item. */
+    setCurrentPhase(path, phase) {
+        this.currentPhaseItem = {
+            path,
+            phase,
+            startedAt: new Date().toISOString(),
+        };
+    }
+    /** Clear the current phase item. */
+    clearCurrentPhase() {
+        this.currentPhaseItem = null;
+    }
+    /** The currently executing phase item, or null. */
+    get currentPhase() {
+        return this.currentPhaseItem;
+    }
+    // ── Legacy queue interface (preserved for backward compat) ─────────
     /**
      * Add a path to the synthesis queue.
      *
@@ -11025,11 +11255,9 @@ class SynthesisQueue {
      * @returns Position and whether the path was already queued.
      */
     enqueue(path, priority = false) {
-        // Check if currently being synthesized.
         if (this.currentItem?.path === path) {
             return { position: 0, alreadyQueued: true };
         }
-        // Check if already in queue.
         const existingIndex = this.queue.findIndex((item) => item.path === path);
         if (existingIndex !== -1) {
             return { position: existingIndex, alreadyQueued: true };
@@ -11052,11 +11280,7 @@ class SynthesisQueue {
         this.onEnqueueCallback?.();
         return { position, alreadyQueued: false };
     }
-    /**
-     * Remove and return the next item from the queue.
-     *
-     * @returns The next QueueItem, or undefined if the queue is empty.
-     */
+    /** Remove and return the next item from the queue. */
     dequeue() {
         const item = this.queue.shift();
         if (item) {
@@ -11086,7 +11310,6 @@ class SynthesisQueue {
     }
     /**
      * Remove all pending items from the queue.
-     *
      * Does not affect the currently-running item.
      *
      * @returns The number of items removed.
@@ -11096,45 +11319,56 @@ class SynthesisQueue {
         this.queue = [];
         return count;
     }
-    /**
-     * Check whether a path is in the queue or currently being synthesized.
-     *
-     * @param path - Meta path to look up.
-     * @returns True if the path is queued or currently running.
-     */
+    /** Check whether a path is in the queue or currently being synthesized. */
     has(path) {
         if (this.currentItem?.path === path)
             return true;
-        return this.queue.some((item) => item.path === path);
+        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.
-     *
-     * @param path - Meta path to look up.
-     * @returns Position index, or null if not found in the queue.
-     */
+    /** 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;
     }
-    /**
-     * Return a snapshot of queue state for the /status endpoint.
-     *
-     * @returns Queue depth and item list.
-     */
+    /** 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;
+    }
+    /** Return a snapshot of queue state for the /status endpoint. */
     getState() {
         return {
-            depth: this.queue.length,
-            items: this.queue.map((item) => ({
-                path: item.path,
-                priority: item.priority,
-                enqueuedAt: item.enqueuedAt,
-            })),
+            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,
+                })),
+            ],
         };
     }
     /**
-     * Process queued items one at a time until the queue is empty.
+     * Process queued items one at a time until all queues are 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.
      *
@@ -11145,19 +11379,22 @@ class SynthesisQueue {
             return;
         this.processing = true;
         try {
-            let item = this.dequeue();
-            while (item) {
+            let next = this.nextItem();
+            while (next) {
                 try {
-                    await synthesizeFn(item.path);
+                    await synthesizeFn(next.path);
                 }
                 catch (err) {
-                    this.logger.error({ path: item.path, err }, 'Synthesis failed');
+                    this.logger.error({ path: next.path, err }, 'Synthesis failed');
                 }
-                this.complete();
-                item = this.dequeue();
+                this.clearCurrentPhase();
+                if (next.source === 'legacy')
+                    this.complete();
+                next = this.nextItem();
             }
         }
         finally {
+            this.clearCurrentPhase();
             this.processing = false;
         }
     }
@@ -11629,14 +11866,15 @@ async function autoSeedPass(rules, watcher, logger) {
 }
 
 /**
- * Croner-based scheduler that discovers the stalest meta candidate each tick
- * and enqueues it for synthesis.
+ * Croner-based scheduler that discovers the highest-priority ready phase
+ * across the corpus each tick and enqueues it for execution.
  *
  * @module scheduler
  */
 const MAX_BACKOFF_MULTIPLIER = 4;
 /**
- * Periodic scheduler that discovers stale meta candidates and enqueues them.
+ * Periodic scheduler that discovers the highest-priority ready phase
+ * across all metas and enqueues it for execution.
  *
  * Supports adaptive backoff when no candidates are found and hot-reloadable
  * cron expressions via {@link Scheduler.updateSchedule}.
@@ -11691,10 +11929,10 @@ class Scheduler {
             this.logger.info({ schedule: expression }, 'Schedule updated');
         }
     }
-    /** Reset backoff multiplier (call after successful synthesis). */
+    /** Reset backoff multiplier (call after successful phase execution). */
     resetBackoff() {
         if (this.backoffMultiplier > 1) {
-            this.logger.debug('Backoff reset after successful synthesis');
+            this.logger.debug('Backoff reset after successful phase execution');
         }
         this.backoffMultiplier = 1;
     }
@@ -11709,10 +11947,9 @@ class Scheduler {
         return this.job.nextRun() ?? null;
     }
     /**
-     * Single tick: discover stalest candidate and enqueue it.
+     * Single tick: discover the highest-priority ready phase and enqueue it.
      *
-     * Skips if the queue is currently processing. Applies adaptive backoff
-     * when no candidates are found.
+     * Applies adaptive backoff when no candidates are found.
      */
     async tick() {
         this.tickCount++;
@@ -11737,14 +11974,15 @@ class Scheduler {
                 this.logger.warn({ err }, 'Auto-seed pass failed');
             }
         }
-        const candidate = await this.discoverStalest();
+        const candidate = await this.discoverNextPhase();
         if (!candidate) {
             this.backoffMultiplier = Math.min(this.backoffMultiplier * 2, MAX_BACKOFF_MULTIPLIER);
-            this.logger.debug({ backoffMultiplier: this.backoffMultiplier }, 'No stale candidates found, increasing backoff');
+            this.logger.debug({ backoffMultiplier: this.backoffMultiplier }, 'No ready phases found, increasing backoff');
             return;
         }
-        this.queue.enqueue(candidate);
-        this.logger.info({ path: candidate }, 'Enqueued stale candidate');
+        // 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
         if (this.registrar) {
             try {
@@ -11764,22 +12002,27 @@ class Scheduler {
         }
     }
     /**
-     * Discover the stalest meta candidate via watcher.
+     * Discover the highest-priority ready phase across the corpus.
+     *
+     * Uses phase-state-aware scheduling: priority order is
+     * critic (band 1) \> builder (band 2) \> architect (band 3),
+     * with weighted staleness as tiebreaker within a band.
      */
-    async discoverStalest() {
+    async discoverNextPhase() {
         try {
             const result = await listMetas(this.config, this.watcher);
-            const stale = result.entries
-                .filter((e) => e.stalenessSeconds > 0 && !e.disabled)
-                .map((e) => ({
-                node: e.node,
-                meta: e.meta,
-                actualStaleness: e.stalenessSeconds,
-            }));
-            return discoverStalestPath(stale, this.config.depthWeight);
+            const candidates = buildPhaseCandidates(result.entries);
+            const winner = selectPhaseCandidate(candidates, this.config.depthWeight);
+            if (!winner)
+                return null;
+            return {
+                path: winner.node.metaPath,
+                phase: winner.owedPhase,
+                band: winner.band,
+            };
         }
         catch (err) {
-            this.logger.warn({ err }, 'Failed to discover stalest candidate');
+            this.logger.warn({ err }, 'Failed to discover next phase candidate');
             return null;
         }
     }
@@ -11985,9 +12228,12 @@ function registerMetasRoutes(app, deps) {
             'architectTokens',
             'builderTokens',
             'criticTokens',
+            'phaseState',
+            'owedPhase',
         ];
         const projectedFields = fieldList ?? defaultFields;
         const metas = entries.map((e) => {
+            const ps = derivePhaseState(e.meta);
             const full = {
                 path: e.path,
                 depth: e.depth,
@@ -12002,6 +12248,8 @@ function registerMetasRoutes(app, deps) {
                 architectTokens: e.architectTokens,
                 builderTokens: e.builderTokens,
                 criticTokens: e.criticTokens,
+                phaseState: ps,
+                owedPhase: getOwedPhase(ps),
             };
             const projected = {};
             for (const f of projectedFields) {
@@ -12026,13 +12274,6 @@ function registerMetasRoutes(app, deps) {
         }
         const meta = JSON.parse(await readFile(join(targetNode.metaPath, 'meta.json'), 'utf8'));
         // Field projection
-        const defaultExclude = new Set([
-            '_architect',
-            '_builder',
-            '_critic',
-            '_content',
-            '_feedback',
-        ]);
         const fieldList = query.fields?.split(',');
         const projectMeta = (m) => {
             if (fieldList) {
@@ -12043,7 +12284,7 @@ function registerMetasRoutes(app, deps) {
             }
             const r = {};
             for (const [k, v] of Object.entries(m)) {
-                if (!defaultExclude.has(k))
+                if (!DEFAULT_EXCLUDE_FIELDS.has(k))
                     r[k] = v;
             }
             return r;
@@ -12056,6 +12297,10 @@ function registerMetasRoutes(app, deps) {
             ? Math.round((Date.now() - new Date(metaTyped._generatedAt).getTime()) / 1000)
             : null;
         const score = computeStalenessScore(staleSeconds, metaTyped._depth ?? 0, metaTyped._emphasis ?? 1, config.depthWeight);
+        // Phase state
+        const entry = result.entries.find((e) => e.node.metaPath === targetNode.metaPath);
+        const phaseState = entry ? derivePhaseState(entry.meta) : null;
+        const owedPhase = phaseState ? getOwedPhase(phaseState) : null;
         const response = {
             path: targetNode.metaPath,
             meta: projectMeta(meta),
@@ -12068,6 +12313,8 @@ function registerMetasRoutes(app, deps) {
                 seconds: staleSeconds,
                 score: Math.round(score * 100) / 100,
             },
+            phaseState,
+            owedPhase,
         };
         // Cross-refs status
         const crossRefsRaw = meta._crossRefs;
@@ -12170,16 +12417,9 @@ function registerMetasUpdateRoute(app, deps) {
         Object.assign(updated, toSet);
         await writeFile(metaJsonPath, JSON.stringify(updated, null, 2) + '\n');
         // Project the response — exclude the same large fields as the detail route.
-        const defaultExclude = new Set([
-            '_architect',
-            '_builder',
-            '_critic',
-            '_content',
-            '_feedback',
-        ]);
         const projected = {};
         for (const [k, v] of Object.entries(updated)) {
-            if (!defaultExclude.has(k))
+            if (!DEFAULT_EXCLUDE_FIELDS.has(k))
                 projected[k] = v;
         }
         return reply.send({
@@ -12241,6 +12481,19 @@ function registerPreviewRoute(app, deps) {
         const structureChanged = structureHash !== meta._structureHash;
         const latestArchive = await readLatestArchive(targetNode.metaPath);
         const steerChanged = hasSteerChanged(meta._steer, latestArchive?._steer, Boolean(latestArchive));
+        // _architect change detection
+        const architectChanged = latestArchive
+            ? (meta._architect ?? '') !== (latestArchive._architect ?? '')
+            : Boolean(meta._architect);
+        // _crossRefs declaration change detection
+        const currentRefs = (meta._crossRefs ?? []).slice().sort().join(',');
+        const archiveRefs = (latestArchive?._crossRefs ?? [])
+            .slice()
+            .sort()
+            .join(',');
+        const crossRefsDeclChanged = latestArchive
+            ? currentRefs !== archiveRefs
+            : currentRefs.length > 0;
         const architectTriggered = isArchitectTriggered(meta, structureChanged, steerChanged, config.architectEvery);
         // Delta files
         const deltaFiles = getDeltaFiles(meta._generatedAt, scopeFiles);
@@ -12255,6 +12508,40 @@ function registerPreviewRoute(app, deps) {
             ? Math.round((Date.now() - new Date(meta._generatedAt).getTime()) / 1000)
             : null;
         const stalenessScore = computeStalenessScore(stalenessSeconds, meta._depth ?? 0, meta._emphasis ?? 1, config.depthWeight);
+        // Phase state
+        const phaseState = derivePhaseState(meta, {
+            structureChanged,
+            steerChanged,
+            architectChanged,
+            crossRefsChanged: crossRefsDeclChanged,
+            architectEvery: config.architectEvery,
+        });
+        const owedPhase = getOwedPhase(phaseState);
+        const priorityBand = getPriorityBand(phaseState);
+        // Architect invalidators
+        const architectInvalidators = [];
+        if (owedPhase === 'architect') {
+            if (structureChanged)
+                architectInvalidators.push('structureHash');
+            if (steerChanged)
+                architectInvalidators.push('steer');
+            if (architectChanged)
+                architectInvalidators.push('_architect');
+            if (crossRefsDeclChanged)
+                architectInvalidators.push('_crossRefs');
+            if ((meta._synthesisCount ?? 0) >= config.architectEvery) {
+                architectInvalidators.push('architectEvery');
+            }
+        }
+        // Staleness inputs
+        const stalenessInputs = {
+            structureHash,
+            steerChanged,
+            architectChanged,
+            crossRefsDeclChanged,
+            scopeMtimeMax: null,
+            crossRefContentChanged: false,
+        };
         return {
             path: targetNode.metaPath,
             staleness: {
@@ -12279,6 +12566,12 @@ function registerPreviewRoute(app, deps) {
                 deltaCount: deltaFiles.length,
             },
             estimatedTokens,
+            // New phase-state fields (additive)
+            owedPhase,
+            priorityBand,
+            phaseState,
+            stalenessInputs,
+            architectInvalidators,
         };
     });
 }
@@ -12286,8 +12579,8 @@ function registerPreviewRoute(app, deps) {
 /**
  * Queue management and abort routes.
  *
- * - GET /queue — current queue state
- * - POST /queue/clear — remove all pending items
+ * - GET /queue — 3-layer queue model (current, overrides, automatic, pending)
+ * - POST /queue/clear — remove override entries only
  * - POST /synthesize/abort — abort the current synthesis
  *
  * @module routes/queue
@@ -12295,33 +12588,134 @@ function registerPreviewRoute(app, deps) {
 /** Register queue management routes. */
 function registerQueueRoutes(app, deps) {
     const { queue } = deps;
-    app.get('/queue', () => ({
-        current: queue.current,
-        pending: queue.pending,
-        state: queue.getState(),
-    }));
+    app.get('/queue', 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) => {
+            try {
+                const metaDir = resolveMetaDir(o.path);
+                const meta = await readMetaJson(metaDir);
+                const ps = derivePhaseState(meta);
+                return {
+                    path: o.path,
+                    owedPhase: getOwedPhase(ps),
+                    enqueuedAt: o.enqueuedAt,
+                };
+            }
+            catch {
+                return {
+                    path: o.path,
+                    owedPhase: null,
+                    enqueuedAt: o.enqueuedAt,
+                };
+            }
+        }));
+        // Compute automatic layer: all metas with a pending owed phase,
+        // ranked by scheduler priority (computed on read, not persisted)
+        let automatic = [];
+        try {
+            const metaResult = await listMetas(deps.config, deps.watcher);
+            const candidates = buildPhaseCandidates(metaResult.entries);
+            const ranked = rankPhaseCandidates(candidates, deps.config.depthWeight);
+            automatic = ranked.map((c) => ({
+                path: c.node.metaPath,
+                owedPhase: c.owedPhase,
+                priorityBand: c.band,
+                effectiveStaleness: c.effectiveStaleness,
+            }));
+        }
+        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
+                ? {
+                    path: currentPhase.path,
+                    phase: currentPhase.phase,
+                    startedAt: currentPhase.startedAt,
+                }
+                : queue.current
+                    ? {
+                        path: queue.current.path,
+                        phase: null,
+                        startedAt: queue.current.enqueuedAt,
+                    }
+                    : null,
+            overrides: enrichedOverrides,
+            automatic,
+            pending: pendingItems,
+            // Legacy state
+            state: queue.getState(),
+        };
+    });
     app.post('/queue/clear', () => {
-        const removed = queue.clear();
+        const removed = queue.clearOverrides();
         return { cleared: removed };
     });
     app.post('/synthesize/abort', async (_request, reply) => {
-        const current = queue.current;
+        // Check 3-layer current first
+        const currentPhase = queue.currentPhase;
+        const current = currentPhase ?? queue.current;
         if (!current) {
-            return reply
-                .status(404)
-                .send({ error: 'NOT_FOUND', message: 'No synthesis in progress' });
+            return reply.status(200).send({ status: 'idle' });
         }
         // Abort the executor
         deps.executor?.abort();
+        const metaDir = resolveMetaDir(current.path);
+        const phase = currentPhase?.phase ?? null;
+        // 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
+            }
+        }
         // Release the lock for the current meta path
         try {
-            releaseLock(resolveMetaDir(current.path));
+            releaseLock(metaDir);
         }
         catch {
             // Lock may already be released
         }
         deps.logger.info({ path: current.path }, 'Synthesis aborted');
-        return { status: 'aborted', path: current.path };
+        return {
+            status: 'aborted',
+            path: current.path,
+            ...(phase ? { phase } : {}),
+        };
     });
 }
 
@@ -12406,7 +12800,6 @@ async function checkDependency(url, path) {
         return { url, status: 'unreachable', checkedAt };
     }
 }
-/** Check watcher, surfacing initialScan.active as indexing state. */
 async function checkWatcher(url) {
     const checkedAt = new Date().toISOString();
     try {
@@ -12432,26 +12825,61 @@ async function checkWatcher(url) {
 function deriveServiceState(deps) {
     if (deps.shuttingDown)
         return 'stopping';
-    if (deps.queue.current)
+    if (deps.queue.current || deps.queue.currentPhase)
         return 'synthesizing';
-    if (deps.queue.depth > 0)
+    if (deps.queue.depth > 0 || deps.queue.overrides.length > 0)
         return 'waiting';
     return 'idle';
 }
+function emptyPhaseCounts() {
+    return { fresh: 0, stale: 0, pending: 0, running: 0, failed: 0 };
+}
 function registerStatusRoute(app, deps) {
     const statusHandler = createStatusHandler({
         name: SERVICE_NAME,
         version: SERVICE_VERSION,
         getHealth: async () => {
-            const { config, queue, scheduler, stats } = deps;
+            const { config, queue, scheduler, stats, watcher } = deps;
             // On-demand dependency checks
             const [watcherHealth, gatewayHealth] = await Promise.all([
                 checkWatcher(config.watcherUrl),
                 checkDependency(config.gatewayUrl, '/status'),
             ]);
+            // Phase state summary
+            const phaseStateSummary = {
+                architect: emptyPhaseCounts(),
+                builder: emptyPhaseCounts(),
+                critic: emptyPhaseCounts(),
+            };
+            let nextPhase = null;
+            try {
+                const metaResult = await listMetas(config, watcher);
+                // Count raw phase states (before retry) for display
+                for (const entry of metaResult.entries) {
+                    const ps = derivePhaseState(entry.meta);
+                    for (const phase of ['architect', 'builder', 'critic']) {
+                        phaseStateSummary[phase][ps[phase]]++;
+                    }
+                }
+                // Build candidates (with auto-retry) for scheduling
+                const candidates = buildPhaseCandidates(metaResult.entries);
+                // Find next phase candidate
+                const winner = selectPhaseCandidate(candidates, config.depthWeight);
+                if (winner) {
+                    nextPhase = {
+                        path: winner.node.metaPath,
+                        phase: winner.owedPhase,
+                        band: winner.band,
+                        staleness: winner.effectiveStaleness,
+                    };
+                }
+            }
+            catch {
+                // Watcher unreachable — phase summary unavailable
+            }
             return {
                 serviceState: deriveServiceState(deps),
-                currentTarget: queue.current?.path ?? null,
+                currentTarget: queue.current?.path ?? queue.currentPhase?.path ?? null,
                 queue: queue.getState(),
                 stats: {
                     totalSyntheses: stats.totalSyntheses,
@@ -12471,6 +12899,8 @@ function registerStatusRoute(app, deps) {
                     },
                     gateway: gatewayHealth,
                 },
+                phaseStateSummary,
+                nextPhase,
             };
         },
     });
@@ -12483,6 +12913,9 @@ function registerStatusRoute(app, deps) {
 /**
  * POST /synthesize route handler.
  *
+ * Path-targeted triggers create explicit override entries in the queue.
+ * Corpus-wide triggers discover the stalest candidate.
+ *
  * @module routes/synthesize
  */
 const synthesizeBodySchema = z.object({
@@ -12493,44 +12926,70 @@ function registerSynthesizeRoute(app, deps) {
     app.post('/synthesize', async (request, reply) => {
         const body = synthesizeBodySchema.parse(request.body);
         const { config, watcher, queue } = deps;
-        let targetPath;
         if (body.path) {
-            targetPath = resolveMetaDir(body.path);
-        }
-        else {
-            // Discover stalest candidate
-            let result;
+            // Path-targeted trigger: create override entry
+            const targetPath = resolveMetaDir(body.path);
+            // Read meta to determine owed phase
+            let owedPhase = null;
+            let meta;
             try {
-                result = await listMetas(config, watcher);
+                meta = await readMetaJson(targetPath);
+                const phaseState = derivePhaseState(meta);
+                owedPhase = getOwedPhase(phaseState);
             }
             catch {
-                return reply.status(503).send({
-                    error: 'SERVICE_UNAVAILABLE',
-                    message: 'Watcher unreachable — cannot discover candidates',
-                });
+                // Meta unreadable — proceed, phase will be evaluated at dequeue time
             }
-            const stale = result.entries
-                .filter((e) => e.stalenessSeconds > 0 && !e.disabled)
-                .map((e) => ({
-                node: e.node,
-                meta: e.meta,
-                actualStaleness: e.stalenessSeconds,
-            }));
-            const stalest = discoverStalestPath(stale, config.depthWeight);
-            if (!stalest) {
-                return reply.code(200).send({
+            // Fully fresh meta → skip (reuse meta already read above)
+            if (owedPhase === null && meta && (meta._phaseState || meta._content)) {
+                return await reply.code(200).send({
                     status: 'skipped',
-                    message: 'No stale metas found. Nothing to synthesize.',
+                    path: targetPath,
+                    owedPhase: null,
+                    queuePosition: -1,
+                    alreadyQueued: false,
                 });
             }
-            targetPath = stalest;
+            const result = queue.enqueueOverride(targetPath);
+            return reply.code(202).send({
+                status: 'queued',
+                path: targetPath,
+                owedPhase,
+                queuePosition: result.position,
+                alreadyQueued: result.alreadyQueued,
+            });
+        }
+        // Corpus-wide trigger: discover stalest candidate
+        let result;
+        try {
+            result = await listMetas(config, watcher);
         }
-        const result = queue.enqueue(targetPath, body.path !== undefined);
+        catch {
+            return reply.status(503).send({
+                error: 'SERVICE_UNAVAILABLE',
+                message: 'Watcher unreachable — cannot discover candidates',
+            });
+        }
+        const stale = result.entries
+            .filter((e) => e.stalenessSeconds > 0 && !e.disabled)
+            .map((e) => ({
+            node: e.node,
+            meta: e.meta,
+            actualStaleness: e.stalenessSeconds,
+        }));
+        const stalest = discoverStalestPath(stale, config.depthWeight);
+        if (!stalest) {
+            return reply.code(200).send({
+                status: 'skipped',
+                message: 'No stale metas found. Nothing to synthesize.',
+            });
+        }
+        const enqueueResult = queue.enqueue(stalest);
         return reply.code(202).send({
             status: 'accepted',
-            path: targetPath,
-            queuePosition: result.position,
-            alreadyQueued: result.alreadyQueued,
+            path: stalest,
+            queuePosition: enqueueResult.position,
+            alreadyQueued: enqueueResult.alreadyQueued,
         });
     });
 }
@@ -12568,6 +13027,17 @@ function registerUnlockRoute(app, deps) {
  *
  * @module routes
  */
+/**
+ * Large generated fields excluded from detail/update response projections.
+ * Shared between metas detail and metasUpdate routes.
+ */
+const DEFAULT_EXCLUDE_FIELDS = new Set([
+    '_architect',
+    '_builder',
+    '_critic',
+    '_content',
+    '_feedback',
+]);
 /** Register all HTTP routes on the Fastify instance. */
 function registerRoutes(app, deps) {
     // Global error handler for validation + watcher errors
@@ -12822,10 +13292,9 @@ async function startService(config, configPath) {
     }
     // Progress reporter — uses shared config reference so hot-reload propagates
     const progress = new ProgressReporter(config, logger);
-    // Wire queue processing — synthesize one meta per dequeue
+    // Wire queue processing — execute one phase per dequeue (phase-state machine)
     const synthesizeFn = async (path) => {
         const startMs = Date.now();
-        let cycleTokens = 0;
         // Strip .meta suffix for human-readable progress reporting
         const ownerPath = path.replace(/\/?\.meta\/?$/, '');
         await progress.report({
@@ -12833,49 +13302,50 @@ async function startService(config, configPath) {
             path: ownerPath,
         });
         try {
-            const results = await orchestrate(config, executor, watcher, path, async (evt) => {
+            const result = await orchestratePhase(config, executor, watcher, path, async (evt) => {
+                // Wire current-phase tracking for GET /queue and POST /synthesize/abort
+                if (evt.type === 'phase_start' && evt.phase) {
+                    queue.setCurrentPhase(ownerPath, evt.phase);
+                }
                 // Track token stats from phase completions
                 if (evt.type === 'phase_complete') {
                     if (evt.tokens !== undefined) {
                         stats.totalTokens += evt.tokens;
-                        if (cycleTokens !== undefined) {
-                            cycleTokens += evt.tokens;
-                        }
                     }
                     else {
-                        cycleTokens = undefined;
                         logger.warn({ path: ownerPath, phase: evt.phase }, 'Token count unavailable (session lookup may have timed out)');
                     }
                 }
                 await progress.report(evt);
             }, logger);
-            // orchestrate() always returns exactly one result
-            const result = results[0];
             const durationMs = Date.now() - startMs;
-            if (!result.synthesized) {
-                // Entity was skipped (e.g. empty scope) — no progress to report.
-                logger.debug({ path: ownerPath }, 'Synthesis skipped');
+            if (!result.executed) {
+                logger.debug({ path: ownerPath }, 'Phase skipped (fully fresh or locked)');
                 return;
             }
             // Update stats
             stats.totalSyntheses++;
             stats.lastCycleDurationMs = durationMs;
             stats.lastCycleAt = new Date().toISOString();
-            if (result.error) {
+            const phaseResult = result.phaseResult;
+            if (phaseResult?.error) {
                 stats.totalErrors++;
                 await progress.report({
                     type: 'error',
                     path: ownerPath,
-                    phase: result.error.step,
-                    error: result.error.message,
+                    phase: phaseResult.error.step,
+                    error: phaseResult.error.message,
                 });
             }
             else {
+                // Task #9: Reset backoff on ANY successful phase execution
                 scheduler.resetBackoff();
+            }
+            // Emit synthesis_complete only on full-cycle completion
+            if (result.cycleComplete) {
                 await progress.report({
                     type: 'synthesis_complete',
                     path: ownerPath,
-                    tokens: cycleTokens,
                     durationMs,
                 });
             }