@karmaniverous/jeeves-meta 0.16.3 → 0.17.0

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

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { sleepAsync, createConfigQueryHandler, atomicWrite, createStatusHandler, getBindAddress, fetchJson, postJson, getServiceUrl, jeevesComponentDescriptorSchema, createServiceCli } from '@karmaniverous/jeeves';
+import { sleepAsync, fetchWithTimeout, createConfigQueryHandler, atomicWrite, createStatusHandler, getBindAddress, fetchJson, postJson, getServiceUrl, jeevesComponentDescriptorSchema, createServiceCli } from '@karmaniverous/jeeves';
 import { normalizePath, metaConfigSchema, getEndpoint, META_COMPONENT } from '@karmaniverous/jeeves-meta-core';
 import fs, { unlinkSync, writeFileSync, existsSync, readFileSync, statSync, mkdirSync, readdirSync, watchFile } from 'node:fs';
 import path, { join, dirname, relative, posix, resolve } from 'node:path';
@@ -763,6 +763,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. */
@@ -791,14 +797,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(),
     /**
-     * Optional mapping of server drive labels to absolute filesystem paths.
-     * Used on Linux to resolve absolute paths to jeeves-server browse paths.
-     * Example: `{ "content": "/opt/jeeves/content" }`
+     * 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).
      */
-    serverDriveRoots: z.record(z.string(), z.string()).optional(),
+    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. */
@@ -3055,128 +3071,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('/');
-}
-/**
- * Resolve a filesystem path to a jeeves-server browse path segment.
- *
- * - Windows: `j:/domains/foo` → `/j/domains/foo` (drive-letter transform).
- * - Linux with serverDriveRoots: `/opt/jeeves/content/slack` + roots
- *   `{ content: "/opt/jeeves/content" }` → `/content/slack`.
- * - Linux without serverDriveRoots: returns the normalized path unchanged
- *   (browse link will be invalid, but this is the pre-existing behavior).
- */
-function resolveServerPath(path, serverDriveRoots) {
-    const normalized = normalizePath(path);
-    // Windows: drive letter present — use existing transform
-    if (/^[A-Za-z]:/.test(normalized)) {
-        return normalized.replace(/^([A-Za-z]):/, '/$1');
-    }
-    // Linux: attempt serverDriveRoots resolution (longest/most-specific root wins)
-    if (serverDriveRoots) {
-        const sorted = Object.entries(serverDriveRoots)
-            .map(([label, root]) => [label, normalizePath(root).replace(/\/+$/, '')])
-            .sort((a, b) => b[1].length - a[1].length);
-        for (const [label, normalizedRoot] of sorted) {
-            if (normalized === normalizedRoot ||
-                normalized.startsWith(normalizedRoot + '/')) {
-                const relative = normalized
-                    .slice(normalizedRoot.length)
-                    .replace(/^\//, '');
-                return `/${label}${relative ? '/' + relative : ''}`;
-            }
+/**
+ * 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;
     }
-    // Fallback: no drive roots configured or no match — return as-is
-    return normalized;
-}
-/** Build a link (or plain path) to the owner directory. */
-function buildDirectoryLink(path, serverBaseUrl, serverDriveRoots) {
-    const resolved = resolveServerPath(path, serverDriveRoots);
-    const encoded = encodePathSegments(resolved);
-    if (!serverBaseUrl)
-        return resolved;
-    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, serverDriveRoots) {
-    const resolved = resolveServerPath(path, serverDriveRoots);
-    const metaJsonPath = `${resolved}/.meta/meta.json`;
-    const encoded = encodePathSegments(metaJsonPath);
-    if (!serverBaseUrl)
-        return metaJsonPath;
-    const base = serverBaseUrl.replace(/\/+$/, '');
-    return `${base}/path${encoded}`;
-}
-function formatProgressEvent(event, serverBaseUrl, serverDriveRoots) {
+    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 'synthesis_start': {
-            const dirLink = buildDirectoryLink(event.path, serverBaseUrl, serverDriveRoots);
-            return `🔬 Started meta synthesis: ${dirLink}`;
-        }
-        case 'phase_start': {
-            if (!event.phase) {
-                return '  ⚙️ Phase started';
-            }
-            return `  ⚙️ ${titleCasePhase(event.phase)} phase started`;
-        }
+        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, serverDriveRoots);
-            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, serverDriveRoots);
-            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.
@@ -3184,7 +3190,27 @@ class ProgressReporter {
         const target = this.config.reportTarget ?? this.config.reportChannel;
         if (!target)
             return;
-        const message = formatProgressEvent(event, this.config.serverBaseUrl, this.config.serverDriveRoots);
+        // 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',
@@ -4762,6 +4788,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
@@ -4783,6 +4810,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
@@ -4811,6 +4849,7 @@ function registerStatusRoute(app, deps) {
                 },
                 phaseStateSummary,
                 nextPhase,
+                metaCounts,
             };
         },
     });
@@ -5120,11 +5159,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();
@@ -5166,25 +5204,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,
@@ -5261,16 +5280,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);
@@ -5312,19 +5322,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++;

package/dist/index.d.ts

@@ -19,7 +19,7 @@ export type { InferenceRuleSpec, MetaContext, MetaExecutor, MetaSpawnOptions, Me
 export type { LoggerConfig } from './logger/index.js';
 export { createLogger, type MinimalLogger } from './logger/index.js';
 export { buildArchitectTask, buildBuilderTask, buildContextPackage, buildCriticTask, type BuilderOutput, orchestratePhase, type OrchestratePhaseResult, parseArchitectOutput, parseBuilderOutput, parseCriticOutput, type PhaseProgressCallback, type PhaseResult, runArchitect, runBuilder, runCritic, } from './orchestrator/index.js';
-export { formatProgressEvent, type ProgressEvent, type ProgressPhase, ProgressReporter, type ProgressReporterConfig, } from './progress/index.js';
+export { type ProgressEvent, type ProgressPhase, ProgressReporter, type ProgressReporterConfig, renderProgressEvent, type TemplateStrings, } from './progress/index.js';
 export { actualStaleness, computeEffectiveStaleness, hasSteerChanged, isArchitectTriggered, isStale, MAX_STALENESS_SECONDS, type StalenessCandidate, } from './scheduling/index.js';
 export { type MetaConfig, metaConfigSchema, type MetaError, metaErrorSchema, type MetaJson, metaJsonSchema, type ServiceConfig, serviceConfigSchema, } from './schema/index.js';
 export { Scheduler } from './scheduler/index.js';

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';
@@ -1252,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. */
@@ -1280,14 +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(),
     /**
-     * Optional mapping of server drive labels to absolute filesystem paths.
-     * Used on Linux to resolve absolute paths to jeeves-server browse paths.
-     * Example: `{ "content": "/opt/jeeves/content" }`
+     * 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).
      */
-    serverDriveRoots: z.record(z.string(), z.string()).optional(),
+    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. */
@@ -3313,128 +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('/');
-}
-/**
- * Resolve a filesystem path to a jeeves-server browse path segment.
- *
- * - Windows: `j:/domains/foo` → `/j/domains/foo` (drive-letter transform).
- * - Linux with serverDriveRoots: `/opt/jeeves/content/slack` + roots
- *   `{ content: "/opt/jeeves/content" }` → `/content/slack`.
- * - Linux without serverDriveRoots: returns the normalized path unchanged
- *   (browse link will be invalid, but this is the pre-existing behavior).
- */
-function resolveServerPath(path, serverDriveRoots) {
-    const normalized = normalizePath(path);
-    // Windows: drive letter present — use existing transform
-    if (/^[A-Za-z]:/.test(normalized)) {
-        return normalized.replace(/^([A-Za-z]):/, '/$1');
-    }
-    // Linux: attempt serverDriveRoots resolution (longest/most-specific root wins)
-    if (serverDriveRoots) {
-        const sorted = Object.entries(serverDriveRoots)
-            .map(([label, root]) => [label, normalizePath(root).replace(/\/+$/, '')])
-            .sort((a, b) => b[1].length - a[1].length);
-        for (const [label, normalizedRoot] of sorted) {
-            if (normalized === normalizedRoot ||
-                normalized.startsWith(normalizedRoot + '/')) {
-                const relative = normalized
-                    .slice(normalizedRoot.length)
-                    .replace(/^\//, '');
-                return `/${label}${relative ? '/' + relative : ''}`;
-            }
+/**
+ * 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;
     }
-    // Fallback: no drive roots configured or no match — return as-is
-    return normalized;
-}
-/** Build a link (or plain path) to the owner directory. */
-function buildDirectoryLink(path, serverBaseUrl, serverDriveRoots) {
-    const resolved = resolveServerPath(path, serverDriveRoots);
-    const encoded = encodePathSegments(resolved);
-    if (!serverBaseUrl)
-        return resolved;
-    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, serverDriveRoots) {
-    const resolved = resolveServerPath(path, serverDriveRoots);
-    const metaJsonPath = `${resolved}/.meta/meta.json`;
-    const encoded = encodePathSegments(metaJsonPath);
-    if (!serverBaseUrl)
-        return metaJsonPath;
-    const base = serverBaseUrl.replace(/\/+$/, '');
-    return `${base}/path${encoded}`;
-}
-function formatProgressEvent(event, serverBaseUrl, serverDriveRoots) {
+    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 'synthesis_start': {
-            const dirLink = buildDirectoryLink(event.path, serverBaseUrl, serverDriveRoots);
-            return `🔬 Started meta synthesis: ${dirLink}`;
-        }
-        case 'phase_start': {
-            if (!event.phase) {
-                return '  ⚙️ Phase started';
-            }
-            return `  ⚙️ ${titleCasePhase(event.phase)} phase started`;
-        }
+        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, serverDriveRoots);
-            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, serverDriveRoots);
-            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.
@@ -3442,7 +3448,27 @@ class ProgressReporter {
         const target = this.config.reportTarget ?? this.config.reportChannel;
         if (!target)
             return;
-        const message = formatProgressEvent(event, this.config.serverBaseUrl, this.config.serverDriveRoots);
+        // 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',
@@ -4992,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
@@ -5013,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
@@ -5041,6 +5079,7 @@ function registerStatusRoute(app, deps) {
                 },
                 phaseStateSummary,
                 nextPhase,
+                metaCounts,
             };
         },
     });
@@ -5350,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();
@@ -5396,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,
@@ -5491,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);
@@ -5542,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++;
@@ -5795,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/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,19 +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;
     /**
-     * Optional mapping of server drive labels to absolute filesystem paths.
-     * Used on Linux to resolve absolute paths to jeeves-server browse paths.
-     * Example: `{ "content": "/opt/jeeves/content" }`
+     * 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
      */
-    serverDriveRoots?: Record<string, string>;
+    serverUrl?: string;
+    /** Handlebars template strings for each progress event type. */
+    templates?: Partial<TemplateStrings>;
 };
-export declare function formatProgressEvent(event: ProgressEvent, serverBaseUrl?: string, serverDriveRoots?: Record<string, 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/schema/config.d.ts

@@ -8,6 +8,12 @@
 import { type MetaConfig, metaConfigSchema } from '@karmaniverous/jeeves-meta-core';
 import { z } from 'zod';
 export { type MetaConfig, metaConfigSchema };
+/** Default Handlebars template strings for progress reporting. Single source of truth. */
+export declare const DEFAULT_TEMPLATE_STRINGS: {
+    readonly phaseStart: ":gear: Started meta synthesis {{phase}} phase of <{{dirLink}}>";
+    readonly phaseEnd: ":white_check_mark: Completed meta synthesis {{phase}} phase ({{tokens}} tokens / {{seconds}}s) at <{{metaLink}}>";
+    readonly phaseError: ":x: Meta synthesis {{phase}} phase failed at <{{dirLink}}>\n   Error: {{error}}";
+};
 /** Zod schema for a single auto-seed policy rule. */
 declare const autoSeedRuleSchema: z.ZodObject<{
     match: z.ZodString;
@@ -34,8 +40,12 @@ export declare const serviceConfigSchema: z.ZodObject<{
     schedule: z.ZodDefault<z.ZodString>;
     reportChannel: z.ZodOptional<z.ZodString>;
     reportTarget: z.ZodOptional<z.ZodString>;
-    serverBaseUrl: z.ZodOptional<z.ZodString>;
-    serverDriveRoots: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    serverUrl: z.ZodDefault<z.ZodString>;
+    templates: z.ZodDefault<z.ZodObject<{
+        phaseStart: z.ZodDefault<z.ZodString>;
+        phaseEnd: z.ZodDefault<z.ZodString>;
+        phaseError: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>>;
     watcherHealthIntervalMs: z.ZodDefault<z.ZodNumber>;
     logging: z.ZodDefault<z.ZodObject<{
         level: z.ZodDefault<z.ZodString>;

package/dist/schema/index.d.ts

@@ -3,6 +3,6 @@
  *
  * @module schema
  */
-export { type AutoSeedRule, type MetaConfig, metaConfigSchema, type ServiceConfig, serviceConfigSchema, } from './config.js';
+export { type AutoSeedRule, DEFAULT_TEMPLATE_STRINGS, type MetaConfig, metaConfigSchema, type ServiceConfig, serviceConfigSchema, } from './config.js';
 export { type MetaError, metaErrorSchema } from './error.js';
 export { type MetaJson, metaJsonSchema, type PhaseName, phaseNames, type PhaseState, phaseStateSchema, type PhaseStatus, phaseStatuses, } from './meta.js';

package/package.json

@@ -110,5 +110,5 @@
   },
   "type": "module",
   "types": "dist/index.d.ts",
-  "version": "0.16.3"
+  "version": "0.17.0"
 }