@karmaniverous/jeeves-meta 0.15.10 → 0.15.12

package/dist/bootstrap.d.ts

@@ -4,6 +4,17 @@
  * @module bootstrap
  */
 import { type ServiceConfig } from './schema/config.js';
+/**
+ * Compute per-cycle token total from a completed meta.
+ *
+ * Exported for testing.
+ *
+ * Uses `_synthesisCount` as a discriminator: after increment by `runCritic`,
+ * a value of 1 means architect ran this cycle (was 0 pre-increment),
+ * so all three phase token fields are summed. A value \> 1 means architect
+ * was skipped (cached brief reused), so only builder + critic are summed.
+ */
+export declare function computeCycleTokens(meta: Record<string, unknown>): number;
 /**
  * Bootstrap the service: create logger, build server, start listening,
  * wire scheduler, queue processing, rule registration, config hot-reload,

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

@@ -2337,7 +2337,7 @@ function buildPhaseCandidates(entries, architectEvery) {
         if (entry.meta._phaseState) {
             const needsArchitect = !entry.meta._builder ||
                 (entry.meta._synthesisCount ?? 0) >= architectEvery;
-            if (needsArchitect && ps.architect === 'fresh') {
+            if (needsArchitect && isFullyFresh(ps)) {
                 ps = { architect: 'pending', builder: 'stale', critic: 'stale' };
             }
         }
@@ -2573,6 +2573,9 @@ async function persistPhaseState(base, phaseState, updates) {
         _phaseState: phaseState,
         _structureHash: base.structureHash,
     };
+    if (!merged._id) {
+        merged._id = randomUUID();
+    }
     // Clean undefined
     if (merged._error === undefined)
         delete merged._error;
@@ -2678,7 +2681,33 @@ async function runBuilder(node, currentMeta, phaseState, config, executor, watch
             timeout: currentMeta._builderTimeout ?? config.builderTimeout,
             label: 'meta-builder',
         });
-        const builderOutput = parseBuilderOutput(result.output);
+        const rawOutput = result.output;
+        // Exact match only — ANNOUNCE_SKIP as the entire output means "no update."
+        // A trailing sentinel on valid output (e.g. JSON + ANNOUNCE_SKIP) is handled
+        // by stripSentinel() inside parseBuilderOutput and is NOT a skip.
+        const isSkip = rawOutput.trim() === 'ANNOUNCE_SKIP';
+        if (isSkip) {
+            // ANNOUNCE_SKIP: preserve existing _content, bump _generatedAt only
+            ps = builderSuccess(ps);
+            const skipUpdates = {
+                _builderTokens: result.tokens,
+                _generatedAt: new Date().toISOString(),
+                _error: undefined,
+            };
+            const ancestorHash = hashAncestorBuilder(ctx.ancestorBuilder);
+            if (ancestorHash)
+                skipUpdates._ancestorBuilderHash = ancestorHash;
+            const updatedMeta = await persistPhaseState(base, ps, skipUpdates);
+            await onProgress?.({
+                type: 'phase_complete',
+                path: node.ownerPath,
+                phase: 'builder',
+                tokens: result.tokens,
+                durationMs: Date.now() - builderStart,
+            });
+            return { executed: true, phaseState: ps, updatedMeta };
+        }
+        const builderOutput = parseBuilderOutput(rawOutput);
         const builderTokens = result.tokens;
         // Builder success: builder → fresh, critic → pending
         ps = builderSuccess(ps);
@@ -2798,6 +2827,28 @@ async function runCritic(node, currentMeta, phaseState, config, executor, watche
  *
  * @module orchestrator/orchestratePhase
  */
+/**
+ * Check whether a meta has an empty scope — no source files, no children,
+ * no cross-refs, and no prior content. Matches §3.9 empty-scope criteria.
+ */
+function isEmptyScope(scopeFiles, node, meta) {
+    return (scopeFiles.length === 0 &&
+        node.children.length === 0 &&
+        (!meta._crossRefs || meta._crossRefs.length === 0) &&
+        !meta._content);
+}
+/**
+ * Handle an empty-scope meta: set all phases fresh, bump _generatedAt.
+ * Prevents perpetual staleness without wasting tokens on synthesis.
+ */
+async function handleEmptyScope(node, currentMeta, config, structureHash, logger) {
+    await persistPhaseState({
+        metaPath: node.metaPath,
+        current: currentMeta,
+        structureHash,
+    }, freshPhaseState(), { _generatedAt: new Date().toISOString() });
+    logger?.info({ path: node.ownerPath }, 'Empty scope — set all phases fresh, bumped _generatedAt');
+}
 /** Phase runner dispatch map — avoids repeating the same switch/case. */
 const phaseRunners = {
     architect: runArchitect,
@@ -2853,6 +2904,11 @@ async function orchestratePhase(config, executor, watcher, targetPath, onProgres
         // Compute structure hash for the phase
         const { scopeFiles } = await getScopeFiles(winner.node, watcher);
         const structureHash = computeStructureHash(scopeFiles);
+        // Empty-scope guard (§3.9, #177): skip synthesis when nothing to synthesize
+        if (isEmptyScope(scopeFiles, winner.node, currentMeta)) {
+            await handleEmptyScope(winner.node, currentMeta, config, structureHash, logger);
+            return { executed: false };
+        }
         // skipUnchanged: bump _generatedAt without altering _phaseState
         if (config.skipUnchanged && currentMeta._generatedAt) {
             const verifiedStale = await isStale(getScopePrefix(winner.node), currentMeta, watcher);
@@ -2894,6 +2950,11 @@ async function orchestrateTargeted(config, executor, watcher, targetPath, onProg
         // Compute structure hash
         const { scopeFiles } = await getScopeFiles(node, watcher);
         const structureHash = computeStructureHash(scopeFiles);
+        // Empty-scope guard (§3.9, #177): skip synthesis when nothing to synthesize
+        if (isEmptyScope(scopeFiles, node, currentMeta)) {
+            await handleEmptyScope(node, currentMeta, config, structureHash, logger);
+            return { executed: false, metaPath: normalizedTarget };
+        }
         return await executePhase(node, currentMeta, phaseState, owedPhase, config, executor, watcher, structureHash, onProgress, logger);
     }
     finally {
@@ -4056,6 +4117,12 @@ function registerConfigApplyRoute(app, configPath) {
                 .status(500)
                 .send({ error: `Failed to write config: ${message}` });
         }
+        // Compute whether any restart-required fields actually changed
+        // (compares validated output against previous config, catching both
+        // explicit patch keys and implicit changes via replace + schema defaults)
+        const validatedRecord = validatedConfig;
+        const restartRequired = RESTART_REQUIRED_FIELDS.some((field) => JSON.stringify(existing[field]) !==
+            JSON.stringify(validatedRecord[field]));
         // Apply hot-reload callback
         try {
             applyHotReloadedConfig(validatedConfig);
@@ -4065,11 +4132,12 @@ function registerConfigApplyRoute(app, configPath) {
             return reply.status(200).send({
                 applied: true,
                 warning: `Config written but callback failed: ${message}`,
-                restartRequired: RESTART_REQUIRED_FIELDS,
+                restartRequired,
             });
         }
         return reply.status(200).send({
             applied: true,
+            restartRequired,
         });
     });
 }
@@ -4330,6 +4398,7 @@ function registerMetasUpdateRoute(app, deps) {
         }
         Object.assign(updated, toSet);
         await writeFile(metaJsonPath, JSON.stringify(updated, null, 2) + '\n');
+        deps.cache.invalidate();
         // Project the response — exclude the same large fields as the detail route.
         const projected = {};
         for (const [k, v] of Object.entries(updated)) {
@@ -4367,10 +4436,10 @@ function registerPreviewRoute(app, deps) {
             const normalized = normalizePath(query.path);
             targetNode = findNode(result.tree, normalized);
             if (!targetNode) {
-                return {
+                return reply.status(404).send({
                     error: 'NOT_FOUND',
                     message: 'Meta path not found: ' + query.path,
-                };
+                });
             }
         }
         else {
@@ -4940,7 +5009,7 @@ function registerRoutes(app, deps) {
     });
     registerStatusRoute(app, deps);
     registerMetasRoutes(app, deps);
-    registerMetasUpdateRoute(app);
+    registerMetasUpdateRoute(app, deps);
     registerSynthesizeRoute(app, deps);
     registerPreviewRoute(app, deps);
     registerSeedRoute(app, deps);
@@ -5027,6 +5096,18 @@ function registerShutdownHandlers(deps) {
                 deps.logger.warn({ path: current.path }, 'Failed to release lock during shutdown');
             }
         }
+        // Release lock for in-progress override synthesis (only when it
+        // differs from the legacy current item to avoid double-release)
+        const currentPhase = deps.queue.currentPhase;
+        if (currentPhase && currentPhase.path !== current?.path) {
+            try {
+                releaseLock(resolveMetaDir(currentPhase.path));
+                deps.logger.info({ path: currentPhase.path }, 'Released lock for in-progress override synthesis');
+            }
+            catch {
+                deps.logger.warn({ path: currentPhase.path }, 'Failed to release override lock during shutdown');
+            }
+        }
         // 3. Close server
         try {
             await deps.server.close();
@@ -5124,6 +5205,25 @@ class HttpWatcherClient {
  *
  * @module bootstrap
  */
+/**
+ * Compute per-cycle token total from a completed meta.
+ *
+ * Exported for testing.
+ *
+ * Uses `_synthesisCount` as a discriminator: after increment by `runCritic`,
+ * a value of 1 means architect ran this cycle (was 0 pre-increment),
+ * so all three phase token fields are summed. A value \> 1 means architect
+ * was skipped (cached brief reused), so only builder + critic are summed.
+ */
+function computeCycleTokens(meta) {
+    const builderTokens = meta._builderTokens ?? 0;
+    const criticTokens = meta._criticTokens ?? 0;
+    const architectRan = (meta._synthesisCount ?? 1) === 1;
+    const architectTokens = architectRan
+        ? (meta._architectTokens ?? 0)
+        : 0;
+    return architectTokens + builderTokens + criticTokens;
+}
 /**
  * Bootstrap the service: create logger, build server, start listening,
  * wire scheduler, queue processing, rule registration, config hot-reload,
@@ -5250,10 +5350,15 @@ async function startService(config, configPath) {
             }
             // Emit synthesis_complete only on full-cycle completion
             if (result.cycleComplete) {
+                const updatedMeta = result.phaseResult?.updatedMeta;
+                const tokens = updatedMeta
+                    ? computeCycleTokens(updatedMeta)
+                    : undefined;
                 await progress.report({
                     type: 'synthesis_complete',
                     path: ownerPath,
                     durationMs,
+                    tokens,
                 });
             }
         }

package/dist/index.js

@@ -2595,7 +2595,7 @@ function buildPhaseCandidates(entries, architectEvery) {
         if (entry.meta._phaseState) {
             const needsArchitect = !entry.meta._builder ||
                 (entry.meta._synthesisCount ?? 0) >= architectEvery;
-            if (needsArchitect && ps.architect === 'fresh') {
+            if (needsArchitect && isFullyFresh(ps)) {
                 ps = { architect: 'pending', builder: 'stale', critic: 'stale' };
             }
         }
@@ -2831,6 +2831,9 @@ async function persistPhaseState(base, phaseState, updates) {
         _phaseState: phaseState,
         _structureHash: base.structureHash,
     };
+    if (!merged._id) {
+        merged._id = randomUUID();
+    }
     // Clean undefined
     if (merged._error === undefined)
         delete merged._error;
@@ -2936,7 +2939,33 @@ async function runBuilder(node, currentMeta, phaseState, config, executor, watch
             timeout: currentMeta._builderTimeout ?? config.builderTimeout,
             label: 'meta-builder',
         });
-        const builderOutput = parseBuilderOutput(result.output);
+        const rawOutput = result.output;
+        // Exact match only — ANNOUNCE_SKIP as the entire output means "no update."
+        // A trailing sentinel on valid output (e.g. JSON + ANNOUNCE_SKIP) is handled
+        // by stripSentinel() inside parseBuilderOutput and is NOT a skip.
+        const isSkip = rawOutput.trim() === 'ANNOUNCE_SKIP';
+        if (isSkip) {
+            // ANNOUNCE_SKIP: preserve existing _content, bump _generatedAt only
+            ps = builderSuccess(ps);
+            const skipUpdates = {
+                _builderTokens: result.tokens,
+                _generatedAt: new Date().toISOString(),
+                _error: undefined,
+            };
+            const ancestorHash = hashAncestorBuilder(ctx.ancestorBuilder);
+            if (ancestorHash)
+                skipUpdates._ancestorBuilderHash = ancestorHash;
+            const updatedMeta = await persistPhaseState(base, ps, skipUpdates);
+            await onProgress?.({
+                type: 'phase_complete',
+                path: node.ownerPath,
+                phase: 'builder',
+                tokens: result.tokens,
+                durationMs: Date.now() - builderStart,
+            });
+            return { executed: true, phaseState: ps, updatedMeta };
+        }
+        const builderOutput = parseBuilderOutput(rawOutput);
         const builderTokens = result.tokens;
         // Builder success: builder → fresh, critic → pending
         ps = builderSuccess(ps);
@@ -3056,6 +3085,28 @@ async function runCritic(node, currentMeta, phaseState, config, executor, watche
  *
  * @module orchestrator/orchestratePhase
  */
+/**
+ * Check whether a meta has an empty scope — no source files, no children,
+ * no cross-refs, and no prior content. Matches §3.9 empty-scope criteria.
+ */
+function isEmptyScope(scopeFiles, node, meta) {
+    return (scopeFiles.length === 0 &&
+        node.children.length === 0 &&
+        (!meta._crossRefs || meta._crossRefs.length === 0) &&
+        !meta._content);
+}
+/**
+ * Handle an empty-scope meta: set all phases fresh, bump _generatedAt.
+ * Prevents perpetual staleness without wasting tokens on synthesis.
+ */
+async function handleEmptyScope(node, currentMeta, config, structureHash, logger) {
+    await persistPhaseState({
+        metaPath: node.metaPath,
+        current: currentMeta,
+        structureHash,
+    }, freshPhaseState(), { _generatedAt: new Date().toISOString() });
+    logger?.info({ path: node.ownerPath }, 'Empty scope — set all phases fresh, bumped _generatedAt');
+}
 /** Phase runner dispatch map — avoids repeating the same switch/case. */
 const phaseRunners = {
     architect: runArchitect,
@@ -3111,6 +3162,11 @@ async function orchestratePhase(config, executor, watcher, targetPath, onProgres
         // Compute structure hash for the phase
         const { scopeFiles } = await getScopeFiles(winner.node, watcher);
         const structureHash = computeStructureHash(scopeFiles);
+        // Empty-scope guard (§3.9, #177): skip synthesis when nothing to synthesize
+        if (isEmptyScope(scopeFiles, winner.node, currentMeta)) {
+            await handleEmptyScope(winner.node, currentMeta, config, structureHash, logger);
+            return { executed: false };
+        }
         // skipUnchanged: bump _generatedAt without altering _phaseState
         if (config.skipUnchanged && currentMeta._generatedAt) {
             const verifiedStale = await isStale(getScopePrefix(winner.node), currentMeta, watcher);
@@ -3152,6 +3208,11 @@ async function orchestrateTargeted(config, executor, watcher, targetPath, onProg
         // Compute structure hash
         const { scopeFiles } = await getScopeFiles(node, watcher);
         const structureHash = computeStructureHash(scopeFiles);
+        // Empty-scope guard (§3.9, #177): skip synthesis when nothing to synthesize
+        if (isEmptyScope(scopeFiles, node, currentMeta)) {
+            await handleEmptyScope(node, currentMeta, config, structureHash, logger);
+            return { executed: false, metaPath: normalizedTarget };
+        }
         return await executePhase(node, currentMeta, phaseState, owedPhase, config, executor, watcher, structureHash, onProgress, logger);
     }
     finally {
@@ -4314,6 +4375,12 @@ function registerConfigApplyRoute(app, configPath) {
                 .status(500)
                 .send({ error: `Failed to write config: ${message}` });
         }
+        // Compute whether any restart-required fields actually changed
+        // (compares validated output against previous config, catching both
+        // explicit patch keys and implicit changes via replace + schema defaults)
+        const validatedRecord = validatedConfig;
+        const restartRequired = RESTART_REQUIRED_FIELDS.some((field) => JSON.stringify(existing[field]) !==
+            JSON.stringify(validatedRecord[field]));
         // Apply hot-reload callback
         try {
             applyHotReloadedConfig(validatedConfig);
@@ -4323,11 +4390,12 @@ function registerConfigApplyRoute(app, configPath) {
             return reply.status(200).send({
                 applied: true,
                 warning: `Config written but callback failed: ${message}`,
-                restartRequired: RESTART_REQUIRED_FIELDS,
+                restartRequired,
             });
         }
         return reply.status(200).send({
             applied: true,
+            restartRequired,
         });
     });
 }
@@ -4588,6 +4656,7 @@ function registerMetasUpdateRoute(app, deps) {
         }
         Object.assign(updated, toSet);
         await writeFile(metaJsonPath, JSON.stringify(updated, null, 2) + '\n');
+        deps.cache.invalidate();
         // Project the response — exclude the same large fields as the detail route.
         const projected = {};
         for (const [k, v] of Object.entries(updated)) {
@@ -4625,10 +4694,10 @@ function registerPreviewRoute(app, deps) {
             const normalized = normalizePath(query.path);
             targetNode = findNode(result.tree, normalized);
             if (!targetNode) {
-                return {
+                return reply.status(404).send({
                     error: 'NOT_FOUND',
                     message: 'Meta path not found: ' + query.path,
-                };
+                });
             }
         }
         else {
@@ -5170,7 +5239,7 @@ function registerRoutes(app, deps) {
     });
     registerStatusRoute(app, deps);
     registerMetasRoutes(app, deps);
-    registerMetasUpdateRoute(app);
+    registerMetasUpdateRoute(app, deps);
     registerSynthesizeRoute(app, deps);
     registerPreviewRoute(app, deps);
     registerSeedRoute(app, deps);
@@ -5257,6 +5326,18 @@ function registerShutdownHandlers(deps) {
                 deps.logger.warn({ path: current.path }, 'Failed to release lock during shutdown');
             }
         }
+        // Release lock for in-progress override synthesis (only when it
+        // differs from the legacy current item to avoid double-release)
+        const currentPhase = deps.queue.currentPhase;
+        if (currentPhase && currentPhase.path !== current?.path) {
+            try {
+                releaseLock(resolveMetaDir(currentPhase.path));
+                deps.logger.info({ path: currentPhase.path }, 'Released lock for in-progress override synthesis');
+            }
+            catch {
+                deps.logger.warn({ path: currentPhase.path }, 'Failed to release override lock during shutdown');
+            }
+        }
         // 3. Close server
         try {
             await deps.server.close();
@@ -5354,6 +5435,25 @@ class HttpWatcherClient {
  *
  * @module bootstrap
  */
+/**
+ * Compute per-cycle token total from a completed meta.
+ *
+ * Exported for testing.
+ *
+ * Uses `_synthesisCount` as a discriminator: after increment by `runCritic`,
+ * a value of 1 means architect ran this cycle (was 0 pre-increment),
+ * so all three phase token fields are summed. A value \> 1 means architect
+ * was skipped (cached brief reused), so only builder + critic are summed.
+ */
+function computeCycleTokens(meta) {
+    const builderTokens = meta._builderTokens ?? 0;
+    const criticTokens = meta._criticTokens ?? 0;
+    const architectRan = (meta._synthesisCount ?? 1) === 1;
+    const architectTokens = architectRan
+        ? (meta._architectTokens ?? 0)
+        : 0;
+    return architectTokens + builderTokens + criticTokens;
+}
 /**
  * Bootstrap the service: create logger, build server, start listening,
  * wire scheduler, queue processing, rule registration, config hot-reload,
@@ -5480,10 +5580,15 @@ async function startService(config, configPath) {
             }
             // Emit synthesis_complete only on full-cycle completion
             if (result.cycleComplete) {
+                const updatedMeta = result.phaseResult?.updatedMeta;
+                const tokens = updatedMeta
+                    ? computeCycleTokens(updatedMeta)
+                    : undefined;
                 await progress.report({
                     type: 'synthesis_complete',
                     path: ownerPath,
                     durationMs,
+                    tokens,
                 });
             }
         }

package/dist/orchestrator/orchestratePhase.d.ts

@@ -8,11 +8,17 @@
  *
  * @module orchestrator/orchestratePhase
  */
+import type { MetaNode } from '../discovery/types.js';
 import type { MetaExecutor, WatcherClient } from '../interfaces/index.js';
 import type { MinimalLogger } from '../logger/index.js';
 import type { ProgressEvent } from '../progress/index.js';
-import type { MetaConfig, PhaseName } from '../schema/index.js';
+import type { MetaConfig, MetaJson, PhaseName } from '../schema/index.js';
 import { type PhaseResult } from './runPhase.js';
+/**
+ * Check whether a meta has an empty scope — no source files, no children,
+ * no cross-refs, and no prior content. Matches §3.9 empty-scope criteria.
+ */
+export declare function isEmptyScope(scopeFiles: string[], node: MetaNode, meta: MetaJson): boolean;
 /** Callback for synthesis progress events. */
 export type PhaseProgressCallback = (event: ProgressEvent) => void | Promise<void>;
 /** Result of a single phase-aware orchestration tick. */

package/package.json

@@ -7,7 +7,7 @@
     "url": "https://github.com/karmaniverous/jeeves-meta/issues"
   },
   "dependencies": {
-    "@karmaniverous/jeeves": "^0.5.11",
+    "@karmaniverous/jeeves": "^0.5.12",
     "@karmaniverous/jeeves-meta-core": "^0.1.3",
     "commander": "^14",
     "croner": "^10",
@@ -110,5 +110,5 @@
   },
   "type": "module",
   "types": "dist/index.d.ts",
-  "version": "0.15.10"
+  "version": "0.15.12"
 }