@karmaniverous/jeeves-meta 0.14.0 → 0.15.1

package/dist/index.js

@@ -9026,12 +9026,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 ??
                 []);
@@ -9042,6 +9042,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();
@@ -9059,7 +9063,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' +
@@ -9077,7 +9080,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) {
@@ -9097,7 +9100,7 @@ class GatewayExecutor {
                     sessionKey,
                     limit: 5,
                     includeTools: false,
-                }, invokeSessionKey);
+                });
                 const messages = historyResult.result?.details?.messages ??
                     historyResult.result?.messages ??
                     [];
@@ -9110,7 +9113,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 {
@@ -9515,6 +9518,22 @@ 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
     .object({
@@ -9595,6 +9614,12 @@ 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();
 
@@ -9653,6 +9678,8 @@ async function mergeAndWrite(options) {
         _state: options.state,
         // Error handling
         _error: options.error ?? undefined,
+        // Phase state machine
+        _phaseState: options.phaseState,
         // Spread structured fields from builder
         ...options.builderOutput?.fields,
     };
@@ -9683,6 +9710,8 @@ async function mergeAndWrite(options) {
         delete merged._content;
     if (merged._feedback === undefined)
         delete merged._feedback;
+    if (merged._phaseState === undefined)
+        delete merged._phaseState;
     // Validate
     const result = metaJsonSchema.safeParse(merged);
     if (!result.success) {
@@ -10378,6 +10407,686 @@ async function orchestrate(config, executor, watcher, targetPath, onProgress, lo
     return [result];
 }
 
+/**
+ * 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 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' };
+}
+/**
+ * Enforce the per-meta invariant: at most one phase is pending or running,
+ * and it is the first non-fresh phase in pipeline order.
+ *
+ * Stale phases that become the first non-fresh phase are promoted to pending.
+ */
+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
+        }
+    }
+    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;
+}
+
+/**
+ * Backward-compatible derivation of _phaseState from existing meta fields.
+ *
+ * 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
+ */
+/**
+ * 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';
+            }
+        }
+        // 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',
+        };
+    }
+    // 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',
+            path: node.ownerPath,
+            phase: 'builder',
+        });
+        const builderStart = Date.now();
+        const builderTask = buildBuilderTask(ctx, currentMeta, config);
+        const result = await executor.spawn(builderTask, {
+            thinking: config.thinking,
+            timeout: config.builderTimeout,
+            label: 'meta-builder',
+        });
+        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,
+            phase: 'builder',
+            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) {
+            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);
+    }
+}
+// ── 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',
+            path: node.ownerPath,
+            phase: 'critic',
+        });
+        const criticStart = Date.now();
+        const criticTask = buildCriticTask(ctx, metaForCritic, config);
+        const result = await executor.spawn(criticTask, {
+            thinking: config.thinking,
+            timeout: config.criticTimeout,
+            label: 'meta-critic',
+        });
+        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,
+            phase: 'critic',
+            tokens: criticTokens,
+            durationMs: Date.now() - criticStart,
+        });
+        return {
+            executed: true,
+            phaseState: ps,
+            updatedMeta,
+            cycleComplete,
+        };
+    }
+    catch (err) {
+        return handlePhaseFailure('critic', err, executor, ps, {
+            metaPath: node.metaPath,
+            current: currentMeta,
+            structureHash,
+        });
+    }
+}
+
+/**
+ * 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/orchestratePhase
+ */
+/** 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) {
+        return orchestrateTargeted(config, executor, watcher, targetPath, onProgress, logger);
+    }
+    // ── Corpus-wide discovery + phase selection ──
+    let metaResult;
+    try {
+        metaResult = await listMetas(config, watcher);
+    }
+    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 };
+            }
+        }
+        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 };
+    }
+    try {
+        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 {
+        releaseLock(node.metaPath);
+    }
+}
+/**
+ * Execute exactly one phase on a meta.
+ */
+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,
+    };
+}
+
 /**
  * Progress reporting via OpenClaw gateway `/tools/invoke` → `message` tool.
  *
@@ -10512,42 +11221,106 @@ class ProgressReporter {
 }
 
 /**
- * Single-threaded synthesis queue with priority support and deduplication.
+ * Hybrid 3-layer synthesis queue.
  *
- * 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.
+ * 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.
  *
  * @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.
      *
@@ -10556,11 +11329,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 };
@@ -10583,11 +11354,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) {
@@ -10617,7 +11384,6 @@ class SynthesisQueue {
     }
     /**
      * Remove all pending items from the queue.
-     *
      * Does not affect the currently-running item.
      *
      * @returns The number of items removed.
@@ -10627,45 +11393,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.
      *
@@ -10676,19 +11453,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;
         }
     }
@@ -11160,14 +11940,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}.
@@ -11222,10 +12003,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;
     }
@@ -11240,10 +12021,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++;
@@ -11268,14 +12048,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 {
@@ -11295,22 +12076,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;
         }
     }
@@ -11516,9 +12302,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,
@@ -11533,6 +12322,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) {
@@ -11557,13 +12348,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) {
@@ -11574,7 +12358,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;
@@ -11587,6 +12371,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),
@@ -11599,6 +12387,8 @@ function registerMetasRoutes(app, deps) {
                 seconds: staleSeconds,
                 score: Math.round(score * 100) / 100,
             },
+            phaseState,
+            owedPhase,
         };
         // Cross-refs status
         const crossRefsRaw = meta._crossRefs;
@@ -11701,16 +12491,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({
@@ -11772,6 +12555,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);
@@ -11786,6 +12582,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: {
@@ -11810,6 +12640,12 @@ function registerPreviewRoute(app, deps) {
                 deltaCount: deltaFiles.length,
             },
             estimatedTokens,
+            // New phase-state fields (additive)
+            owedPhase,
+            priorityBand,
+            phaseState,
+            stalenessInputs,
+            architectInvalidators,
         };
     });
 }
@@ -11817,8 +12653,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
@@ -11826,33 +12662,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 } : {}),
+        };
     });
 }
 
@@ -11909,7 +12846,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 {
@@ -11935,26 +12871,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,
@@ -11974,6 +12945,8 @@ function registerStatusRoute(app, deps) {
                     },
                     gateway: gatewayHealth,
                 },
+                phaseStateSummary,
+                nextPhase,
             };
         },
     });
@@ -11986,6 +12959,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({
@@ -11996,44 +12972,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,
         });
     });
 }
@@ -12071,6 +13073,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
@@ -12325,10 +13338,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({
@@ -12336,49 +13348,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,
                 });
             }
@@ -12498,4 +13511,4 @@ const metaDescriptor = jeevesComponentDescriptorSchema.parse({
     customCliCommands: registerCustomCliCommands,
 });
 
-export { DEFAULT_PORT, DEFAULT_PORT_STR, GatewayExecutor, HttpWatcherClient, MAX_STALENESS_SECONDS, ProgressReporter, RESTART_REQUIRED_FIELDS, RuleRegistrar, SERVICE_NAME, SERVICE_VERSION, Scheduler, SynthesisQueue, acquireLock, actualStaleness, buildArchitectTask, buildBuilderTask, buildContextPackage, buildCriticTask, buildOwnershipTree, cleanupStaleLocks, computeEffectiveStaleness, computeEma, computeStructureHash, createLogger, createServer, createSnapshot, discoverMetas, filterInScope, findNode, formatProgressEvent, getScopePrefix, hasSteerChanged, isArchitectTriggered, isLocked, isStale, listArchiveFiles, listMetas, loadServiceConfig, mergeAndWrite, metaConfigSchema, metaDescriptor, metaErrorSchema, metaJsonSchema, migrateConfigPath, normalizePath, orchestrate, parseArchitectOutput, parseBuilderOutput, parseCriticOutput, pruneArchive, readLatestArchive, readLockState, registerCustomCliCommands, registerRoutes, registerShutdownHandlers, releaseLock, resolveConfigPath, resolveMetaDir, selectCandidate, serviceConfigSchema, sleepAsync as sleep, startService, toMetaError, verifyRuleApplication };
+export { DEFAULT_PORT, DEFAULT_PORT_STR, GatewayExecutor, HttpWatcherClient, MAX_STALENESS_SECONDS, ProgressReporter, RESTART_REQUIRED_FIELDS, RuleRegistrar, SERVICE_NAME, SERVICE_VERSION, Scheduler, SynthesisQueue, acquireLock, actualStaleness, buildArchitectTask, buildBuilderTask, buildContextPackage, buildCriticTask, buildOwnershipTree, cleanupStaleLocks, computeEffectiveStaleness, computeEma, computeStructureHash, createLogger, createServer, createSnapshot, discoverMetas, filterInScope, findNode, formatProgressEvent, getScopePrefix, hasSteerChanged, isArchitectTriggered, isLocked, isStale, listArchiveFiles, listMetas, loadServiceConfig, mergeAndWrite, metaConfigSchema, metaDescriptor, metaErrorSchema, metaJsonSchema, migrateConfigPath, normalizePath, orchestrate, orchestratePhase, parseArchitectOutput, parseBuilderOutput, parseCriticOutput, pruneArchive, readLatestArchive, readLockState, registerCustomCliCommands, registerRoutes, registerShutdownHandlers, releaseLock, resolveConfigPath, resolveMetaDir, runArchitect, runBuilder, runCritic, selectCandidate, serviceConfigSchema, sleepAsync as sleep, startService, toMetaError, verifyRuleApplication };