@karmaniverous/jeeves-meta 0.16.1 → 0.16.3

package/README.md

@@ -14,10 +14,12 @@ HTTP service for the Jeeves knowledge synthesis engine. Provides a Fastify API,
 - **Cross-meta references** — `_crossRefs` declares relationships to other metas; referenced `_content` included as architect/builder context
 - **Archive management** — timestamped snapshots with configurable pruning
 - **Lock staging** — write to `.lock` → copy to `meta.json` → archive (crash-safe)
+- **Staging file retry** — configurable retries (`stagingRetries`, `stagingRetryDelayMs`) when sub-agent output file is not yet visible after session completion (network/NFS latency)
+- **Preview delta cap** — `/preview` response includes `deltaFilesTruncated` flag and `deltaCount` total when delta files exceed `previewDeltaFilesCap`
 - **Virtual rule registration** — registers 3 watcher inference rules at startup with retry
 - **Progress reporting** — real-time synthesis events via gateway channel messages
 - **Graceful shutdown** — stop scheduler, release locks, close server
-- **Built-in prompts** — default architect and critic prompts ship with the package; optional config overrides via `@file:` or inline strings
+- **Built-in prompts** — default architect and critic prompts ship with the package
 - **Handlebars templates** — prompts compiled with `{ config, meta, scope }` context; architect can write template expressions into builder briefs
 - **Config hot-reload** — all synthesis parameters reload without restart; restart-required fields (port, URLs) warn on change
 - **Auto-seed policy** — config-driven declarative `.meta/` creation via `autoSeed` rules

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

@@ -714,8 +714,6 @@ const RESTART_REQUIRED_FIELDS = [
     'watcherUrl',
     'gatewayUrl',
     'gatewayApiKey',
-    'defaultArchitect',
-    'defaultCritic',
 ];
 let runtime = null;
 /** Register the active service runtime for config-apply hot reload. */
@@ -795,6 +793,12 @@ const serviceConfigSchema = metaConfigSchema.extend({
     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" }`
+     */
+    serverDriveRoots: z.record(z.string(), z.string()).optional(),
     /** Interval in ms for periodic watcher health check. 0 = disabled. Default: 60000. */
     watcherHealthIntervalMs: z.number().int().min(0).default(60_000),
     /** Logging configuration. */
@@ -806,12 +810,20 @@ const serviceConfigSchema = metaConfigSchema.extend({
      * Rules are evaluated in order; last match wins for steer/crossRefs.
      */
     autoSeed: z.array(autoSeedRuleSchema).optional().default([]),
+    /** Optional workspace directory for synthesis staging files. Defaults to `os.tmpdir() + '/jeeves-meta'`. */
+    workspaceDir: z.string().optional(),
+    /** Max retries when staging file not yet visible after session completion. Default: 10. */
+    stagingRetries: z.number().int().min(0).default(10),
+    /** Delay between staging file retries in ms. Default: 250. */
+    stagingRetryDelayMs: z.number().int().min(0).default(250),
+    /** Maximum number of delta files returned in /preview response. Default: 50. */
+    previewDeltaFilesCap: z.number().int().min(1).default(50),
 });
 
 /**
  * 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
  */
@@ -843,24 +855,10 @@ 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');
-}
 /**
  * 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.
@@ -868,13 +866,6 @@ function resolveFileRef(value, baseDir) {
 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);
 }
 
@@ -933,12 +924,16 @@ class GatewayExecutor {
     apiKey;
     pollIntervalMs;
     workspaceDir;
+    stagingRetries;
+    stagingRetryDelayMs;
     controller = new AbortController();
     constructor(options = {}) {
         this.gatewayUrl = (options.gatewayUrl ?? 'http://127.0.0.1:18789').replace(/\/+$/, '');
         this.apiKey = options.apiKey;
         this.pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
         this.workspaceDir = options.workspaceDir ?? join(tmpdir(), 'jeeves-meta');
+        this.stagingRetries = options.stagingRetries ?? 10;
+        this.stagingRetryDelayMs = options.stagingRetryDelayMs ?? 250;
     }
     /** Remove a temp output file if it exists. */
     cleanupOutputFile(outputPath) {
@@ -1168,10 +1163,23 @@ class GatewayExecutor {
                         // No output or partial output — throw for _state recovery (§3.16.6)
                         throw new SpawnTimeoutError('Gateway-side timeout detected (session status: timeout)', outputPath);
                     }
-                    // Normal completion — read output from file
+                    // Normal completion — read staging file with retry for delayed visibility
                     const output = this.readStagingFile(outputPath);
                     if (output !== undefined)
                         return { output, tokens };
+                    // Staging file not yet visible — retry with bounded grace window
+                    for (let i = 0; i < this.stagingRetries; i++) {
+                        await sleepAsync(this.stagingRetryDelayMs);
+                        // Check abort after yield point — signal may have been
+                        // set externally (e.g. operator abort) during the sleep.
+                        if (this.aborted) {
+                            this.cleanupOutputFile(outputPath);
+                            throw new SpawnAbortedError();
+                        }
+                        const retryOutput = this.readStagingFile(outputPath);
+                        if (retryOutput !== undefined)
+                            return { output: retryOutput, tokens };
+                    }
                     // 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).
@@ -1321,9 +1329,6 @@ function packageDirectorySync({cwd, ignoreTypeOnlyPackageJson} = {}) {
  * 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({
@@ -1811,7 +1816,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}`,
@@ -1860,7 +1865,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));
 }
 /**
@@ -1875,7 +1880,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)',
@@ -2292,8 +2297,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(',');
@@ -2540,10 +2545,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);
@@ -2572,8 +2578,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) {
@@ -2701,7 +2707,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(),
@@ -2773,6 +2779,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);
@@ -2804,7 +2816,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 };
                 }
@@ -2847,7 +2860,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,
         };
@@ -3069,29 +3082,62 @@ function encodePathSegments(p) {
         .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 : ''}`;
+            }
+        }
+    }
+    // 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) {
-    const normalized = normalizePath(path).replace(/^([A-Za-z]):/, '/$1');
-    const encoded = encodePathSegments(normalized);
+function buildDirectoryLink(path, serverBaseUrl, serverDriveRoots) {
+    const resolved = resolveServerPath(path, serverDriveRoots);
+    const encoded = encodePathSegments(resolved);
     if (!serverBaseUrl)
-        return normalized;
+        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) {
-    const normalized = normalizePath(path).replace(/^([A-Za-z]):/, '/$1');
-    const metaJsonPath = `${normalized}/.meta/meta.json`;
+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) {
+function formatProgressEvent(event, serverBaseUrl, serverDriveRoots) {
     switch (event.type) {
         case 'synthesis_start': {
-            const dirLink = buildDirectoryLink(event.path, serverBaseUrl);
+            const dirLink = buildDirectoryLink(event.path, serverBaseUrl, serverDriveRoots);
             return `🔬 Started meta synthesis: ${dirLink}`;
         }
         case 'phase_start': {
@@ -3107,7 +3153,7 @@ function formatProgressEvent(event, serverBaseUrl) {
             return `  ✅ ${phase} complete (${tokenStr} / ${duration})`;
         }
         case 'synthesis_complete': {
-            const metaLink = buildMetaJsonLink(event.path, serverBaseUrl);
+            const metaLink = buildMetaJsonLink(event.path, serverBaseUrl, serverDriveRoots);
             const tokenStr = formatTokens(event.tokens);
             const duration = event.durationMs !== undefined
                 ? formatSeconds(event.durationMs)
@@ -3115,7 +3161,7 @@ function formatProgressEvent(event, serverBaseUrl) {
             return `✅ Completed: ${metaLink} (${tokenStr} / ${duration})`;
         }
         case 'error': {
-            const dirLink = buildDirectoryLink(event.path, serverBaseUrl);
+            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}`;
@@ -3138,7 +3184,7 @@ class ProgressReporter {
         const target = this.config.reportTarget ?? this.config.reportChannel;
         if (!target)
             return;
-        const message = formatProgressEvent(event, this.config.serverBaseUrl);
+        const message = formatProgressEvent(event, this.config.serverBaseUrl, this.config.serverDriveRoots);
         const url = new URL('/tools/invoke', this.config.gatewayUrl);
         const args = {
             action: 'send',
@@ -4452,9 +4498,10 @@ function registerPreviewRoute(app, deps) {
                 ownedFiles: scopeFiles.length,
                 childMetas: targetNode.children.length,
                 deltaFiles: deltaFiles
-                    .slice(0, 50)
+                    .slice(0, config.previewDeltaFilesCap)
                     .map((f) => ({ path: f, action: 'modified' })),
                 deltaCount: deltaFiles.length,
+                deltaFilesTruncated: deltaFiles.length > config.previewDeltaFilesCap,
             },
             estimatedTokens,
             // New phase-state fields (additive)
@@ -5156,6 +5203,9 @@ async function startService(config, configPath) {
     const executor = new GatewayExecutor({
         gatewayUrl: config.gatewayUrl,
         apiKey: config.gatewayApiKey,
+        workspaceDir: config.workspaceDir,
+        stagingRetries: config.stagingRetries,
+        stagingRetryDelayMs: config.stagingRetryDelayMs,
     });
     // Runtime stats (mutable, shared with routes)
     const stats = {

package/dist/configHotReload.d.ts

@@ -15,7 +15,7 @@ import type { ServiceConfig } from './schema/config.js';
  * Shared between the descriptor's `onConfigApply` and the file-watcher
  * hot-reload in `bootstrap.ts`.
  */
-export declare const RESTART_REQUIRED_FIELDS: readonly ["port", "watcherUrl", "gatewayUrl", "gatewayApiKey", "defaultArchitect", "defaultCritic"];
+export declare const RESTART_REQUIRED_FIELDS: readonly ["port", "watcherUrl", "gatewayUrl", "gatewayApiKey"];
 interface ConfigHotReloadRuntime {
     config: ServiceConfig;
     logger: Logger;

package/dist/configLoader.d.ts

@@ -1,7 +1,7 @@
 /**
  * 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
  */
@@ -28,8 +28,7 @@ export declare function resolveConfigPath(args: string[]): string;
 /**
  * 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.

package/dist/executor/GatewayExecutor.d.ts

@@ -18,6 +18,10 @@ export interface GatewayExecutorOptions {
     pollIntervalMs?: number;
     /** Workspace directory for output staging. Default: OS temp dir + /jeeves-meta. */
     workspaceDir?: string;
+    /** Max retries when staging file not yet visible after session completion. Default: 10. */
+    stagingRetries?: number;
+    /** Delay between retries in ms. Default: 250. */
+    stagingRetryDelayMs?: number;
 }
 /**
  * MetaExecutor that spawns OpenClaw sessions via the gateway's
@@ -32,6 +36,8 @@ export declare class GatewayExecutor implements MetaExecutor {
     private readonly apiKey;
     private readonly pollIntervalMs;
     private readonly workspaceDir;
+    private readonly stagingRetries;
+    private readonly stagingRetryDelayMs;
     private controller;
     constructor(options?: GatewayExecutorOptions);
     /** Remove a temp output file if it exists. */

package/dist/index.js

@@ -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. */
@@ -1284,6 +1282,12 @@ const serviceConfigSchema = metaConfigSchema.extend({
     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" }`
+     */
+    serverDriveRoots: z.record(z.string(), z.string()).optional(),
     /** Interval in ms for periodic watcher health check. 0 = disabled. Default: 60000. */
     watcherHealthIntervalMs: z.number().int().min(0).default(60_000),
     /** Logging configuration. */
@@ -1295,12 +1299,20 @@ const serviceConfigSchema = metaConfigSchema.extend({
      * Rules are evaluated in order; last match wins for steer/crossRefs.
      */
     autoSeed: z.array(autoSeedRuleSchema).optional().default([]),
+    /** Optional workspace directory for synthesis staging files. Defaults to `os.tmpdir() + '/jeeves-meta'`. */
+    workspaceDir: z.string().optional(),
+    /** Max retries when staging file not yet visible after session completion. Default: 10. */
+    stagingRetries: z.number().int().min(0).default(10),
+    /** Delay between staging file retries in ms. Default: 250. */
+    stagingRetryDelayMs: z.number().int().min(0).default(250),
+    /** Maximum number of delta files returned in /preview response. Default: 50. */
+    previewDeltaFilesCap: z.number().int().min(1).default(50),
 });
 
 /**
  * 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
  */
@@ -1332,19 +1344,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.
  *
@@ -1393,8 +1392,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.
@@ -1402,13 +1400,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);
 }
 
@@ -1467,12 +1458,16 @@ class GatewayExecutor {
     apiKey;
     pollIntervalMs;
     workspaceDir;
+    stagingRetries;
+    stagingRetryDelayMs;
     controller = new AbortController();
     constructor(options = {}) {
         this.gatewayUrl = (options.gatewayUrl ?? 'http://127.0.0.1:18789').replace(/\/+$/, '');
         this.apiKey = options.apiKey;
         this.pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
         this.workspaceDir = options.workspaceDir ?? join(tmpdir(), 'jeeves-meta');
+        this.stagingRetries = options.stagingRetries ?? 10;
+        this.stagingRetryDelayMs = options.stagingRetryDelayMs ?? 250;
     }
     /** Remove a temp output file if it exists. */
     cleanupOutputFile(outputPath) {
@@ -1702,10 +1697,23 @@ class GatewayExecutor {
                         // No output or partial output — throw for _state recovery (§3.16.6)
                         throw new SpawnTimeoutError('Gateway-side timeout detected (session status: timeout)', outputPath);
                     }
-                    // Normal completion — read output from file
+                    // Normal completion — read staging file with retry for delayed visibility
                     const output = this.readStagingFile(outputPath);
                     if (output !== undefined)
                         return { output, tokens };
+                    // Staging file not yet visible — retry with bounded grace window
+                    for (let i = 0; i < this.stagingRetries; i++) {
+                        await sleepAsync(this.stagingRetryDelayMs);
+                        // Check abort after yield point — signal may have been
+                        // set externally (e.g. operator abort) during the sleep.
+                        if (this.aborted) {
+                            this.cleanupOutputFile(outputPath);
+                            throw new SpawnAbortedError();
+                        }
+                        const retryOutput = this.readStagingFile(outputPath);
+                        if (retryOutput !== undefined)
+                            return { output: retryOutput, tokens };
+                    }
                     // 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).
@@ -1767,9 +1775,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({
@@ -2069,7 +2074,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}`,
@@ -2118,7 +2123,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));
 }
 /**
@@ -2133,7 +2138,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)',
@@ -2550,8 +2555,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(',');
@@ -2798,10 +2803,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);
@@ -2830,8 +2836,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) {
@@ -2959,7 +2965,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(),
@@ -3031,6 +3037,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);
@@ -3062,7 +3074,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 };
                 }
@@ -3105,7 +3118,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,
         };
@@ -3327,29 +3340,62 @@ function encodePathSegments(p) {
         .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 : ''}`;
+            }
+        }
+    }
+    // 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) {
-    const normalized = normalizePath(path).replace(/^([A-Za-z]):/, '/$1');
-    const encoded = encodePathSegments(normalized);
+function buildDirectoryLink(path, serverBaseUrl, serverDriveRoots) {
+    const resolved = resolveServerPath(path, serverDriveRoots);
+    const encoded = encodePathSegments(resolved);
     if (!serverBaseUrl)
-        return normalized;
+        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) {
-    const normalized = normalizePath(path).replace(/^([A-Za-z]):/, '/$1');
-    const metaJsonPath = `${normalized}/.meta/meta.json`;
+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) {
+function formatProgressEvent(event, serverBaseUrl, serverDriveRoots) {
     switch (event.type) {
         case 'synthesis_start': {
-            const dirLink = buildDirectoryLink(event.path, serverBaseUrl);
+            const dirLink = buildDirectoryLink(event.path, serverBaseUrl, serverDriveRoots);
             return `🔬 Started meta synthesis: ${dirLink}`;
         }
         case 'phase_start': {
@@ -3365,7 +3411,7 @@ function formatProgressEvent(event, serverBaseUrl) {
             return `  ✅ ${phase} complete (${tokenStr} / ${duration})`;
         }
         case 'synthesis_complete': {
-            const metaLink = buildMetaJsonLink(event.path, serverBaseUrl);
+            const metaLink = buildMetaJsonLink(event.path, serverBaseUrl, serverDriveRoots);
             const tokenStr = formatTokens(event.tokens);
             const duration = event.durationMs !== undefined
                 ? formatSeconds(event.durationMs)
@@ -3373,7 +3419,7 @@ function formatProgressEvent(event, serverBaseUrl) {
             return `✅ Completed: ${metaLink} (${tokenStr} / ${duration})`;
         }
         case 'error': {
-            const dirLink = buildDirectoryLink(event.path, serverBaseUrl);
+            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}`;
@@ -3396,7 +3442,7 @@ class ProgressReporter {
         const target = this.config.reportTarget ?? this.config.reportChannel;
         if (!target)
             return;
-        const message = formatProgressEvent(event, this.config.serverBaseUrl);
+        const message = formatProgressEvent(event, this.config.serverBaseUrl, this.config.serverDriveRoots);
         const url = new URL('/tools/invoke', this.config.gatewayUrl);
         const args = {
             action: 'send',
@@ -4710,9 +4756,10 @@ function registerPreviewRoute(app, deps) {
                 ownedFiles: scopeFiles.length,
                 childMetas: targetNode.children.length,
                 deltaFiles: deltaFiles
-                    .slice(0, 50)
+                    .slice(0, config.previewDeltaFilesCap)
                     .map((f) => ({ path: f, action: 'modified' })),
                 deltaCount: deltaFiles.length,
+                deltaFilesTruncated: deltaFiles.length > config.previewDeltaFilesCap,
             },
             estimatedTokens,
             // New phase-state fields (additive)
@@ -5386,6 +5433,9 @@ async function startService(config, configPath) {
     const executor = new GatewayExecutor({
         gatewayUrl: config.gatewayUrl,
         apiKey: config.gatewayApiKey,
+        workspaceDir: config.workspaceDir,
+        stagingRetries: config.stagingRetries,
+        stagingRetryDelayMs: config.stagingRetryDelayMs,
     });
     // Runtime stats (mutable, shared with routes)
     const stats = {

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

@@ -28,8 +28,14 @@ export type ProgressReporterConfig = {
     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" }`
+     */
+    serverDriveRoots?: Record<string, string>;
 };
-export declare function formatProgressEvent(event: ProgressEvent, serverBaseUrl?: string): string;
+export declare function formatProgressEvent(event: ProgressEvent, serverBaseUrl?: string, serverDriveRoots?: Record<string, string>): string;
 export declare class ProgressReporter {
     private readonly config;
     private readonly logger;

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. */

package/dist/schema/config.d.ts

@@ -27,16 +27,15 @@ export declare const serviceConfigSchema: z.ZodObject<{
     maxArchive: z.ZodDefault<z.ZodNumber>;
     maxLines: z.ZodDefault<z.ZodNumber>;
     thinking: z.ZodDefault<z.ZodString>;
-    defaultArchitect: z.ZodOptional<z.ZodString>;
-    defaultCritic: z.ZodOptional<z.ZodString>;
     skipUnchanged: z.ZodDefault<z.ZodBoolean>;
-    metaProperty: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    metaArchiveProperty: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    metaProperty: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    metaArchiveProperty: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     port: z.ZodDefault<z.ZodNumber>;
     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>>;
     watcherHealthIntervalMs: z.ZodDefault<z.ZodNumber>;
     logging: z.ZodDefault<z.ZodObject<{
         level: z.ZodDefault<z.ZodString>;
@@ -49,6 +48,10 @@ export declare const serviceConfigSchema: z.ZodObject<{
         crossRefs: z.ZodOptional<z.ZodArray<z.ZodString>>;
         parentDepth: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>>>;
+    workspaceDir: z.ZodOptional<z.ZodString>;
+    stagingRetries: z.ZodDefault<z.ZodNumber>;
+    stagingRetryDelayMs: z.ZodDefault<z.ZodNumber>;
+    previewDeltaFilesCap: z.ZodDefault<z.ZodNumber>;
 }, z.core.$strip>;
 /** Inferred type for service configuration. */
 export type ServiceConfig = z.infer<typeof serviceConfigSchema>;

package/package.json

@@ -8,7 +8,7 @@
   },
   "dependencies": {
     "@karmaniverous/jeeves": "^0.5.12",
-    "@karmaniverous/jeeves-meta-core": "^0.2.0",
+    "@karmaniverous/jeeves-meta-core": "^0.2.2",
     "commander": "^14",
     "croner": "^10",
     "fastify": "^5.8",
@@ -110,5 +110,5 @@
   },
   "type": "module",
   "types": "dist/index.d.ts",
-  "version": "0.16.1"
+  "version": "0.16.3"
 }