@karmaniverous/jeeves-meta 0.15.8 → 0.15.9

package/dist/index.js

@@ -80,6 +80,113 @@ const META_COMPONENT = {
     pluginPackage: '@karmaniverous/jeeves-meta-openclaw',
     defaultPort: 1938};
 
+/**
+ * Shared endpoint catalog — single source of truth for the jeeves-meta API.
+ *
+ * Both the CLI service and the OpenClaw plugin derive their registrations
+ * from this declarative catalog, eliminating drift between the two.
+ *
+ */
+/**
+ * Canonical endpoint catalog for the jeeves-meta API.
+ *
+ * Every entry describes a single HTTP endpoint exposed by the service.
+ * Route handlers, plugin tools, and HTTP clients should reference these
+ * descriptors rather than hard-coding paths and descriptions.
+ */
+const META_ENDPOINTS = [
+    {
+        name: 'status',
+        method: 'GET',
+        path: '/status',
+        description: 'Service health and status overview.',
+    },
+    {
+        name: 'listMetas',
+        method: 'GET',
+        path: '/metas',
+        description: 'List metas with summary stats and per-meta projection. Response includes _phaseState and owedPhase per meta.',
+    },
+    {
+        name: 'metaDetail',
+        method: 'GET',
+        path: '/metas/:path',
+        description: 'Full detail for a single meta, with optional archive history. Response includes _phaseState and owedPhase.',
+    },
+    {
+        name: 'updateMeta',
+        method: 'PATCH',
+        path: '/metas/:path',
+        description: 'Update user-settable reserved properties on a meta entity.',
+    },
+    {
+        name: 'synthesize',
+        method: 'POST',
+        path: '/synthesize',
+        description: 'Trigger synthesis. Path-targeted creates an override queue entry; returns owedPhase. Fully-fresh metas return status:skipped.',
+    },
+    {
+        name: 'abort',
+        method: 'POST',
+        path: '/synthesize/abort',
+        description: 'Abort the currently running synthesis.',
+    },
+    {
+        name: 'preview',
+        method: 'GET',
+        path: '/preview',
+        description: 'Dry-run preview of next synthesis. Returns owedPhase, priorityBand, phaseState, inputStatus, and architectInvalidators.',
+    },
+    {
+        name: 'seed',
+        method: 'POST',
+        path: '/seed',
+        description: 'Create a .meta/ directory and initial meta.json for a new entity path.',
+    },
+    {
+        name: 'unlock',
+        method: 'POST',
+        path: '/unlock',
+        description: 'Remove a stale .lock from a meta entity that is stuck.',
+    },
+    {
+        name: 'config',
+        method: 'GET',
+        path: '/config',
+        description: 'Query service configuration with optional JSONPath.',
+    },
+    {
+        name: 'configApply',
+        method: 'POST',
+        path: '/config/apply',
+        description: 'Apply a configuration patch.',
+    },
+    {
+        name: 'queue',
+        method: 'GET',
+        path: '/queue',
+        description: 'List queued synthesis operations (3-layer model: current, overrides, automatic).',
+    },
+    {
+        name: 'queueClear',
+        method: 'POST',
+        path: '/queue/clear',
+        description: 'Clear override entries from the queue.',
+    },
+];
+/**
+ * Look up an endpoint descriptor by name.
+ *
+ * @param name - The endpoint identifier.
+ * @returns The matching {@link EndpointDescriptor}.
+ */
+function getEndpoint(name) {
+    const ep = META_ENDPOINTS.find((e) => e.name === name);
+    if (!ep)
+        throw new Error(`Unknown endpoint: ${name}`);
+    return ep;
+}
+
 /**
  * Structured error schema from a synthesis step failure.
  *
@@ -6018,6 +6125,9 @@ function requireRange () {
 	  }
 
 	  parseRange (range) {
+	    // strip build metadata so it can't bleed into the version
+	    range = range.replace(BUILDSTRIPRE, '');
+
 	    // memoize range parsing for performance.
 	    // this is a very hot path, and fully deterministic.
 	    const memoOpts =
@@ -6143,6 +6253,7 @@ function requireRange () {
 	const SemVer = requireSemver$1();
 	const {
 	  safeRe: re,
+	  src,
 	  t,
 	  comparatorTrimReplace,
 	  tildeTrimReplace,
@@ -6150,6 +6261,9 @@ function requireRange () {
 	} = requireRe();
 	const { FLAG_INCLUDE_PRERELEASE, FLAG_LOOSE } = requireConstants();
 
+	// unbounded global build-metadata stripper used by parseRange
+	const BUILDSTRIPRE = new RegExp(src[t.BUILD], 'g');
+
 	const isNullSet = c => c.value === '<0.0.0-0';
 	const isAny = c => c.value === '';
 
@@ -7201,7 +7315,7 @@ function requireSubset () {
 	        if (higher === c && higher !== gt) {
 	          return false
 	        }
-	      } else if (gt.operator === '>=' && !satisfies(gt.semver, String(c), options)) {
+	      } else if (gt.operator === '>=' && !c.test(gt.semver)) {
 	        return false
 	      }
 	    }
@@ -7219,7 +7333,7 @@ function requireSubset () {
 	        if (lower === c && lower !== lt) {
 	          return false
 	        }
-	      } else if (lt.operator === '<=' && !satisfies(lt.semver, String(c), options)) {
+	      } else if (lt.operator === '<=' && !c.test(lt.semver)) {
 	        return false
 	      }
 	    }
@@ -7879,6 +7993,20 @@ When editing files outside the workspace, use the bridge pattern: copy in → ed
 
 **Cross-channel sends:** Use the \`message\` tool with an explicit \`target\` to send to a different channel or DM.
 
+### Slack File Downloads
+
+To download a Slack-hosted file, first try the \`message\` tool's \`download-file\` action. If that fails, fall back to a direct HTTP fetch using the bot token:
+
+\`\`\`js
+fetch(url_private_download, {
+  headers: { Authorization: 'Bearer ' + botToken },
+});
+\`\`\`
+
+The bot token is at \`channels.slack.accounts.default.botToken\` in \`openclaw.json\`.
+
+Never tell the user a file can't be downloaded until both methods have been tried.
+
 ### Plugin Lifecycle
 
 \`\`\`bash
@@ -8361,6 +8489,24 @@ async function discoverMetas(watcher) {
     return metaPaths;
 }
 
+/**
+ * Retrieve the nearest ancestor meta node from the ownership tree.
+ *
+ * @module discovery/getAncestorMeta
+ */
+/**
+ * Get the nearest ancestor MetaNode for a given node.
+ *
+ * Walks up the ownership tree (via the parent pointer set by
+ * buildOwnershipTree) to find the closest ancestor .meta/ directory.
+ *
+ * @param node - The meta node to find the ancestor for.
+ * @returns The parent MetaNode, or null for root-level metas.
+ */
+function getAncestorMeta(node) {
+    return node.parent;
+}
+
 /**
  * File-system lock for preventing concurrent synthesis on the same meta.
  *
@@ -9033,6 +9179,14 @@ const autoSeedRuleSchema = z.object({
     steer: z.string().optional(),
     /** Optional cross-references for seeded metas. */
     crossRefs: z.array(z.string()).optional(),
+    /** Walk up this many extra parent levels from the matched file's directory. Default 0. */
+    parentDepth: z.number().int().min(0).optional(),
+    /** Per-category timeout override for the architect phase (seconds, min 30). */
+    architectTimeout: z.number().int().min(30).optional(),
+    /** Per-category timeout override for the builder phase (seconds, min 30). */
+    builderTimeout: z.number().int().min(30).optional(),
+    /** Per-category timeout override for the critic phase (seconds, min 30). */
+    criticTimeout: z.number().int().min(30).optional(),
 });
 /** Zod schema for jeeves-meta service configuration (superset of MetaConfig). */
 const serviceConfigSchema = metaConfigSchema.extend({
@@ -9324,7 +9478,7 @@ class GatewayExecutor {
             'Write your complete output to a file using the Write tool at:\n' +
             outputPath +
             '\n\n' +
-            'After writing the file, reply with ONLY: NO_REPLY';
+            'After writing the file, your final message must be exactly: ANNOUNCE_SKIP';
         // Step 1: Spawn the sub-agent session (unique label per cycle to avoid
         // "label already in use" errors — gateway labels persist after session completion)
         const labelBase = options?.label ?? 'jeeves-meta-synthesis';
@@ -9392,7 +9546,9 @@ class GatewayExecutor {
                             }
                         }
                     }
-                    // Fallback: extract from message content if file wasn't written
+                    // Fallback: extract from message content if file wasn't written.
+                    // Skip ANNOUNCE_SKIP sentinel messages — the real output is in
+                    // a preceding assistant message (the file write).
                     for (let i = msgArray.length - 1; i >= 0; i--) {
                         const msg = msgArray[i];
                         if (msg.role === 'assistant' && msg.content) {
@@ -9404,7 +9560,7 @@ class GatewayExecutor {
                                         .map((b) => b.text)
                                         .join('\n')
                                     : '';
-                            if (text)
+                            if (text && text.trim() !== 'ANNOUNCE_SKIP')
                                 return { output: text, tokens };
                         }
                     }
@@ -9434,11 +9590,16 @@ class GatewayExecutor {
 function createLogger(config) {
     const level = config?.level ?? 'info';
     if (config?.file) {
-        const transport = pino.transport({
-            target: 'pino/file',
-            options: { destination: config.file, mkdir: true },
+        const fileStream = pino.destination({
+            dest: config.file,
+            sync: false,
+            mkdir: true,
         });
-        return pino({ level }, transport);
+        const multistream = pino.multistream([
+            { stream: process.stdout },
+            { stream: fileStream },
+        ]);
+        return pino({ level }, multistream);
     }
     return pino({ level });
 }
@@ -9560,6 +9721,21 @@ async function buildContextPackage(node, meta, watcher, logger) {
     }
     // Archive paths
     const archives = listArchiveFiles(node.metaPath);
+    // Nearest ancestor _builder output
+    let ancestorBuilder;
+    const ancestor = getAncestorMeta(node);
+    if (ancestor) {
+        try {
+            const raw = await readFile(join(ancestor.metaPath, 'meta.json'), 'utf8');
+            const ancestorMeta = JSON.parse(raw);
+            if (ancestorMeta._builder) {
+                ancestorBuilder = ancestorMeta._builder;
+            }
+        }
+        catch {
+            // Ancestor meta.json unreadable — skip
+        }
+    }
     return {
         path: node.metaPath,
         scopeFiles,
@@ -9571,6 +9747,7 @@ async function buildContextPackage(node, meta, watcher, logger) {
         steer: meta._steer ?? null,
         previousState: meta._state ?? null,
         archives,
+        ancestorBuilder,
     };
 }
 
@@ -9618,6 +9795,12 @@ function appendMetaSections(sections, heading, metas) {
         sections.push(`### ${path}`, typeof content === 'string' ? content : '(not yet synthesized)');
     }
 }
+/** Inject nearest ancestor's organizational context, if available. */
+function appendAncestorContext(sections, ctx) {
+    if (ctx.ancestorBuilder) {
+        sections.push('', '## PARENT ORGANIZATIONAL CONTEXT', ctx.ancestorBuilder);
+    }
+}
 /** Append optional context sections shared across all step prompts. */
 function appendSharedSections(sections, ctx, options) {
     const opts = {
@@ -9657,7 +9840,7 @@ function buildArchitectTask(ctx, meta, config) {
     const sections = [
         `# jeeves-meta · ARCHITECT · ${ctx.path}`,
         '',
-        meta._architect ?? config.defaultArchitect ?? DEFAULT_ARCHITECT_PROMPT,
+        config.defaultArchitect ?? DEFAULT_ARCHITECT_PROMPT,
         '',
         '## SCOPE',
         `Path: ${ctx.path}`,
@@ -9667,6 +9850,7 @@ function buildArchitectTask(ctx, meta, config) {
         '### File listing (scope)',
         condenseScopeFiles(ctx.scopeFiles),
     ];
+    appendAncestorContext(sections, ctx);
     // Inject previous _builder so architect can see its own prior output
     if (meta._builder) {
         sections.push('', '## PREVIOUS TASK BRIEF', meta._builder);
@@ -9697,6 +9881,7 @@ function buildBuilderTask(ctx, meta, config) {
         `Delta files (${ctx.deltaFiles.length.toString()} changed):`,
         ...ctx.deltaFiles.slice(0, config.maxLines).map((f) => `- ${f}`),
     ];
+    appendAncestorContext(sections, ctx);
     if (ctx.previousState != null) {
         sections.push('', '## PREVIOUS STATE', 'The following opaque state was returned by the previous synthesis cycle.', 'Use it to continue progressive work. Update `_state` in your output to', 'reflect your progress.', '', '```json', JSON.stringify(ctx.previousState, null, 2), '```');
     }
@@ -9719,7 +9904,7 @@ function buildCriticTask(ctx, meta, config) {
     const sections = [
         `# jeeves-meta · CRITIC · ${ctx.path}`,
         '',
-        meta._critic ?? config.defaultCritic ?? DEFAULT_CRITIC_PROMPT,
+        config.defaultCritic ?? DEFAULT_CRITIC_PROMPT,
         '',
         '## SYNTHESIS TO EVALUATE',
         meta._content ?? '(No content produced)',
@@ -9853,7 +10038,7 @@ function enforceInvariant(state) {
 // ── Invalidation cascades ──────────────────────────────────────────────
 /**
  * Architect invalidated: architect → pending; builder, critic → stale.
- * Triggers: _structureHash change, _steer change, _architect change,
+ * Triggers: first run, _structureHash change, _steer change,
  * _crossRefs declaration change, _synthesisCount \>= architectEvery.
  */
 function invalidateArchitect(state) {
@@ -10051,31 +10236,6 @@ function derivePhaseState(meta, inputs) {
     if (!meta._content && !meta._builder) {
         return initialPhaseState();
     }
-    // Check architect invalidation (when inputs are provided)
-    if (inputs) {
-        // Progressive metas: structure changes invalidate builder, not architect
-        const structureInvalidatesArchitect = inputs.structureChanged && meta._state === undefined;
-        const architectInvalidated = structureInvalidatesArchitect ||
-            inputs.steerChanged ||
-            inputs.architectChanged ||
-            inputs.crossRefsChanged ||
-            (meta._synthesisCount ?? 0) >= inputs.architectEvery;
-        if (architectInvalidated) {
-            return {
-                architect: 'pending',
-                builder: 'stale',
-                critic: 'stale',
-            };
-        }
-        // Progressive meta with structure change: builder-only invalidation
-        if (inputs.structureChanged && meta._state !== undefined) {
-            return {
-                architect: 'fresh',
-                builder: 'pending',
-                critic: 'stale',
-            };
-        }
-    }
     // Has _builder but no _content: builder is pending
     if (meta._builder && !meta._content) {
         return {
@@ -10124,6 +10284,14 @@ function computeStructureHash(filePaths) {
  *
  * @module phaseState/invalidate
  */
+/**
+ * Check whether a persisted prompt snapshot mismatches the currently-resolved prompt.
+ * Returns true when the snapshot exists and differs from the resolved prompt.
+ * This is informational only — it does NOT trigger invalidation.
+ */
+function isPromptStale(snapshot, resolved) {
+    return snapshot !== undefined && snapshot !== resolved;
+}
 /**
  * Compute invalidation inputs and apply cascade for a single meta.
  *
@@ -10146,10 +10314,16 @@ async function computeInvalidation(meta, scopeFiles, config, node, crossRefMetas
     const structureChanged = structureHash !== meta._structureHash;
     const latestArchive = await readLatestArchive(node.metaPath);
     const steerChanged = hasSteerChanged(meta._steer, latestArchive?._steer, Boolean(latestArchive));
-    // _architect change: compare current vs. archive
-    const architectChanged = latestArchive
-        ? (meta._architect ?? '') !== (latestArchive._architect ?? '')
-        : Boolean(meta._architect);
+    // Prompt staleness detection: compare persisted prompt snapshots against
+    // currently-resolved prompts.  This is INFORMATIONAL ONLY — reported via
+    // inputStatus so /preview can surface it, but it must NEVER feed into
+    // the invalidation cascade.  When a meta naturally reaches architectEvery
+    // through real builder cycles, architect runs with the current prompt and
+    // the snapshot updates.  Coupling prompt changes to invalidation causes a
+    // corpus-wide synthesis storm (see #163).
+    const architectChanged = isPromptStale(meta._architect, config.defaultArchitect ?? DEFAULT_ARCHITECT_PROMPT);
+    const criticChanged = isPromptStale(meta._critic, config.defaultCritic ?? DEFAULT_CRITIC_PROMPT);
+    const effectiveSynthesisCount = meta._synthesisCount ?? 0;
     // _crossRefs declaration change
     const currentRefs = (meta._crossRefs ?? []).slice().sort().join(',');
     const archiveRefs = (latestArchive?._crossRefs ?? [])
@@ -10171,38 +10345,30 @@ async function computeInvalidation(meta, scopeFiles, config, node, crossRefMetas
     }
     if (steerChanged)
         architectInvalidators.push('steer');
-    if (architectChanged)
-        architectInvalidators.push('_architect');
     if (crossRefsDeclChanged)
         architectInvalidators.push('_crossRefs');
-    if ((meta._synthesisCount ?? 0) >= config.architectEvery) {
+    if (effectiveSynthesisCount >= config.architectEvery) {
         architectInvalidators.push('architectEvery');
     }
-    // First-run check: no _builder means architect must run
-    const firstRun = !meta._builder;
-    if (architectInvalidators.length > 0 || firstRun) {
+    if (!meta._builder)
+        architectInvalidators.push('firstRun');
+    if (architectInvalidators.length > 0) {
         phaseState = invalidateArchitect(phaseState);
     }
     // ── Builder-level inputs ──
-    // Scope file mtime check — if any file newer than _generatedAt
-    const scopeMtimeMax = null;
-    // Note: actual mtime check is done by the caller or via isStale;
-    // here we just detect cross-ref content changes for the cascade.
     // Cross-ref _content change (builder-invalidating)
     let crossRefContentChanged = false;
     return {
         phaseState,
         architectInvalidators,
-        stalenessInputs: {
+        inputStatus: {
             structureHash,
             steerChanged,
             architectChanged,
+            criticChanged,
             crossRefsDeclChanged,
-            scopeMtimeMax,
             crossRefContentChanged,
         },
-        structureHash,
-        steerChanged,
     };
 }
 
@@ -10382,6 +10548,15 @@ function toMetaError(step, err, code = 'FAILED') {
  *
  * @module orchestrator/parseOutput
  */
+/** Sentinel appended by synthesis workers to skip the announce turn. */
+const ANNOUNCE_SKIP = 'ANNOUNCE_SKIP';
+/** Strip a trailing ANNOUNCE_SKIP sentinel from raw output. */
+function stripSentinel(raw) {
+    const trimmed = raw.trim();
+    return trimmed.endsWith(ANNOUNCE_SKIP)
+        ? trimmed.slice(0, -ANNOUNCE_SKIP.length).trim()
+        : trimmed;
+}
 /**
  * Parse architect output. The architect returns a task brief as text.
  *
@@ -10389,7 +10564,7 @@ function toMetaError(step, err, code = 'FAILED') {
  * @returns The task brief string.
  */
 function parseArchitectOutput(output) {
-    return output.trim();
+    return stripSentinel(output);
 }
 /**
  * Parse builder output. The builder returns JSON with _content and optional fields.
@@ -10400,7 +10575,7 @@ function parseArchitectOutput(output) {
  * @returns Parsed builder output with content and structured fields.
  */
 function parseBuilderOutput(output) {
-    const trimmed = output.trim();
+    const trimmed = stripSentinel(output);
     // Strategy 1: Try to parse the entire output as JSON directly
     const direct = tryParseJson(trimmed);
     if (direct)
@@ -10467,7 +10642,7 @@ function tryParseJson(str) {
  * @returns The feedback string.
  */
 function parseCriticOutput(output) {
-    return output.trim();
+    return stripSentinel(output);
 }
 
 /**
@@ -10478,6 +10653,12 @@ function parseCriticOutput(output) {
  *
  * @module orchestrator/runPhase
  */
+/** Compute SHA-256 hash of ancestor _builder text for observability tracking. */
+function hashAncestorBuilder(ancestorBuilder) {
+    return ancestorBuilder
+        ? createHash('sha256').update(ancestorBuilder).digest('hex')
+        : undefined;
+}
 /** Write updated meta with phase state via lock staging. */
 async function persistPhaseState(base, phaseState, updates) {
     const lockPath = join(base.metaPath, '.lock');
@@ -10521,6 +10702,12 @@ async function handlePhaseFailure(phase, err, executor, ps, base, additionalUpda
 // ── Architect executor ─────────────────────────────────────────────────
 async function runArchitect(node, currentMeta, phaseState, config, executor, watcher, structureHash, onProgress, logger) {
     let ps = phaseRunning(phaseState, 'architect');
+    const base = {
+        metaPath: node.metaPath,
+        current: currentMeta,
+        config,
+        structureHash,
+    };
     const ctx = await buildContextPackage(node, currentMeta, watcher, logger);
     try {
         await onProgress?.({
@@ -10532,21 +10719,25 @@ async function runArchitect(node, currentMeta, phaseState, config, executor, wat
         const architectTask = buildArchitectTask(ctx, currentMeta, config);
         const result = await executor.spawn(architectTask, {
             thinking: config.thinking,
-            timeout: config.architectTimeout,
+            timeout: currentMeta._architectTimeout ?? 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, {
+        const architectUpdates = {
             _builder: builderBrief,
-            _architect: currentMeta._architect ?? config.defaultArchitect ?? '',
+            _architect: config.defaultArchitect ?? DEFAULT_ARCHITECT_PROMPT,
             _synthesisCount: 0,
             _architectTokens: architectTokens,
             _generatedAt: new Date().toISOString(),
             _error: undefined,
-        });
+        };
+        const ancestorHash = hashAncestorBuilder(ctx.ancestorBuilder);
+        if (ancestorHash)
+            architectUpdates._ancestorBuilderHash = ancestorHash;
+        const updatedMeta = await persistPhaseState(base, ps, architectUpdates);
         await onProgress?.({
             type: 'phase_complete',
             path: node.ownerPath,
@@ -10557,16 +10748,18 @@ async function runArchitect(node, currentMeta, phaseState, config, executor, wat
         return { executed: true, phaseState: ps, updatedMeta };
     }
     catch (err) {
-        return handlePhaseFailure('architect', err, executor, ps, {
-            metaPath: node.metaPath,
-            current: currentMeta,
-            structureHash,
-        });
+        return handlePhaseFailure('architect', err, executor, ps, base);
     }
 }
 // ── Builder executor ───────────────────────────────────────────────────
 async function runBuilder(node, currentMeta, phaseState, config, executor, watcher, structureHash, onProgress, logger) {
     let ps = phaseRunning(phaseState, 'builder');
+    const base = {
+        metaPath: node.metaPath,
+        current: currentMeta,
+        config,
+        structureHash,
+    };
     const ctx = await buildContextPackage(node, currentMeta, watcher, logger);
     try {
         await onProgress?.({
@@ -10578,21 +10771,25 @@ async function runBuilder(node, currentMeta, phaseState, config, executor, watch
         const builderTask = buildBuilderTask(ctx, currentMeta, config);
         const result = await executor.spawn(builderTask, {
             thinking: config.thinking,
-            timeout: config.builderTimeout,
+            timeout: currentMeta._builderTimeout ?? 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, {
+        const builderUpdates = {
             _content: builderOutput.content,
             _state: builderOutput.state,
             _builderTokens: builderTokens,
             _generatedAt: new Date().toISOString(),
             _error: undefined,
             ...builderOutput.fields,
-        });
+        };
+        const ancestorHash = hashAncestorBuilder(ctx.ancestorBuilder);
+        if (ancestorHash)
+            builderUpdates._ancestorBuilderHash = ancestorHash;
+        const updatedMeta = await persistPhaseState(base, ps, builderUpdates);
         await onProgress?.({
             type: 'phase_complete',
             path: node.ownerPath,
@@ -10618,16 +10815,18 @@ async function runBuilder(node, currentMeta, phaseState, config, executor, watch
                 // Could not read partial output — no state recovery
             }
         }
-        return handlePhaseFailure('builder', err, executor, ps, {
-            metaPath: node.metaPath,
-            current: currentMeta,
-            structureHash,
-        }, partialState);
+        return handlePhaseFailure('builder', err, executor, ps, base, partialState);
     }
 }
 // ── Critic executor ────────────────────────────────────────────────────
 async function runCritic(node, currentMeta, phaseState, config, executor, watcher, structureHash, onProgress, logger) {
     let ps = phaseRunning(phaseState, 'critic');
+    const base = {
+        metaPath: node.metaPath,
+        current: currentMeta,
+        config,
+        structureHash,
+    };
     const ctx = await buildContextPackage(node, currentMeta, watcher, logger);
     // Build critic task using current meta's _content
     const metaForCritic = { ...currentMeta };
@@ -10641,7 +10840,7 @@ async function runCritic(node, currentMeta, phaseState, config, executor, watche
         const criticTask = buildCriticTask(ctx, metaForCritic, config);
         const result = await executor.spawn(criticTask, {
             thinking: config.thinking,
-            timeout: config.criticTimeout,
+            timeout: currentMeta._criticTimeout ?? config.criticTimeout,
             label: 'meta-critic',
         });
         const feedback = parseCriticOutput(result.output);
@@ -10651,6 +10850,7 @@ async function runCritic(node, currentMeta, phaseState, config, executor, watche
         const cycleComplete = isFullyFresh(ps);
         const updates = {
             _feedback: feedback,
+            _critic: config.defaultCritic ?? DEFAULT_CRITIC_PROMPT,
             _criticTokens: criticTokens,
             _error: undefined,
         };
@@ -10659,7 +10859,7 @@ async function runCritic(node, currentMeta, phaseState, config, executor, watche
         if (cycleComplete) {
             updates._synthesisCount = (currentMeta._synthesisCount ?? 0) + 1;
         }
-        const updatedMeta = await persistPhaseState({ metaPath: node.metaPath, current: currentMeta, config, structureHash }, ps, updates);
+        const updatedMeta = await persistPhaseState(base, ps, updates);
         // Archive on full-cycle only
         if (cycleComplete) {
             await createSnapshot(node.metaPath, updatedMeta);
@@ -10680,11 +10880,7 @@ async function runCritic(node, currentMeta, phaseState, config, executor, watche
         };
     }
     catch (err) {
-        return handlePhaseFailure('critic', err, executor, ps, {
-            metaPath: node.metaPath,
-            current: currentMeta,
-            structureHash,
-        });
+        return handlePhaseFailure('critic', err, executor, ps, base);
     }
 }
 
@@ -11261,12 +11457,6 @@ class WatcherHealthCheck {
                 return;
             }
             const data = (await res.json());
-            // If rules were never successfully registered (startup failure),
-            // attempt registration now that the watcher is reachable.
-            if (!this.registrar.isRegistered) {
-                this.logger.info('Rules not registered — attempting registration');
-                await this.registrar.register();
-            }
             await this.registrar.checkAndReregister(data.uptime);
         }
         catch (err) {
@@ -11419,36 +11609,39 @@ class RuleRegistrar {
     logger;
     watcherClient;
     lastWatcherUptime = null;
-    registered = false;
+    registering = false;
     constructor(config, logger, watcher) {
         this.config = config;
         this.logger = logger;
         this.watcherClient = watcher;
     }
-    /** Whether rules have been successfully registered. */
-    get isRegistered() {
-        return this.registered;
-    }
     /**
      * Register rules with watcher. Retries with exponential backoff.
      * Non-blocking — logs errors but never throws.
      */
     async register() {
-        const rules = buildMetaRules(this.config);
-        for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
-            try {
-                await this.watcherClient.registerRules(SOURCE, rules);
-                this.registered = true;
-                this.logger.info('Virtual rules registered with watcher');
-                return;
-            }
-            catch (err) {
-                const delayMs = RETRY_BASE_MS * Math.pow(2, attempt);
-                this.logger.warn({ attempt: attempt + 1, delayMs, err }, 'Rule registration failed, retrying');
-                await new Promise((r) => setTimeout(r, delayMs));
+        if (this.registering)
+            return;
+        this.registering = true;
+        try {
+            const rules = buildMetaRules(this.config);
+            for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+                try {
+                    await this.watcherClient.registerRules(SOURCE, rules);
+                    this.logger.info('Virtual rules registered with watcher');
+                    return;
+                }
+                catch (err) {
+                    const delayMs = RETRY_BASE_MS * Math.pow(2, attempt);
+                    this.logger.warn({ attempt: attempt + 1, delayMs, err }, 'Rule registration failed, retrying');
+                    await new Promise((r) => setTimeout(r, delayMs));
+                }
             }
+            this.logger.error('Rule registration failed after max retries — service degraded');
+        }
+        finally {
+            this.registering = false;
         }
-        this.logger.error('Rule registration failed after max retries — service degraded');
     }
     /**
      * Check watcher uptime and re-register if it decreased (restart detected).
@@ -11459,7 +11652,6 @@ class RuleRegistrar {
         if (this.lastWatcherUptime !== null &&
             currentUptime < this.lastWatcherUptime) {
             this.logger.info({ previous: this.lastWatcherUptime, current: currentUptime }, 'Watcher restart detected — re-registering rules');
-            this.registered = false;
             await this.register();
         }
         this.lastWatcherUptime = currentUptime;
@@ -11529,6 +11721,12 @@ async function createMeta(ownerPath, options) {
         metaJson._crossRefs = options.crossRefs;
     if (options?.steer !== undefined)
         metaJson._steer = options.steer;
+    if (options?.architectTimeout !== undefined)
+        metaJson._architectTimeout = options.architectTimeout;
+    if (options?.builderTimeout !== undefined)
+        metaJson._builderTimeout = options.builderTimeout;
+    if (options?.criticTimeout !== undefined)
+        metaJson._criticTimeout = options.criticTimeout;
     const metaJsonPath = join(metaDir, 'meta.json');
     await writeFile(metaJsonPath, JSON.stringify(metaJson, null, 2) + '\n');
     return { metaDir, _id };
@@ -11557,15 +11755,24 @@ function metaExists(ownerPath) {
 /**
  * Extract parent directory paths from watcher walk results.
  *
- * Walk returns file paths; we need the unique set of immediate parent
- * directories that could be owners.
+ * Walk returns file paths; we need the unique set of parent directories that
+ * could be owners. When {@link parentDepth} is specified, walk up that many
+ * additional levels from each file's immediate parent. The walk is clamped at
+ * the filesystem root to prevent escaping the watched scope.
  */
-function extractDirectories(filePaths, logger) {
+function extractDirectories(filePaths, parentDepth = 0, logger) {
     const dirs = new Set();
     for (const fp of filePaths) {
         // Normalize backslash paths (Windows) to forward slashes before posix.dirname
         const normalized = normalizePath(fp);
-        const dir = posix.dirname(normalized);
+        let dir = posix.dirname(normalized);
+        // Walk up parentDepth additional levels, clamping at filesystem root
+        for (let i = 0; i < parentDepth; i++) {
+            const parent = posix.dirname(dir);
+            if (parent === dir)
+                break; // reached root
+            dir = parent;
+        }
         if (dir !== '.' && dir !== '/') {
             dirs.add(dir);
         }
@@ -11590,11 +11797,14 @@ async function autoSeedPass(rules, watcher, logger) {
     const candidates = new Map();
     for (const rule of rules) {
         const files = await watcher.walk([rule.match]);
-        const dirs = extractDirectories(files, logger);
+        const dirs = extractDirectories(files, rule.parentDepth, logger);
         for (const dir of dirs) {
             candidates.set(dir, {
                 steer: rule.steer,
                 crossRefs: rule.crossRefs,
+                architectTimeout: rule.architectTimeout,
+                builderTimeout: rule.builderTimeout,
+                criticTimeout: rule.criticTimeout,
             });
         }
     }
@@ -11609,10 +11819,7 @@ async function autoSeedPass(rules, watcher, logger) {
     const seededPaths = [];
     for (const candidate of toSeed) {
         try {
-            await createMeta(candidate.path, {
-                steer: candidate.steer,
-                crossRefs: candidate.crossRefs,
-            });
+            await createMeta(candidate.path, candidate);
             seededPaths.push(candidate.path);
             logger?.info({ path: candidate.path }, 'auto-seeded meta');
         }
@@ -11814,7 +12021,7 @@ class Scheduler {
                         metaPath: t2.node.metaPath,
                         current: currentMeta,
                         config: this.config,
-                        structureHash: result.structureHash,
+                        structureHash: result.inputStatus.structureHash,
                     }, result.phaseState, {});
                     this.cache.invalidate();
                     return {
@@ -11828,8 +12035,10 @@ class Scheduler {
                     metaPath: t2.node.metaPath,
                     current: currentMeta,
                     config: this.config,
-                    structureHash: result.structureHash,
-                }, result.phaseState, { _generatedAt: new Date().toISOString() });
+                    structureHash: result.inputStatus.structureHash,
+                }, result.phaseState, {
+                    _generatedAt: new Date().toISOString(),
+                });
                 dirty = true;
             }
             finally {
@@ -11859,7 +12068,7 @@ function sanitizeConfig(config) {
 }
 function registerConfigRoute(app, deps) {
     const configHandler = createConfigQueryHandler(() => sanitizeConfig(deps.config));
-    app.get('/config', async (request, reply) => {
+    app.get(getEndpoint('config').path, async (request, reply) => {
         const { path } = request.query;
         const result = await configHandler({ path });
         return reply.status(result.status).send(result.body);
@@ -11878,7 +12087,7 @@ function registerConfigRoute(app, deps) {
  */
 /** Register the POST /config/apply route. */
 function registerConfigApplyRoute(app, configPath) {
-    app.post('/config/apply', async (request, reply) => {
+    app.post(getEndpoint('configApply').path, async (request, reply) => {
         if (!configPath) {
             return reply
                 .status(500)
@@ -11967,42 +12176,32 @@ function registerConfigApplyRoute(app, configPath) {
  *
  * @module routes/metas
  */
+/** Reusable Zod schema for boolean query string parameters ('true'/'false'). */
+const boolQueryParam = z.enum(['true', 'false']).transform((v) => v === 'true');
 const metasQuerySchema = z.object({
     pathPrefix: z.string().optional(),
-    hasError: z
-        .enum(['true', 'false'])
-        .transform((v) => v === 'true')
-        .optional(),
+    hasError: boolQueryParam.optional(),
     staleHours: z
         .string()
         .transform(Number)
         .pipe(z.number().positive())
         .optional(),
-    neverSynthesized: z
-        .enum(['true', 'false'])
-        .transform((v) => v === 'true')
-        .optional(),
-    locked: z
-        .enum(['true', 'false'])
-        .transform((v) => v === 'true')
-        .optional(),
-    disabled: z
-        .enum(['true', 'false'])
-        .transform((v) => v === 'true')
-        .optional(),
+    neverSynthesized: boolQueryParam.optional(),
+    locked: boolQueryParam.optional(),
+    disabled: boolQueryParam.optional(),
     fields: z.string().optional(),
 });
 const metaDetailQuerySchema = z.object({
     fields: z.string().optional(),
     includeArchive: z
         .union([
-        z.enum(['true', 'false']).transform((v) => v === 'true'),
+        boolQueryParam,
         z.string().transform(Number).pipe(z.number().int().nonnegative()),
     ])
         .optional(),
 });
 function registerMetasRoutes(app, deps) {
-    app.get('/metas', async (request) => {
+    app.get(getEndpoint('listMetas').path, async (request) => {
         const query = metasQuerySchema.parse(request.query);
         const { config, watcher } = deps;
         const result = await listMetas(config, watcher);
@@ -12074,7 +12273,7 @@ function registerMetasRoutes(app, deps) {
         });
         return { summary, metas };
     });
-    app.get('/metas/:path', async (request, reply) => {
+    app.get(getEndpoint('metaDetail').path, async (request, reply) => {
         const query = metaDetailQuerySchema.parse(request.query);
         const { config, watcher } = deps;
         const targetPath = normalizePath(decodeURIComponent(request.params.path));
@@ -12168,7 +12367,7 @@ function registerMetasRoutes(app, deps) {
 /**
  * PATCH /metas/:path — update user-settable reserved properties on a meta.
  *
- * Supported fields: _steer, _emphasis, _depth, _crossRefs, _disabled.
+ * Supported fields: _steer, _emphasis, _depth, _crossRefs, _disabled, _architectTimeout, _builderTimeout, _criticTimeout.
  * Set a field to null to remove it. Unknown keys are rejected.
  *
  * @module routes/metasUpdate
@@ -12180,10 +12379,13 @@ const updateBodySchema = z
     _depth: z.union([z.number(), z.null()]).optional(),
     _crossRefs: z.union([z.array(z.string()), z.null()]).optional(),
     _disabled: z.union([z.boolean(), z.null()]).optional(),
+    _architectTimeout: z.union([z.number().int().min(30), z.null()]).optional(),
+    _builderTimeout: z.union([z.number().int().min(30), z.null()]).optional(),
+    _criticTimeout: z.union([z.number().int().min(30), z.null()]).optional(),
 })
     .strict();
 function registerMetasUpdateRoute(app, deps) {
-    app.patch('/metas/:path', async (request, reply) => {
+    app.patch(getEndpoint('updateMeta').path, async (request, reply) => {
         const parseResult = updateBodySchema.safeParse(request.body);
         if (!parseResult.success) {
             return reply.status(400).send({
@@ -12205,13 +12407,7 @@ function registerMetasUpdateRoute(app, deps) {
             });
         }
         const metaJsonPath = join(metaDir, 'meta.json');
-        const KEYS = [
-            '_steer',
-            '_emphasis',
-            '_depth',
-            '_crossRefs',
-            '_disabled',
-        ];
+        const KEYS = Object.keys(updateBodySchema.shape);
         const toDelete = new Set();
         const toSet = {};
         for (const key of KEYS) {
@@ -12249,7 +12445,7 @@ function registerMetasUpdateRoute(app, deps) {
  * @module routes/preview
  */
 function registerPreviewRoute(app, deps) {
-    app.get('/preview', async (request, reply) => {
+    app.get(getEndpoint('preview').path, async (request, reply) => {
         const { config, watcher, cache } = deps;
         const query = request.query;
         let result;
@@ -12287,12 +12483,8 @@ function registerPreviewRoute(app, deps) {
         const { scopeFiles } = await getScopeFiles(targetNode, watcher);
         // Compute invalidation inputs (DRY: reuse phaseState/invalidate logic)
         const invalidation = await computeInvalidation(meta, scopeFiles, config, targetNode);
-        const { architectInvalidators, stalenessInputs } = invalidation;
-        const { structureHash } = invalidation;
-        const structureChanged = structureHash !== meta._structureHash;
-        const { steerChanged } = invalidation;
-        const { architectChanged, crossRefsDeclChanged } = stalenessInputs;
-        const architectTriggered = isArchitectTriggered(meta, structureChanged, steerChanged, config.architectEvery);
+        const { architectInvalidators, inputStatus, phaseState } = invalidation;
+        const architectTriggered = architectInvalidators.length > 0;
         // Delta files
         const deltaFiles = getDeltaFiles(meta._generatedAt, scopeFiles);
         // EMA token estimates
@@ -12306,14 +12498,6 @@ 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);
         return {
@@ -12324,10 +12508,17 @@ function registerPreviewRoute(app, deps) {
             },
             architectWillRun: architectTriggered,
             architectReason: [
-                ...(!meta._builder ? ['no cached builder (first run)'] : []),
-                ...(structureChanged ? ['structure changed'] : []),
-                ...(steerChanged ? ['steer changed'] : []),
-                ...((meta._synthesisCount ?? 0) >= config.architectEvery
+                ...(architectInvalidators.includes('firstRun')
+                    ? ['no cached builder (first run)']
+                    : []),
+                ...(architectInvalidators.includes('structureHash')
+                    ? ['structure changed']
+                    : []),
+                ...(architectInvalidators.includes('steer') ? ['steer changed'] : []),
+                ...(architectInvalidators.includes('_crossRefs')
+                    ? ['cross-refs changed']
+                    : []),
+                ...(architectInvalidators.includes('architectEvery')
                     ? ['periodic refresh']
                     : []),
             ].join(', ') || 'not triggered',
@@ -12344,7 +12535,7 @@ function registerPreviewRoute(app, deps) {
             owedPhase,
             priorityBand,
             phaseState,
-            stalenessInputs,
+            inputStatus,
             architectInvalidators,
         };
     });
@@ -12362,7 +12553,7 @@ function registerPreviewRoute(app, deps) {
 /** Register queue management routes. */
 function registerQueueRoutes(app, deps) {
     const { queue } = deps;
-    app.get('/queue', async () => {
+    app.get(getEndpoint('queue').path, async () => {
         const currentPhase = queue.currentPhase;
         const overrides = queue.overrides;
         // Compute owedPhase for each override entry by reading meta state
@@ -12438,11 +12629,11 @@ function registerQueueRoutes(app, deps) {
             state: queue.getState(),
         };
     });
-    app.post('/queue/clear', () => {
+    app.post(getEndpoint('queueClear').path, () => {
         const removed = queue.clearOverrides();
         return { cleared: removed };
     });
-    app.post('/synthesize/abort', async (_request, reply) => {
+    app.post(getEndpoint('abort').path, async (_request, reply) => {
         // Check 3-layer current first
         const currentPhase = queue.currentPhase;
         const current = currentPhase ?? queue.current;
@@ -12504,7 +12695,7 @@ const seedBodySchema = z.object({
     steer: z.string().optional(),
 });
 function registerSeedRoute(app, deps) {
-    app.post('/seed', async (request, reply) => {
+    app.post(getEndpoint('seed').path, async (request, reply) => {
         const body = seedBodySchema.parse(request.body);
         if (metaExists(body.path)) {
             return reply.status(409).send({
@@ -12641,7 +12832,7 @@ function registerStatusRoute(app, deps) {
                 dependencies: {
                     watcher: {
                         ...watcherHealth,
-                        rulesRegistered: deps.registrar?.isRegistered ?? false,
+                        rulesRegistered: true,
                     },
                     gateway: gatewayHealth,
                 },
@@ -12650,7 +12841,7 @@ function registerStatusRoute(app, deps) {
             };
         },
     });
-    app.get('/status', async (_request, reply) => {
+    app.get(getEndpoint('status').path, async (_request, reply) => {
         const result = await statusHandler();
         return reply.status(result.status).send(result.body);
     });
@@ -12669,24 +12860,41 @@ const synthesizeBodySchema = z.object({
 });
 /** Register the POST /synthesize route. */
 function registerSynthesizeRoute(app, deps) {
-    app.post('/synthesize', async (request, reply) => {
+    app.post(getEndpoint('synthesize').path, async (request, reply) => {
         const body = synthesizeBodySchema.parse(request.body);
         const { config, watcher, queue, cache } = deps;
         if (body.path) {
             // Path-targeted trigger: create override entry
             const targetPath = resolveMetaDir(body.path);
-            // Read meta to determine owed phase
+            // Read meta and recompute invalidation against current inputs
+            // (structure hash, steer, cross-refs, prompt snapshots) rather than
+            // trusting the cached _phaseState. Fixes #160.
             let owedPhase = null;
             let meta;
             try {
                 meta = await readMetaJson(targetPath);
-                const phaseState = derivePhaseState(meta);
-                owedPhase = getOwedPhase(phaseState);
+                const node = await buildMinimalNode(normalizePath(targetPath), watcher);
+                const { scopeFiles } = await getScopeFiles(node, watcher);
+                const invalidation = await computeInvalidation(meta, scopeFiles, config, node);
+                owedPhase = getOwedPhase(invalidation.phaseState);
+                // Persist recomputed phase state + structure hash when stale.
+                // Matches the scheduler's Tier 2 pattern: always persist so the
+                // stored _phaseState reflects reality for subsequent reads.
+                if (owedPhase) {
+                    await persistPhaseState({
+                        metaPath: targetPath,
+                        current: meta,
+                        config,
+                        structureHash: invalidation.inputStatus.structureHash,
+                    }, invalidation.phaseState, {});
+                    cache.invalidate();
+                }
             }
             catch {
-                // Meta unreadable — proceed, phase will be evaluated at dequeue time
+                // Meta unreadable or watcher unavailable — proceed,
+                // phase will be evaluated at dequeue time
             }
-            // Fully fresh meta → skip (reuse meta already read above)
+            // Fully fresh meta → skip
             if (owedPhase === null && meta && (meta._phaseState || meta._content)) {
                 return await reply.code(200).send({
                     status: 'skipped',
@@ -12744,7 +12952,7 @@ const unlockBodySchema = z.object({
     path: z.string().min(1),
 });
 function registerUnlockRoute(app, deps) {
-    app.post('/unlock', (request, reply) => {
+    app.post(getEndpoint('unlock').path, (request, reply) => {
         const body = unlockBodySchema.parse(request.body);
         const metaDir = resolveMetaDir(body.path);
         const lockPath = join(metaDir, '.lock');
@@ -13141,9 +13349,7 @@ async function startService(config, configPath) {
     routeDeps.registrar = registrar;
     void registrar.register().then(() => {
         routeDeps.ready = true;
-        if (registrar.isRegistered) {
-            void verifyRuleApplication(watcher, logger);
-        }
+        void verifyRuleApplication(watcher, logger);
     }, () => {
         // Registration failed after max retries — mark ready anyway
         routeDeps.ready = true;
@@ -13336,6 +13542,17 @@ const metaJsonSchema = z
     _error: metaErrorSchema.optional(),
     /** When true, this meta is skipped during staleness scheduling. Manual trigger still works. */
     _disabled: z.boolean().optional(),
+    /** Per-entity timeout override for the architect phase (seconds, min 30). */
+    _architectTimeout: z.number().int().min(30).optional(),
+    /** Per-entity timeout override for the builder phase (seconds, min 30). */
+    _builderTimeout: z.number().int().min(30).optional(),
+    /** Per-entity timeout override for the critic phase (seconds, min 30). */
+    _criticTimeout: z.number().int().min(30).optional(),
+    /**
+     * SHA-256 hash of ancestor _builder text at last synthesis.
+     * Observability only — no invalidation cascade.
+     */
+    _ancestorBuilderHash: z.string().optional(),
     /**
      * Per-phase state machine record. Engine-managed.
      * Keyed by phase name (architect, builder, critic) with status values.