maka-agent 0.2.0-dev.6.20260830 → 0.2.0-dev.64.20260929

package/node_modules/@maka/runtime/dist/execution-inspect.js

@@ -16,25 +16,26 @@
  * specific language governing permissions and limitations
  * under the License.
  */
+import { runtimeInvocationOutcome } from '@maka/core/runtime-invocation';
 import { AGENT_RUN_INSPECT_DOCUMENT_VERSION, SESSION_INSPECT_DOCUMENT_VERSION, } from '@maka/core/execution-inspect';
 import { inspectAgentRunReadModel, } from './agent-run-inspect.js';
-import { validateHistoryCompactCheckpointShape, } from './history-compact-checkpoint.js';
+import { isSupersededHistoryCompactCheckpoint, validateHistoryCompactCheckpointShape, } from './history-compact-checkpoint.js';
 export async function inspectAgentRunDocument(runStore, runtimeEventStore, input) {
     const model = await inspectAgentRunReadModel(runStore, runtimeEventStore, {
         sessionId: input.sessionId,
         runId: input.agentRunId,
-        ...(input.header ? { header: input.header } : {}),
+        ...(input.invocation ? { invocation: input.invocation } : {}),
         ...(input.isFatalReadError ? { isFatalReadError: input.isFatalReadError } : {}),
         includeModelReplay: false,
     });
-    const diagnostics = model.diagnostics.map((item) => sourceDiagnostic(model.header, item));
-    const tools = inspectTools(model.header, model.runtimeEvents, diagnostics);
-    const compactionCheckpoints = inspectCompactionCheckpoints(model.header, model.events, diagnostics);
-    const runtimeCoverage = coverageFor(model.header.runId, model.runtimeEvents);
+    const diagnostics = model.diagnostics.map((item) => sourceDiagnostic(model.invocation, item));
+    const tools = inspectTools(model.invocation, model.runtimeEvents, diagnostics);
+    const compactionCheckpoints = inspectCompactionCheckpoints(model.invocation, model.events, diagnostics);
+    const runtimeCoverage = coverageFor(model.invocation.runId, model.runtimeEvents);
     return {
         schemaVersion: AGENT_RUN_INSPECT_DOCUMENT_VERSION,
         kind: 'agent_run',
-        agentRun: inspectIdentity(model.header),
+        agentRun: inspectIdentity(model.invocation),
         sources: {
             operationalEventCount: model.events.length,
             runtimeEventCount: model.runtimeEvents.length,
@@ -48,13 +49,13 @@ export async function inspectAgentRunDocument(runStore, runtimeEventStore, input
 }
 export async function inspectSessionDocument(sessionStore, runStore, runtimeEventStore, sessionId, options = {}) {
     const resolvedHeader = options.header ?? (await sessionStore.readHeader(sessionId));
-    const runHeaders = options.runHeaders ?? (await runStore.listSessionRuns(sessionId));
+    const invocations = options.invocations ?? (await runtimeEventStore.listSessionInvocations(sessionId));
     const agentRuns = [];
-    for (const runHeader of runHeaders) {
+    for (const invocation of invocations) {
         agentRuns.push(await inspectAgentRunDocument(runStore, runtimeEventStore, {
             sessionId,
-            agentRunId: runHeader.runId,
-            header: runHeader,
+            agentRunId: invocation.runId,
+            invocation,
             ...(options.isFatalReadError ? { isFatalReadError: options.isFatalReadError } : {}),
         }));
     }
@@ -100,7 +101,7 @@ export function renderAgentRunInspectTree(document) {
         `├─ Turn ${run.turnId}`,
         `├─ Runtime Events ${formatCoverage(document.sources.runtimeCoverage)} (${document.sources.runtimeEventCount})`,
         `├─ Operational Events ${document.sources.operationalEventCount}`,
-        `├─ Source Health [${document.sources.health.statusConsistency}]`,
+        `├─ Source Health [runtime ledger ${document.sources.health.runtimeLedger}]`,
         `├─ Tools ${document.tools.callCount} calls / ${document.tools.responseCount} responses`,
     ];
     for (const checkpoint of document.compactionCheckpoints) {
@@ -129,26 +130,30 @@ export function renderSessionInspectTree(document) {
     });
     return `${lines.join('\n')}\n`;
 }
-function inspectIdentity(header) {
+function inspectIdentity(invocation) {
+    const lineage = invocation.opening.lineage;
+    const terminal = invocation.terminalEvent;
+    const stateDelta = terminal?.actions?.stateDelta;
+    const failureClass = typeof stateDelta?.failureClass === 'string' ? stateDelta.failureClass : undefined;
+    const abortSource = typeof stateDelta?.abortSource === 'string' ? stateDelta.abortSource : undefined;
     return {
-        sessionId: header.sessionId,
-        agentRunId: header.runId,
-        ...(header.invocationId ? { invocationId: header.invocationId } : {}),
-        turnId: header.turnId,
-        ...(header.parentRunId ? { parentRunId: header.parentRunId } : {}),
-        ...(header.resumedFromRunId ? { resumedFromRunId: header.resumedFromRunId } : {}),
-        ...(header.retriedFromRunId ? { retriedFromRunId: header.retriedFromRunId } : {}),
-        ...(header.parentTurnId ? { parentTurnId: header.parentTurnId } : {}),
-        ...(header.agentId ? { agentId: header.agentId } : {}),
-        status: header.status,
-        createdAt: header.createdAt,
-        updatedAt: header.updatedAt,
-        ...(header.completedAt !== undefined ? { completedAt: header.completedAt } : {}),
-        ...(header.failureClass ? { failureClass: header.failureClass } : {}),
-        ...(header.abortSource ? { abortSource: header.abortSource } : {}),
+        sessionId: invocation.sessionId,
+        agentRunId: invocation.runId,
+        invocationId: invocation.invocationId,
+        turnId: invocation.turnId,
+        ...(lineage?.parentRunId ? { parentRunId: lineage.parentRunId } : {}),
+        ...(lineage?.resumedFromRunId ? { resumedFromRunId: lineage.resumedFromRunId } : {}),
+        ...(lineage?.retriedFromRunId ? { retriedFromRunId: lineage.retriedFromRunId } : {}),
+        ...(lineage?.parentTurnId ? { parentTurnId: lineage.parentTurnId } : {}),
+        ...(lineage?.agentId ? { agentId: lineage.agentId } : {}),
+        status: runtimeInvocationOutcome(invocation) ?? 'running',
+        openedAt: invocation.openedAt,
+        ...(terminal ? { endedAt: terminal.ts } : {}),
+        ...(failureClass ? { failureClass } : {}),
+        ...(abortSource ? { abortSource } : {}),
     };
 }
-function inspectTools(header, events, diagnostics) {
+function inspectTools(invocation, events, diagnostics) {
     const calls = new Map();
     const responses = new Map();
     for (const event of events) {
@@ -173,10 +178,10 @@ function inspectTools(header, events, diagnostics) {
         .filter((response) => !calls.has(response.toolCallId))
         .map(({ isError: _isError, ...response }) => response);
     for (const call of callsWithoutResponse) {
-        diagnostics.push(diagnostic(header, 'tool_response_missing', 'warning', `Tool Call ${call.toolCallId} has no committed Runtime response; its outcome and external side effects are unknown.`, call.eventId));
+        diagnostics.push(diagnostic(invocation, 'tool_response_missing', 'warning', `Tool Call ${call.toolCallId} has no committed Runtime response; its outcome and external side effects are unknown.`, call.eventId));
     }
     for (const response of responsesWithoutCall) {
-        diagnostics.push(diagnostic(header, 'tool_call_missing', 'warning', `Tool response ${response.toolCallId} has no matching Runtime call fact.`, response.eventId));
+        diagnostics.push(diagnostic(invocation, 'tool_call_missing', 'warning', `Tool response ${response.toolCallId} has no matching Runtime call fact.`, response.eventId));
     }
     return {
         callCount: calls.size,
@@ -186,15 +191,25 @@ function inspectTools(header, events, diagnostics) {
         responsesWithoutCall,
     };
 }
-function inspectCompactionCheckpoints(header, events, diagnostics) {
+function inspectCompactionCheckpoints(invocation, events, diagnostics) {
     const checkpoints = [];
     for (const event of events) {
         if (event.type !== 'history_compact_checkpoint_recorded')
             continue;
         const checkpoint = event.data?.checkpoint;
-        if (!validateHistoryCompactCheckpointShape(checkpoint, header.sessionId)) {
-            diagnostics.push(diagnostic(header, 'compaction_checkpoint_invalid', 'error', 'AgentRun contains an invalid durable Compaction checkpoint record.', event.id));
-            checkpoints.push({ eventId: event.id, validation: 'invalid' });
+        if (!validateHistoryCompactCheckpointShape(checkpoint, invocation.sessionId)) {
+            // A checkpoint recorded under an older source policy is expected history,
+            // not corruption: the ledger keeps every checkpoint it ever wrote, and
+            // every consumer fails open on it. Reporting it as an error would drown
+            // out the records that really are damaged.
+            const superseded = isSupersededHistoryCompactCheckpoint(checkpoint);
+            diagnostics.push(diagnostic(invocation, superseded ? 'compaction_checkpoint_superseded' : 'compaction_checkpoint_invalid', superseded ? 'info' : 'error', superseded
+                ? 'AgentRun contains a durable Compaction checkpoint from a superseded source policy; it is ignored and re-created on demand.'
+                : 'AgentRun contains an invalid durable Compaction checkpoint record.', event.id));
+            checkpoints.push({
+                eventId: event.id,
+                validation: superseded ? 'superseded' : 'invalid',
+            });
             continue;
         }
         const valid = checkpoint;
@@ -208,22 +223,22 @@ function inspectCompactionCheckpoints(header, events, diagnostics) {
     }
     return checkpoints;
 }
-function sourceDiagnostic(header, source) {
+function sourceDiagnostic(invocation, source) {
     const severity = /read_failed|corrupt|mismatch/.test(source.code)
         ? 'error'
         : source.code.includes('missing')
             ? 'warning'
             : 'info';
-    return diagnostic(header, source.code, severity, source.message, source.eventId);
+    return diagnostic(invocation, source.code, severity, source.message, source.eventId);
 }
-function diagnostic(header, code, severity, message, eventId) {
+function diagnostic(invocation, code, severity, message, eventId) {
     return {
         severity,
         code,
         message,
-        sessionId: header.sessionId,
-        agentRunId: header.runId,
-        turnId: header.turnId,
+        sessionId: invocation.sessionId,
+        agentRunId: invocation.runId,
+        turnId: invocation.turnId,
         ...(eventId ? { eventId } : {}),
     };
 }

package/node_modules/@maka/runtime/dist/filesystem-executor.js

@@ -27,6 +27,8 @@
 // skipped the worker, so that undeclared rule became the only arbiter and made
 // "full access" stricter than ask mode, which grants :slash_tmp outright (#2083).
 import { Buffer } from 'node:buffer';
+import { readPage } from './read-page.js';
+import { formatJsonText } from './format-json.js';
 import { lstat, realpath, stat } from 'node:fs/promises';
 import { isAbsolute } from 'node:path';
 import { ToolOutcomeUnknownError } from '@maka/core/events';
@@ -37,7 +39,7 @@ import { StableWriteFailure } from './file-stable-write.js';
 import { applyUpdateToContent } from './apply-patch-file.js';
 import { withFileWriteLock } from './file-write-lock.js';
 import { isSupportedImagePath } from './image-file.js';
-import { operationAccess } from './filesystem-worker/protocol.js';
+import { FilesystemWorkerOperationSchema, operationAccess } from './filesystem-worker/protocol.js';
 import { resolveCanonicalDirectoryEntryTarget } from './path-containment.js';
 import { normalizeSandboxBoundaryPath } from './sandbox-boundary-path.js';
 import { SandboxCommandError } from './sandbox/errors.js';
@@ -113,6 +115,8 @@ export function createBoundaryFilesystemExecutor(input) {
         });
     };
     async function run(call, expectedIdentity) {
+        if (call.operation.kind === 'read')
+            FilesystemWorkerOperationSchema.parse({ ...call.operation, cwd: call.cwd });
         const worker = workerFor(call.executionBoundary);
         if (!worker) {
             // The local backend consumes the same identity authority as the worker
@@ -266,13 +270,14 @@ function createWorkspaceFilesystemExecutor(workspace) {
                     const result = await workspace.readFile({
                         cwd,
                         path,
-                        ...(operation.offset !== undefined ? { offset: operation.offset } : {}),
-                        ...(operation.limit !== undefined ? { limit: operation.limit } : {}),
                     });
                     if ('bytes' in result) {
                         return { kind: 'read_image', bytes: result.bytes, mimeType: result.mimeType };
                     }
-                    return { kind: 'read', content: result.content };
+                    return {
+                        kind: 'read',
+                        ...readPage(result.content, operation, undefined, operation.continuation),
+                    };
                 }
                 case 'write': {
                     const { path } = await workspace.resolveWritablePath({
@@ -432,10 +437,7 @@ function createWorkspaceFilesystemExecutor(workspace) {
                             transform: (ctx) => {
                                 original = ctx.content ?? '';
                                 try {
-                                    const value = operation.sortKeys
-                                        ? sortKeysDeep(JSON.parse(original))
-                                        : JSON.parse(original);
-                                    return JSON.stringify(value, null, 2);
+                                    return formatJsonText(original, operation.sortKeys ?? false);
                                 }
                                 catch (error) {
                                     parseError = error instanceof Error ? error.message : 'parse failed';
@@ -476,9 +478,9 @@ function createWorkspaceFilesystemExecutor(workspace) {
                         throw new Error('FormatJson does not support image files.');
                     const original = read.content;
                     const bytesBefore = Buffer.byteLength(original, 'utf8');
-                    let parsed;
+                    let formatted;
                     try {
-                        parsed = JSON.parse(original);
+                        formatted = formatJsonText(original, operation.sortKeys ?? false);
                     }
                     catch (error) {
                         return {
@@ -492,8 +494,6 @@ function createWorkspaceFilesystemExecutor(workspace) {
                             changed: false,
                         };
                     }
-                    const value = operation.sortKeys ? sortKeysDeep(parsed) : parsed;
-                    const formatted = JSON.stringify(value, null, 2);
                     const { bytes: bytesAfter } = await workspace.writeFile({
                         cwd,
                         path,
@@ -520,12 +520,13 @@ function createWorkspaceFilesystemExecutor(workspace) {
                         label: 'Glob cwd',
                         scope,
                     });
-                    const { files } = await workspace.globFiles({
+                    const { files, truncated } = await workspace.globFiles({
                         cwd: base,
                         pattern: operation.pattern,
                         ...(operation.limit !== undefined ? { limit: operation.limit } : {}),
+                        ...(abortSignal ? { abortSignal } : {}),
                     });
-                    return { kind: 'glob', files };
+                    return { kind: 'glob', files, truncated };
                 }
                 case 'grep': {
                     const { path } = await workspace.resolveExistingPath({
@@ -534,7 +535,7 @@ function createWorkspaceFilesystemExecutor(workspace) {
                         label: 'Grep',
                         scope,
                     });
-                    const { matches } = await workspace.grepFiles({
+                    const result = await workspace.grepFiles({
                         cwd,
                         pattern: operation.pattern,
                         path,
@@ -544,7 +545,7 @@ function createWorkspaceFilesystemExecutor(workspace) {
                         timeoutMs: operation.timeoutMs,
                         ...(abortSignal ? { abortSignal } : {}),
                     });
-                    return { kind: 'grep', matches };
+                    return { kind: 'grep', ...result };
                 }
             }
         },
@@ -566,15 +567,3 @@ function assertGlobPatternInScope(pattern, scope) {
 async function canonicalExistingPath(path) {
     return await realpath(path).catch(() => path);
 }
-// Object.fromEntries creates own data properties, so special keys like
-// "__proto__" are preserved instead of triggering the inherited setter.
-function sortKeysDeep(value) {
-    if (Array.isArray(value))
-        return value.map(sortKeysDeep);
-    if (value !== null && typeof value === 'object' && !(value instanceof Date)) {
-        return Object.fromEntries(Object.keys(value)
-            .sort()
-            .map((key) => [key, sortKeysDeep(value[key])]));
-    }
-    return value;
-}

package/node_modules/@maka/runtime/dist/filesystem-worker/client.js

@@ -19,10 +19,11 @@
 import { randomUUID } from 'node:crypto';
 import { lstat, realpath } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
-import { dirname } from 'node:path';
+import { dirname, join } from 'node:path';
 import { canReadPath, canWritePath } from '@maka/core/permission-profile';
 import { compilePermissionProfile } from '@maka/core/permission-profile-compiler';
 import { normalizeSandboxBoundaryPath } from '../sandbox-boundary-path.js';
+import { MAX_CHILD_FD } from '../child-fd-input.js';
 import { resolveCanonicalDirectoryEntryTarget } from '../path-containment.js';
 import { pinExistingLinuxProfilePath } from '../sandbox/linux-profile-path.js';
 import { classifyWindowsBrokerFailure } from '../sandbox/windows-broker-errors.js';
@@ -224,10 +225,40 @@ export class FilesystemWorkerClient {
         if (Buffer.byteLength(requestJson, 'utf8') > FILESYSTEM_WORKER_MAX_REQUEST_BYTES) {
             throw clientError('request_overflow', 'validation', requestId);
         }
-        const launch = await this.input.getLaunchSpec();
+        const launch = await this.input.getLaunchSpec(operation);
         if (!launch.ok)
             throw clientError(launch.reason, 'launch', requestId, launch.message);
-        const workerProfile = deriveWorkerProfile(effectiveProfile, operationBoundary);
+        const searchMetadata = [];
+        if (operation.kind === 'grep' && target.targetType === 'directory') {
+            // Narrow the data scan to its target without dropping already-authorized
+            // ancestor ignore rules. Configuration files never grant their parent tree.
+            for (let parent = dirname(target.enforcementPath);; parent = dirname(parent)) {
+                for (const name of ['.gitignore', '.ignore', '.rgignore', '.git', '.git/info/exclude']) {
+                    const path = join(parent, name);
+                    if (!canReadPath(effectiveProfile, path, pathContext))
+                        continue;
+                    const canonical = await realpath(path).catch(() => undefined);
+                    if (canonical && canReadPath(effectiveProfile, canonical, pathContext)) {
+                        const metadata = await lstat(canonical).catch(() => undefined);
+                        if (metadata?.isFile() || (name === '.git' && metadata?.isDirectory())) {
+                            searchMetadata.push({
+                                path,
+                                canonicalPath: canonical,
+                                targetType: metadata.isDirectory() ? 'directory' : 'file',
+                            });
+                        }
+                    }
+                }
+                if (dirname(parent) === parent)
+                    break;
+            }
+        }
+        const firstMetadataFd = 5;
+        if (platform === 'linux' &&
+            searchMetadata.some(({ targetType }, index) => targetType === 'file' && firstMetadataFd + index > MAX_CHILD_FD)) {
+            throw clientError('request_overflow', 'validation', requestId, 'Too many ancestor ignore files for one Grep operation. Search from a higher-level directory.');
+        }
+        const workerProfile = deriveWorkerProfile(effectiveProfile, operationBoundary, searchMetadata.map(({ path, canonicalPath }) => platform === 'linux' ? path : canonicalPath));
         const pinnedTarget = platform === 'linux' && !entryMode && target.targetType !== 'missing'
             ? (() => {
                 try {
@@ -270,7 +301,30 @@ export class FilesystemWorkerClient {
             throw clientError('path_changed', 'validation', requestId, 'The approved filesystem target parent changed before sandbox launch.');
         }
         let transformed;
+        const pinnedMetadata = [];
+        const releasePinnedPaths = () => {
+            pinnedTarget?.releaseSource();
+            pinnedRuntimeWritableRoot?.releaseSource();
+            for (const pinned of pinnedMetadata)
+                pinned.releaseSource();
+        };
         try {
+            if (platform === 'linux') {
+                for (const metadata of searchMetadata) {
+                    const pinned = pinExistingLinuxProfilePath({
+                        path: metadata.canonicalPath,
+                        targetType: metadata.targetType,
+                        access: 'read',
+                        childFd: firstMetadataFd + pinnedMetadata.length,
+                    });
+                    if (!pinned) {
+                        throw clientError('path_changed', 'validation', requestId);
+                    }
+                    // rg opens the ancestor's lexical name. Bind the verified canonical
+                    // source there even when the original metadata entry was a symlink.
+                    pinnedMetadata.push({ ...pinned, path: metadata.path });
+                }
+            }
             transformed = this.input.sandboxManager.transform({
                 platform,
                 command: {
@@ -283,17 +337,18 @@ export class FilesystemWorkerClient {
                         ...pathContext,
                         runtimeReadableRoots: launch.spec.runtimeReadableRoots,
                         executableRoots: launch.spec.executableRoots,
-                        ...(pinnedTarget
+                        ...(pinnedTarget || pinnedMetadata.length
                             ? {
                                 pinnedProfilePaths: [
-                                    {
-                                        path: pinnedTarget.path,
-                                        access: pinnedTarget.access,
-                                        fd: pinnedTarget.childFd,
-                                        sourceFd: pinnedTarget.sourceFd,
-                                        releaseSource: pinnedTarget.releaseSource,
-                                    },
-                                ],
+                                    ...(pinnedTarget ? [pinnedTarget] : []),
+                                    ...pinnedMetadata,
+                                ].map((pinned) => ({
+                                    path: pinned.path,
+                                    access: pinned.access,
+                                    fd: pinned.childFd,
+                                    sourceFd: pinned.sourceFd,
+                                    releaseSource: pinned.releaseSource,
+                                })),
                             }
                             : {}),
                         ...(pinnedRuntimeWritableRoot
@@ -313,13 +368,11 @@ export class FilesystemWorkerClient {
             });
         }
         catch (error) {
-            pinnedTarget?.releaseSource();
-            pinnedRuntimeWritableRoot?.releaseSource();
+            releasePinnedPaths();
             throw error;
         }
         if (!transformed.ok) {
-            pinnedTarget?.releaseSource();
-            pinnedRuntimeWritableRoot?.releaseSource();
+            releasePinnedPaths();
             throw clientError(transformed.reason, 'transform', requestId, transformed.message, false, {
                 backend: transformed.sandboxType,
                 profileName: effectiveProfile.name ?? effectiveProfile.type,
@@ -348,8 +401,7 @@ export class FilesystemWorkerClient {
             throw clientError(dispatched ? 'worker_io_incomplete' : 'spawn_failed', 'launch', requestId, undefined, false, {}, dispatched);
         }
         finally {
-            pinnedTarget?.releaseSource();
-            pinnedRuntimeWritableRoot?.releaseSource();
+            releasePinnedPaths();
         }
         if (processResult.timedOut) {
             throw clientError('timeout', 'launch', requestId, undefined, false, {}, processResult.dispatched);
@@ -414,7 +466,7 @@ export function filesystemWorkerRuntimeWritableRoots(input) {
         return input.writableAncestor ? [input.writableAncestor] : undefined;
     return input.targetType === 'missing' ? [dirname(input.enforcementPath)] : undefined;
 }
-function deriveWorkerProfile(profile, operationBoundary) {
+function deriveWorkerProfile(profile, operationBoundary, searchMetadata) {
     if (profile.type !== 'managed' || profile.fileSystem.kind !== 'restricted')
         return profile;
     const target = operationBoundary.filesystem.entries[0];
@@ -430,6 +482,12 @@ function deriveWorkerProfile(profile, operationBoundary) {
                     access: target.access,
                     match: target.scope,
                 },
+                ...searchMetadata.map((path) => ({
+                    kind: 'path',
+                    path,
+                    access: 'read',
+                    match: 'exact',
+                })),
             ],
         },
         network: { kind: 'restricted' },

package/node_modules/@maka/runtime/dist/filesystem-worker/launch-spec.js

@@ -18,12 +18,23 @@
  */
 import { constants } from 'node:fs';
 import { access, realpath } from 'node:fs/promises';
-import { delimiter, dirname, isAbsolute, join, resolve } from 'node:path';
+import { dirname, isAbsolute, resolve } from 'node:path';
 import { resolveFilesystemWorkerBundle, } from './resource-resolver.js';
 import { resolveMacosExecutableDependencies, } from './macos-executable-dependencies.js';
+import { currentRipgrepEnvironment, formatRipgrepEnvironmentArg, } from '../ripgrep-guidance.js';
+import { defaultRipgrepCandidates, resolveRipgrepCandidates } from '../ripgrep-executable.js';
 export function createFilesystemWorkerLaunchSpecProvider(input) {
-    let cached;
-    return () => (cached ??= resolveLaunchSpec(input));
+    const platform = input.platform ?? process.platform;
+    let base;
+    return async (operation) => {
+        const resolved = await (base ??= resolveLaunchBase(input, platform));
+        if (!resolved.ok)
+            return resolved;
+        const grep = operation.kind === 'grep'
+            ? await resolveWorkerRipgrep(input.rgCandidates ?? defaultRipgrepCandidates(input.hostEnv ?? process.env, platform), platform, input.inspectMacosExecutableDependencies ?? resolveMacosExecutableDependencies)
+            : undefined;
+        return { ok: true, spec: composeLaunchSpec(resolved.base, grep) };
+    };
 }
 export function buildFilesystemWorkerEnv(runtime, hostEnv = process.env, controlledTmpdir = '/tmp', platform = process.platform) {
     const env = { TMPDIR: controlledTmpdir, OPENSSL_CONF: '/dev/null' };
@@ -47,7 +58,7 @@ export function buildFilesystemWorkerEnv(runtime, hostEnv = process.env, control
         env.ELECTRON_RUN_AS_NODE = '1';
     return env;
 }
-async function resolveLaunchSpec(input) {
+async function resolveLaunchBase(input, platform) {
     const bundle = await resolveFilesystemWorkerBundle(input.resourceLocation);
     if (!bundle.ok) {
         return {
@@ -64,7 +75,6 @@ async function resolveLaunchSpec(input) {
             message: 'Filesystem worker runtime is unavailable.',
         };
     }
-    const platform = input.platform ?? process.platform;
     // A packaged Windows executable lives directly inside the product-owned app
     // directory. Granting its parent would widen a normal install from
     // `...\Programs\Maka` to every application under `...\Programs` (or from
@@ -81,7 +91,6 @@ async function resolveLaunchSpec(input) {
         };
     }
     const dependencyRoots = await resolveRuntimeDependencyRoots(program);
-    const grep = await resolveRipgrepExecutable(input.rgCandidates ?? defaultRipgrepCandidates(input.hostEnv ?? process.env, platform), platform, input.inspectMacosExecutableDependencies ?? resolveMacosExecutableDependencies);
     const electronFrameworks = input.runtime === 'electron' && platform === 'darwin'
         ? await resolveReadableRoot(resolve(dirname(program), '..', 'Frameworks'))
         : undefined;
@@ -92,52 +101,64 @@ async function resolveLaunchSpec(input) {
             message: 'Electron framework roots are unavailable.',
         };
     }
+    const environment = currentRipgrepEnvironment(input.hostEnv ?? process.env);
     return {
         ok: true,
-        spec: {
+        base: {
+            runtime: input.runtime,
+            platform,
             program,
-            // --preserve-symlinks-main skips the module loader's realpath of the
-            // bundle path. Inside the Windows AppContainer that realpath would
-            // lstat every ancestor directory (up to the volume root), which the
-            // sandbox grants deliberately do not allow.
-            //
-            // --no-stdio-init: Electron's run-as-node entry opens the NUL device to
-            // backfill missing standard handles before Node starts, and the
-            // AppContainer denies that device open, which aborts startup (FATAL
-            // node_main.cc "Unable to open nul device"). The broker always relays
-            // three valid standard handles into the child, so the backfill is
-            // unnecessary; the switch skips it and is consumed before Node's own
-            // option parsing.
-            args: [
-                ...(input.runtime === 'electron' && platform === 'win32' ? ['--no-stdio-init'] : []),
-                ...(platform === 'win32' ? ['--preserve-symlinks-main'] : []),
-                bundle.path,
-                ...(grep ? ['--grep-executable', grep.executable] : []),
-            ],
+            bundlePath: bundle.path,
+            runtimeRoot,
+            dependencyRoots,
+            ...(electronFrameworks ? { electronFrameworks } : {}),
             env: buildFilesystemWorkerEnv(input.runtime, input.hostEnv, input.tmpdir, platform),
-            runtimeReadableRoots: unique([
-                bundle.path,
-                runtimeRoot,
-                ...dependencyRoots,
-                ...(grep?.runtimeReadableRoots ?? []),
-            ]),
-            executableRoots: unique([
-                program,
-                runtimeRoot,
-                ...(electronFrameworks ? [electronFrameworks] : []),
-                ...dependencyRoots,
-                ...(grep ? [grep.executable, ...grep.executableRoots] : []),
-            ]),
+            ...(environment ? { environment } : {}),
         },
     };
 }
-async function resolveRipgrepExecutable(candidates, platform, inspectMacosExecutableDependencies) {
-    const inspected = new Set();
-    for (const candidate of candidates) {
-        const executable = await resolveExecutable(candidate);
-        if (!executable || inspected.has(executable))
-            continue;
-        inspected.add(executable);
+function composeLaunchSpec(base, grep) {
+    return {
+        program: base.program,
+        // --preserve-symlinks-main skips the module loader's realpath of the
+        // bundle path. Inside the Windows AppContainer that realpath would
+        // lstat every ancestor directory (up to the volume root), which the
+        // sandbox grants deliberately do not allow.
+        //
+        // --no-stdio-init: Electron's run-as-node entry opens the NUL device to
+        // backfill missing standard handles before Node starts, and the
+        // AppContainer denies that device open, which aborts startup (FATAL
+        // node_main.cc "Unable to open nul device"). The broker always relays
+        // three valid standard handles into the child, so the backfill is
+        // unnecessary; the switch skips it and is consumed before Node's own
+        // option parsing.
+        args: [
+            ...(base.runtime === 'electron' && base.platform === 'win32' ? ['--no-stdio-init'] : []),
+            ...(base.platform === 'win32' ? ['--preserve-symlinks-main'] : []),
+            base.bundlePath,
+            ...(base.environment
+                ? ['--ripgrep-environment', formatRipgrepEnvironmentArg(base.environment)]
+                : []),
+            ...(grep ? ['--grep-executable', grep.executable] : []),
+        ],
+        env: base.env,
+        runtimeReadableRoots: unique([
+            base.bundlePath,
+            base.runtimeRoot,
+            ...base.dependencyRoots,
+            ...(grep?.runtimeReadableRoots ?? []),
+        ]),
+        executableRoots: unique([
+            base.program,
+            base.runtimeRoot,
+            ...(base.electronFrameworks ? [base.electronFrameworks] : []),
+            ...base.dependencyRoots,
+            ...(grep ? [grep.executable, ...grep.executableRoots] : []),
+        ]),
+    };
+}
+async function resolveWorkerRipgrep(candidates, platform, inspectMacosExecutableDependencies) {
+    for await (const executable of resolveRipgrepCandidates(candidates)) {
         if (platform !== 'darwin') {
             return { executable, runtimeReadableRoots: [], executableRoots: [] };
         }
@@ -171,16 +192,6 @@ async function resolveReadableRoot(candidate) {
         return undefined;
     }
 }
-function defaultRipgrepCandidates(env, platform = process.platform) {
-    const executableName = platform === 'win32' ? 'rg.exe' : 'rg';
-    return [
-        ...(env.PATH ?? '')
-            .split(delimiter)
-            .filter(Boolean)
-            .map((directory) => join(directory, executableName)),
-        ...(platform === 'win32' ? [] : ['/opt/homebrew/bin/rg', '/usr/local/bin/rg', '/usr/bin/rg']),
-    ];
-}
 async function resolveRuntimeDependencyRoots(program) {
     const candidates = program.startsWith('/opt/homebrew/')
         ? ['/opt/homebrew/opt', '/opt/homebrew/Cellar']