@karmaniverous/jeeves-meta 0.16.2 → 0.17.0

package/dist/index.js

@@ -5,7 +5,7 @@ import { normalizePath, META_COMPONENT, metaConfigSchema, getEndpoint, phaseStat
 export { metaConfigSchema, metaErrorSchema, normalizePath } from '@karmaniverous/jeeves-meta-core';
 import { fileURLToPath } from 'node:url';
 import process$1 from 'node:process';
-import { fetchJson, postJson, getServiceUrl, sleepAsync, createConfigQueryHandler, atomicWrite, createStatusHandler, getBindAddress, jeevesComponentDescriptorSchema } from '@karmaniverous/jeeves';
+import { fetchJson, postJson, getServiceUrl, sleepAsync, fetchWithTimeout, createConfigQueryHandler, atomicWrite, createStatusHandler, getBindAddress, jeevesComponentDescriptorSchema } from '@karmaniverous/jeeves';
 export { sleepAsync as sleep } from '@karmaniverous/jeeves';
 import { z } from 'zod';
 import { randomUUID, createHash } from 'node:crypto';
@@ -1203,8 +1203,6 @@ const RESTART_REQUIRED_FIELDS = [
     'watcherUrl',
     'gatewayUrl',
     'gatewayApiKey',
-    'defaultArchitect',
-    'defaultCritic',
 ];
 let runtime = null;
 /** Register the active service runtime for config-apply hot reload. */
@@ -1254,6 +1252,12 @@ function applyHotReloadedConfig(newConfig) {
  *
  * @module schema/config
  */
+/** Default Handlebars template strings for progress reporting. Single source of truth. */
+const DEFAULT_TEMPLATE_STRINGS = {
+    phaseStart: ':gear: Started meta synthesis {{phase}} phase of <{{dirLink}}>',
+    phaseEnd: ':white_check_mark: Completed meta synthesis {{phase}} phase ({{tokens}} tokens / {{seconds}}s) at <{{metaLink}}>',
+    phaseError: ':x: Meta synthesis {{phase}} phase failed at <{{dirLink}}>\n   Error: {{error}}',
+};
 /** Zod schema for logging configuration. */
 const loggingSchema = z.object({
     /** Log level. */
@@ -1282,8 +1286,24 @@ const serviceConfigSchema = metaConfigSchema.extend({
     reportChannel: z.string().optional(),
     /** Channel/user ID to send progress messages to. */
     reportTarget: z.string().optional(),
-    /** Optional base URL for the service, used to construct entity links in progress reports. */
-    serverBaseUrl: z.string().optional(),
+    /**
+     * URL of the local jeeves-server instance, used by the ProgressReporter
+     * to resolve filesystem paths to browse links via the resolve-path API.
+     * Default: http://127.0.0.1:1934
+     */
+    serverUrl: z.string().default('http://127.0.0.1:1934'),
+    /**
+     * Handlebars templates for progress reporting messages.
+     * Each template receives a standard set of data keys (dirLink, metaLink,
+     * phase, tokens, seconds, error).
+     */
+    templates: z
+        .object({
+        phaseStart: z.string().default(DEFAULT_TEMPLATE_STRINGS.phaseStart),
+        phaseEnd: z.string().default(DEFAULT_TEMPLATE_STRINGS.phaseEnd),
+        phaseError: z.string().default(DEFAULT_TEMPLATE_STRINGS.phaseError),
+    })
+        .default(() => ({ ...DEFAULT_TEMPLATE_STRINGS })),
     /** Interval in ms for periodic watcher health check. 0 = disabled. Default: 60000. */
     watcherHealthIntervalMs: z.number().int().min(0).default(60_000),
     /** Logging configuration. */
@@ -1308,7 +1328,7 @@ const serviceConfigSchema = metaConfigSchema.extend({
 /**
  * Load and resolve jeeves-meta service config.
  *
- * Supports \@file: indirection and environment-variable substitution (dollar-brace pattern).
+ * Supports environment-variable substitution (dollar-brace pattern).
  *
  * @module configLoader
  */
@@ -1340,19 +1360,6 @@ function substituteEnvVars(value) {
     }
     return value;
 }
-/**
- * Resolve \@file: references in a config value.
- *
- * @param value - String value that may start with "\@file:".
- * @param baseDir - Base directory for resolving relative paths.
- * @returns The resolved string (file contents or original value).
- */
-function resolveFileRef(value, baseDir) {
-    if (!value.startsWith('@file:'))
-        return value;
-    const filePath = join(baseDir, value.slice(6));
-    return readFileSync(filePath, 'utf8');
-}
 /**
  * Migrate legacy config path to the new canonical location.
  *
@@ -1401,8 +1408,7 @@ function resolveConfigPath(args) {
 /**
  * Load service config from a JSON file.
  *
- * Resolves \@file: references for defaultArchitect and defaultCritic,
- * and substitutes environment-variable placeholders throughout.
+ * Substitutes environment-variable placeholders throughout.
  *
  * @param configPath - Path to config JSON file.
  * @returns Validated ServiceConfig.
@@ -1410,13 +1416,6 @@ function resolveConfigPath(args) {
 function loadServiceConfig(configPath) {
     const rawText = readFileSync(configPath, 'utf8');
     const raw = substituteEnvVars(JSON.parse(rawText));
-    const baseDir = dirname(configPath);
-    if (typeof raw['defaultArchitect'] === 'string') {
-        raw['defaultArchitect'] = resolveFileRef(raw['defaultArchitect'], baseDir);
-    }
-    if (typeof raw['defaultCritic'] === 'string') {
-        raw['defaultCritic'] = resolveFileRef(raw['defaultCritic'], baseDir);
-    }
     return serviceConfigSchema.parse(raw);
 }
 
@@ -1792,9 +1791,6 @@ function createLogger(config) {
  * Prompts ship as .md files bundled into dist/prompts/ via rollup-plugin-copy.
  * Loaded at runtime relative to the compiled module location.
  *
- * Users can override via `defaultArchitect` / `defaultCritic` in the service
- * config. Most installations should use the built-in defaults.
- *
  * @module prompts
  */
 const packageRoot = packageDirectorySync({
@@ -2094,7 +2090,7 @@ function buildArchitectTask(ctx, meta, config) {
     const sections = [
         `# jeeves-meta · ARCHITECT · ${ctx.path}`,
         '',
-        config.defaultArchitect ?? DEFAULT_ARCHITECT_PROMPT,
+        DEFAULT_ARCHITECT_PROMPT,
         '',
         '## SCOPE',
         `Path: ${ctx.path}`,
@@ -2143,7 +2139,7 @@ function buildBuilderTask(ctx, meta, config) {
         includeSteer: false,
         feedbackHeading: '## FEEDBACK FROM CRITIC',
     });
-    sections.push('', '## OUTPUT FORMAT', '', 'Respond with ONLY a JSON object. No explanation, no markdown fences, no text before or after.', '', 'Required schema:', '{', '  "type": "object",', '  "required": ["_content"],', '  "properties": {', '    "_content": { "type": "string", "description": "Markdown narrative synthesis" },', '    "_state": { "description": "Opaque state object for progressive work across cycles" }', '  },', '  "additionalProperties": true', '}', '', 'Add any structured fields that capture important facts about this entity', '(e.g. status, risks, dependencies, metrics). Use descriptive key names without underscore prefix.', 'The _content field is the only required key — everything else is domain-driven.', '_state is optional: set it to carry state across synthesis cycles for progressive work.', '', 'DIAGRAMS: When diagrams would aid understanding, use PlantUML in fenced code blocks (```plantuml).', 'PlantUML is rendered natively by the serving infrastructure. NEVER use ASCII art diagrams.');
+    sections.push('', '## OUTPUT FORMAT', '', 'Respond with ONLY a JSON object. No explanation, no markdown fences, no text before or after.', '', 'Required schema:', '{', '  "type": "object",', '  "required": ["_content"],', '  "properties": {', '    "_content": { "type": "string", "description": "Markdown narrative synthesis" },', '    "_state": { "description": "Opaque state object for progressive work across cycles" }', '  },', '  "additionalProperties": true', '}', '', 'Add any structured fields that capture important facts about this entity', '(e.g. status, risks, dependencies, metrics). Use descriptive key names without underscore prefix.', 'The _content field is the only required key — everything else is domain-driven.', '_state is optional: set it to carry state across synthesis cycles for progressive work.', '', 'DIAGRAMS: When diagrams would aid understanding, use PlantUML in fenced code blocks (```plantuml).', 'PlantUML is rendered natively by the serving infrastructure. NEVER use ASCII art diagrams.', '', 'IMPORTANT: Do not call sessions_spawn or sessions_yield. Read all files directly using the tools', 'available in your session. Do not attempt to parallelize work by spawning sub-agents.');
     return compileTemplate(sections.join('\n'), buildTemplateContext(ctx, meta, config));
 }
 /**
@@ -2158,7 +2154,7 @@ function buildCriticTask(ctx, meta, config) {
     const sections = [
         `# jeeves-meta · CRITIC · ${ctx.path}`,
         '',
-        config.defaultCritic ?? DEFAULT_CRITIC_PROMPT,
+        DEFAULT_CRITIC_PROMPT,
         '',
         '## SYNTHESIS TO EVALUATE',
         meta._content ?? '(No content produced)',
@@ -2575,8 +2571,8 @@ async function computeInvalidation(meta, scopeFiles, config, node, crossRefMetas
     // 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 architectChanged = isPromptStale(meta._architect, DEFAULT_ARCHITECT_PROMPT);
+    const criticChanged = isPromptStale(meta._critic, DEFAULT_CRITIC_PROMPT);
     const effectiveSynthesisCount = meta._synthesisCount ?? 0;
     // _crossRefs declaration change
     const currentRefs = (meta._crossRefs ?? []).slice().sort().join(',');
@@ -2823,10 +2819,11 @@ function parseArchitectOutput(output) {
 /**
  * Parse builder output. The builder returns JSON with _content and optional fields.
  *
- * Attempts JSON parse first. If that fails, treats the entire output as _content.
+ * Attempts JSON extraction via multiple strategies. Returns null if all strategies fail
+ * (e.g. the output is plain text, self-talk, or a sub-agent delegation response).
  *
  * @param output - Raw subprocess output.
- * @returns Parsed builder output with content and structured fields.
+ * @returns Parsed builder output, or null if output is not valid builder JSON.
  */
 function parseBuilderOutput(output) {
     const trimmed = stripSentinel(output);
@@ -2855,8 +2852,8 @@ function parseBuilderOutput(output) {
         if (result)
             return result;
     }
-    // Fallback: treat entire output as content
-    return { content: trimmed, fields: {} };
+    // All JSON strategies failed — not valid builder output
+    return null;
 }
 /** Try to parse a string as JSON and extract builder output fields. */
 function tryParseJson(str) {
@@ -2984,7 +2981,7 @@ async function runArchitect(node, currentMeta, phaseState, config, executor, wat
         ps = architectSuccess(ps);
         const architectUpdates = {
             _builder: builderBrief,
-            _architect: config.defaultArchitect ?? DEFAULT_ARCHITECT_PROMPT,
+            _architect: DEFAULT_ARCHITECT_PROMPT,
             _synthesisCount: 0,
             _architectTokens: architectTokens,
             _generatedAt: new Date().toISOString(),
@@ -3056,6 +3053,12 @@ async function runBuilder(node, currentMeta, phaseState, config, executor, watch
             return { executed: true, phaseState: ps, updatedMeta };
         }
         const builderOutput = parseBuilderOutput(rawOutput);
+        if (!builderOutput) {
+            throw new Error('Builder output is not valid JSON — expected { _content|content: string, ... }. ' +
+                'Raw output (' +
+                rawOutput.length.toString() +
+                ' chars) did not match any JSON extraction strategy.');
+        }
         const builderTokens = result.tokens;
         // Builder success: builder → fresh, critic → pending
         ps = builderSuccess(ps);
@@ -3087,7 +3090,8 @@ async function runBuilder(node, currentMeta, phaseState, config, executor, watch
             try {
                 const raw = await readFile(err.outputPath, 'utf8');
                 const partial = parseBuilderOutput(raw);
-                if (partial.state !== undefined &&
+                if (partial !== null &&
+                    partial.state !== undefined &&
                     JSON.stringify(partial.state) !== JSON.stringify(currentMeta._state)) {
                     partialState = { _state: partial.state };
                 }
@@ -3130,7 +3134,7 @@ async function runCritic(node, currentMeta, phaseState, config, executor, watche
         const cycleComplete = isFullyFresh(ps);
         const updates = {
             _feedback: feedback,
-            _critic: config.defaultCritic ?? DEFAULT_CRITIC_PROMPT,
+            _critic: DEFAULT_CRITIC_PROMPT,
             _criticTokens: criticTokens,
             _error: undefined,
         };
@@ -3325,95 +3329,118 @@ async function executePhase(node, currentMeta, phaseState, phase, config, execut
 /**
  * Progress reporting via OpenClaw gateway `/tools/invoke` → `message` tool.
  *
+ * Progress events are rendered using Handlebars templates. Owner-path links
+ * are resolved via the jeeves-server resolve-path API, with graceful
+ * fallback to raw filesystem paths when the server is unreachable.
+ *
  * @module progress
  */
+/** Compile raw template strings into Handlebars delegates. */
+function compileTemplates(raw) {
+    const merged = {
+        phaseStart: raw?.phaseStart ?? DEFAULT_TEMPLATE_STRINGS.phaseStart,
+        phaseEnd: raw?.phaseEnd ?? DEFAULT_TEMPLATE_STRINGS.phaseEnd,
+        phaseError: raw?.phaseError ?? DEFAULT_TEMPLATE_STRINGS.phaseError,
+    };
+    return {
+        phaseStart: Handlebars.compile(merged.phaseStart),
+        phaseEnd: Handlebars.compile(merged.phaseEnd),
+        phaseError: Handlebars.compile(merged.phaseError),
+    };
+}
 function formatNumber(n) {
     return n.toLocaleString('en-US');
 }
-function formatTokens(tokens) {
-    return tokens !== undefined
-        ? formatNumber(tokens) + ' tokens'
-        : 'unknown tokens';
-}
-function formatSeconds(durationMs) {
-    const seconds = durationMs / 1000;
-    return Math.round(seconds).toString() + 's';
-}
-function titleCasePhase(phase) {
-    return phase.charAt(0).toUpperCase() + phase.slice(1);
-}
-/**
- * URL-encode each path segment individually so that spaces and special
- * characters are safe while preserving the `/` separators.
- */
-function encodePathSegments(p) {
-    return p
-        .split('/')
-        .map((seg) => encodeURIComponent(seg))
-        .join('/');
-}
-/** Build a link (or plain path) to the owner directory. */
-function buildDirectoryLink(path, serverBaseUrl) {
-    const normalized = normalizePath(path).replace(/^([A-Za-z]):/, '/$1');
-    const encoded = encodePathSegments(normalized);
-    if (!serverBaseUrl)
-        return normalized;
-    const base = serverBaseUrl.replace(/\/+$/, '');
-    return `${base}/path${encoded}`;
-}
-/** Build a link (or plain path) to the entity's meta.json output file. */
-function buildMetaJsonLink(path, serverBaseUrl) {
-    const normalized = normalizePath(path).replace(/^([A-Za-z]):/, '/$1');
-    const metaJsonPath = `${normalized}/.meta/meta.json`;
-    const encoded = encodePathSegments(metaJsonPath);
-    if (!serverBaseUrl)
-        return metaJsonPath;
-    const base = serverBaseUrl.replace(/\/+$/, '');
-    return `${base}/path${encoded}`;
-}
-function formatProgressEvent(event, serverBaseUrl) {
-    switch (event.type) {
-        case 'synthesis_start': {
-            const dirLink = buildDirectoryLink(event.path, serverBaseUrl);
-            return `🔬 Started meta synthesis: ${dirLink}`;
-        }
-        case 'phase_start': {
-            if (!event.phase) {
-                return '  ⚙️ Phase started';
-            }
-            return `  ⚙️ ${titleCasePhase(event.phase)} phase started`;
+/**
+ * Resolve a filesystem path to a browse URL via the jeeves-server
+ * resolve-path API. Returns the raw path as fallback on any failure.
+ *
+ * On HTTP 200, uses publicUrl if present, otherwise prefixes serverUrl
+ * to browseUrl. On any error or non-200 response, returns fsPath as-is.
+ */
+/** Timeout for resolve-path API calls (ms). */
+const RESOLVE_PATH_TIMEOUT_MS = 3000;
+async function resolveLink(fsPath, serverUrl) {
+    try {
+        const url = new URL('/api/resolve-path', serverUrl);
+        url.searchParams.set('fsPath', fsPath);
+        const res = await fetchWithTimeout(url.toString(), RESOLVE_PATH_TIMEOUT_MS);
+        if (!res.ok)
+            return fsPath;
+        const data = (await res.json());
+        if (data.publicUrl)
+            return data.publicUrl;
+        if (data.browseUrl) {
+            const base = serverUrl.replace(/\/+$/, '');
+            return base + data.browseUrl;
         }
+        return fsPath;
+    }
+    catch {
+        return fsPath;
+    }
+}
+/** Resolve browse links for both the owner directory and its meta.json. */
+async function resolveLinks(ownerPath, serverUrl) {
+    const dirLink = await resolveLink(ownerPath, serverUrl);
+    // Derive metaLink by appending /.meta/meta.json to the resolved dir link
+    const metaLink = dirLink.replace(/\/+$/, '') + '/.meta/meta.json';
+    return { dirLink, metaLink };
+}
+/**
+ * Render the appropriate template for a progress event.
+ *
+ * @param event - The progress event to render.
+ * @param templates - Compiled Handlebars templates.
+ * @param serverUrl - jeeves-server URL for resolve-path API.
+ * @returns Rendered message string.
+ */
+async function renderProgressEvent(event, templates, serverUrl) {
+    const ownerPath = event.path;
+    const metaPath = ownerPath.replace(/\/+$/, '') + '/.meta/meta.json';
+    const phase = (event.phase ?? 'unknown').toUpperCase();
+    const { dirLink, metaLink } = await resolveLinks(ownerPath, serverUrl);
+    const base = {
+        dirPath: ownerPath,
+        metaPath,
+        dirLink,
+        metaLink,
+        phase,
+    };
+    switch (event.type) {
+        case 'phase_start':
+            return templates.phaseStart(base);
         case 'phase_complete': {
-            const phase = event.phase ? titleCasePhase(event.phase) : 'Phase';
-            const tokenStr = formatTokens(event.tokens);
-            const duration = event.durationMs !== undefined ? formatSeconds(event.durationMs) : '0s';
-            return `  ✅ ${phase} complete (${tokenStr} / ${duration})`;
-        }
-        case 'synthesis_complete': {
-            const metaLink = buildMetaJsonLink(event.path, serverBaseUrl);
-            const tokenStr = formatTokens(event.tokens);
-            const duration = event.durationMs !== undefined
-                ? formatSeconds(event.durationMs)
-                : '0.0s';
-            return `✅ Completed: ${metaLink} (${tokenStr} / ${duration})`;
+            const seconds = event.durationMs !== undefined
+                ? String(Math.round(event.durationMs / 1000))
+                : '0';
+            const tokens = event.tokens !== undefined ? formatNumber(event.tokens) : 'unknown';
+            return templates.phaseEnd({ ...base, seconds, tokens });
         }
         case 'error': {
-            const dirLink = buildDirectoryLink(event.path, serverBaseUrl);
-            const phase = event.phase ? `${titleCasePhase(event.phase)} ` : '';
-            const error = event.error ?? 'Unknown error';
-            return `❌ Synthesis failed at ${phase}phase: ${dirLink}\n   Error: ${error}`;
+            const seconds = event.durationMs !== undefined
+                ? String(Math.round(event.durationMs / 1000))
+                : '0';
+            const errorMsg = event.error ?? 'Unknown error';
+            return templates.phaseError({ ...base, seconds, error: errorMsg });
         }
-        default: {
+        default:
             return 'Unknown progress event';
-        }
     }
 }
 class ProgressReporter {
     config;
     logger;
+    templates;
+    /** Snapshot of template source strings used to compile `this.templates`. */
+    lastTemplateSource;
+    serverUrl;
     constructor(config, logger) {
         this.config = config;
         this.logger = logger;
+        this.templates = compileTemplates(config.templates);
+        this.lastTemplateSource = JSON.stringify(config.templates);
+        this.serverUrl = config.serverUrl ?? 'http://127.0.0.1:1934';
     }
     async report(event) {
         // Multi-channel mode: reportTarget is the destination, reportChannel is the platform.
@@ -3421,7 +3448,27 @@ class ProgressReporter {
         const target = this.config.reportTarget ?? this.config.reportChannel;
         if (!target)
             return;
-        const message = formatProgressEvent(event, this.config.serverBaseUrl);
+        // Detect template hot-reload: config.templates may be mutated by
+        // applyHotReloadedConfig; recompile when the source strings change.
+        const currentSource = JSON.stringify(this.config.templates);
+        if (currentSource !== this.lastTemplateSource) {
+            try {
+                this.templates = compileTemplates(this.config.templates);
+                this.lastTemplateSource = currentSource;
+                this.logger.info('Progress templates recompiled (hot-reload)');
+            }
+            catch (err) {
+                this.logger.warn({ err }, 'Failed to compile hot-reloaded templates; keeping previous templates');
+            }
+        }
+        let message;
+        try {
+            message = await renderProgressEvent(event, this.templates, this.serverUrl);
+        }
+        catch (err) {
+            this.logger.warn({ err }, 'Progress event rendering failed');
+            return;
+        }
         const url = new URL('/tools/invoke', this.config.gatewayUrl);
         const args = {
             action: 'send',
@@ -4971,6 +5018,7 @@ function registerStatusRoute(app, deps) {
                 critic: emptyPhaseCounts(),
             };
             let nextPhase = null;
+            let metaCounts = null;
             try {
                 const metaResult = await cache.get(config, watcher);
                 // Count raw phase states (before retry) for display
@@ -4992,6 +5040,17 @@ function registerStatusRoute(app, deps) {
                         staleness: winner.effectiveStaleness,
                     };
                 }
+                // Meta counts summary
+                const summary = computeSummary(metaResult.entries, config.depthWeight);
+                metaCounts = {
+                    total: summary.total,
+                    enabled: summary.total - summary.disabled,
+                    disabled: summary.disabled,
+                    neverSynthesized: summary.neverSynthesized,
+                    stale: summary.stale,
+                    errors: summary.errors,
+                    locked: summary.locked,
+                };
             }
             catch {
                 // Watcher unreachable — phase summary unavailable
@@ -5020,6 +5079,7 @@ function registerStatusRoute(app, deps) {
                 },
                 phaseStateSummary,
                 nextPhase,
+                metaCounts,
             };
         },
     });
@@ -5329,11 +5389,10 @@ class HttpWatcherClient {
     async post(endpoint, body) {
         const url = this.baseUrl + endpoint;
         for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
-            const res = await fetch(url, {
+            const res = await fetchWithTimeout(url, this.timeoutMs, {
                 method: 'POST',
                 headers: { 'Content-Type': 'application/json' },
                 body: JSON.stringify(body),
-                signal: AbortSignal.timeout(this.timeoutMs),
             });
             if (res.ok) {
                 return res.json();
@@ -5375,25 +5434,6 @@ 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,
@@ -5470,16 +5510,7 @@ async function startService(config, configPath) {
             // Track whether synthesis_start has been emitted (deferred until
             // a phase actually begins, avoiding orphan "Started" messages
             // when the meta is skipped/locked/fresh). See #165.
-            let synthesisStartEmitted = false;
             const result = await orchestratePhase(config, executor, watcher, path, async (evt) => {
-                // Emit synthesis_start on first phase_start (deferred guard)
-                if (evt.type === 'phase_start' && !synthesisStartEmitted) {
-                    synthesisStartEmitted = true;
-                    await progress.report({
-                        type: 'synthesis_start',
-                        path: ownerPath,
-                    });
-                }
                 // Wire current-phase tracking for GET /queue and POST /synthesize/abort
                 if (evt.type === 'phase_start' && evt.phase) {
                     queue.setCurrentPhase(ownerPath, evt.phase);
@@ -5521,19 +5552,8 @@ async function startService(config, configPath) {
                 // Task #9: Reset backoff on ANY successful phase execution
                 scheduler.resetBackoff();
             }
-            // 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,
-                });
-            }
+            // Note: synthesis_complete is no longer emitted; the phaseEnd template
+            // for the final critic phase serves as the completion signal (#129).
         }
         catch (err) {
             stats.totalErrors++;
@@ -5774,4 +5794,4 @@ const metaJsonSchema = z
 })
     .loose();
 
-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, metaDescriptor, metaJsonSchema, migrateConfigPath, orchestratePhase, parseArchitectOutput, parseBuilderOutput, parseCriticOutput, pruneArchive, readLatestArchive, readLockState, registerCustomCliCommands, registerRoutes, registerShutdownHandlers, releaseLock, resolveConfigPath, resolveMetaDir, runArchitect, runBuilder, runCritic, serviceConfigSchema, 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, getScopePrefix, hasSteerChanged, isArchitectTriggered, isLocked, isStale, listArchiveFiles, listMetas, loadServiceConfig, metaDescriptor, metaJsonSchema, migrateConfigPath, orchestratePhase, parseArchitectOutput, parseBuilderOutput, parseCriticOutput, pruneArchive, readLatestArchive, readLockState, registerCustomCliCommands, registerRoutes, registerShutdownHandlers, releaseLock, renderProgressEvent, resolveConfigPath, resolveMetaDir, runArchitect, runBuilder, runCritic, serviceConfigSchema, startService, toMetaError, verifyRuleApplication };

package/dist/orchestrator/parseOutput.d.ts

@@ -26,12 +26,13 @@ export declare function parseArchitectOutput(output: string): string;
 /**
  * Parse builder output. The builder returns JSON with _content and optional fields.
  *
- * Attempts JSON parse first. If that fails, treats the entire output as _content.
+ * Attempts JSON extraction via multiple strategies. Returns null if all strategies fail
+ * (e.g. the output is plain text, self-talk, or a sub-agent delegation response).
  *
  * @param output - Raw subprocess output.
- * @returns Parsed builder output with content and structured fields.
+ * @returns Parsed builder output, or null if output is not valid builder JSON.
  */
-export declare function parseBuilderOutput(output: string): BuilderOutput;
+export declare function parseBuilderOutput(output: string): BuilderOutput | null;
 /**
  * Parse critic output. The critic returns evaluation text.
  *

package/dist/progress/index.d.ts

@@ -1,12 +1,16 @@
 /**
  * Progress reporting via OpenClaw gateway `/tools/invoke` → `message` tool.
  *
+ * Progress events are rendered using Handlebars templates. Owner-path links
+ * are resolved via the jeeves-server resolve-path API, with graceful
+ * fallback to raw filesystem paths when the server is unreachable.
+ *
  * @module progress
  */
 import type { Logger } from 'pino';
 export type ProgressPhase = 'architect' | 'builder' | 'critic';
 export type ProgressEvent = {
-    type: 'synthesis_start' | 'phase_start' | 'phase_complete' | 'synthesis_complete' | 'error';
+    type: 'phase_start' | 'phase_complete' | 'error';
     /** Owner path (not .meta path) of the entity being synthesized. */
     path: string;
     phase?: ProgressPhase;
@@ -14,6 +18,18 @@ export type ProgressEvent = {
     durationMs?: number;
     error?: string;
 };
+/** Compiled Handlebars templates for the three progress event types. */
+type CompiledTemplates = {
+    phaseStart: HandlebarsTemplateDelegate;
+    phaseEnd: HandlebarsTemplateDelegate;
+    phaseError: HandlebarsTemplateDelegate;
+};
+/** Raw (string) template config — mirrors the schema definition. */
+export type TemplateStrings = {
+    phaseStart: string;
+    phaseEnd: string;
+    phaseError: string;
+};
 export type ProgressReporterConfig = {
     gatewayUrl: string;
     gatewayApiKey?: string;
@@ -26,13 +42,32 @@ export type ProgressReporterConfig = {
     reportChannel?: string;
     /** Channel/user ID to send messages to. Takes priority over reportChannel as target. */
     reportTarget?: string;
-    /** Optional base URL for the service, used to construct entity links. */
-    serverBaseUrl?: string;
+    /**
+     * URL of the local jeeves-server instance, used to resolve filesystem paths
+     * to browse links via the resolve-path API.
+     * Default: http://127.0.0.1:1934
+     */
+    serverUrl?: string;
+    /** Handlebars template strings for each progress event type. */
+    templates?: Partial<TemplateStrings>;
 };
-export declare function formatProgressEvent(event: ProgressEvent, serverBaseUrl?: string): string;
+/**
+ * Render the appropriate template for a progress event.
+ *
+ * @param event - The progress event to render.
+ * @param templates - Compiled Handlebars templates.
+ * @param serverUrl - jeeves-server URL for resolve-path API.
+ * @returns Rendered message string.
+ */
+export declare function renderProgressEvent(event: ProgressEvent, templates: CompiledTemplates, serverUrl: string): Promise<string>;
 export declare class ProgressReporter {
     private readonly config;
     private readonly logger;
+    private templates;
+    /** Snapshot of template source strings used to compile `this.templates`. */
+    private lastTemplateSource;
+    private readonly serverUrl;
     constructor(config: ProgressReporterConfig, logger: Logger);
     report(event: ProgressEvent): Promise<void>;
 }
+export {};

package/dist/prompts/index.d.ts

@@ -4,9 +4,6 @@
  * Prompts ship as .md files bundled into dist/prompts/ via rollup-plugin-copy.
  * Loaded at runtime relative to the compiled module location.
  *
- * Users can override via `defaultArchitect` / `defaultCritic` in the service
- * config. Most installations should use the built-in defaults.
- *
  * @module prompts
  */
 /** Built-in default architect prompt. */