maka-agent 0.2.0-dev.30.20260912 → 0.2.0-dev.31.20260913

package/node_modules/@maka/runtime/dist/conversation-copy.js

@@ -23,14 +23,14 @@ import { decodePersistedToolResultContent } from '@maka/core/tool-result-record-
 import { isEmittedAgentRunEventType } from '@maka/core/agent-run';
 import { decodeModelCallAttempt, MODEL_CALL_ATTEMPT_EVENT_TYPE, } from '@maka/core/model-call-attempt';
 import { TOOL_RECOVERY_DECISION_FACT_KIND } from '@maka/core/tool-recovery-fact';
-import { buildHistoryCompactCheckpoint, matchHistoryCompactCheckpointPrefix, validateHistoryCompactCheckpointShape, } from './history-compact-checkpoint.js';
+import { buildHistoryCompactCheckpoint, historyCompactSourceDigest, matchHistoryCompactCheckpointPrefix, validateHistoryCompactCheckpointShape, } from './history-compact-checkpoint.js';
 import { findCheckpointSummaryDefect } from './history-compact-summary-validation.js';
 import { isHistoryCompactContentEvent } from './history-compaction.js';
 import { classifyTerminalRuntimeLedger, commitTerminalRunWithRuntimeFact, } from './terminal-run-commit.js';
 import { buildToolOperationId } from './runtime-commit-sink.js';
 import { isContinuationStartRuntimeEvent } from './runtime-event-read-model.js';
 import { runtimeHandoffPause } from '@maka/core/runtime-handoff';
-import { buildToolResultArchiveResourceRef, parseToolResultArchiveResourceRef, } from './tool-result-archive-resource.js';
+import { buildToolResultArchiveResourceRef, parseToolResultArchiveResourceRef, parseToolResultEventAddress, } from './tool-result-archive-resource.js';
 import { deserializeToolResultArchive, isArchivedToolResultPlaceholder, buildLedgerArchivedToolResultPlaceholder, } from './tool-result-archive.js';
 import { rewriteDurableToolResultProjectionArtifactRefs } from './durable-tool-result-projection.js';
 import { buildModelProjectionTransition, durableToolResultProjectionDigest, decodeModelProjectionTransition, MODEL_PROJECTION_TRANSITION_EVENT_TYPE, } from '@maka/core/model-projection-transition';
@@ -38,6 +38,7 @@ import { baseToolResultProjection, decodeLedgerTransition, reduceEffectiveModelP
 import { archivedToolResultProjection } from './tool-result-archive-transition.js';
 import { serializeToolResultProjectionV1 } from './tool-result-archive-encoding.js';
 import { createHash } from 'node:crypto';
+import { readToolResultPage, readableToolResult, resolveReadInput, READ_PAGE_MAX_CHARS, } from './read-page.js';
 /** Walks every typed StorageRef site reached by conversation-copy rewriting. */
 function collectConversationCopyStorageRefs(input) {
     const refs = [];
@@ -354,6 +355,15 @@ export async function cloneConversationRuntimeLedger(input) {
             throw new Error('Cyclic copied archive reference');
         visiting.add(sourceId);
         const target = clonedEventBySourceId.get(sourceId);
+        if (target?.content?.kind === 'function_response' && target.content.name === 'Read') {
+            target.content.result = rewriteReadPage(target.content.result, references, clonedEventBySourceId);
+            const projection = target.content.modelProjection;
+            if (projection?.kind === 'json')
+                target.content.modelProjection = {
+                    ...projection,
+                    value: rewriteReadPage(projection.value, references, clonedEventBySourceId),
+                };
+        }
         if (target?.content?.kind === 'function_response' && target.content.name === 'ArchiveRead') {
             const resolveResult = (value) => rewriteArchiveReadResult(value, references, (ref) => {
                 const identity = parseToolResultArchiveResourceRef(ref);
@@ -377,8 +387,19 @@ export async function cloneConversationRuntimeLedger(input) {
     for (const sourceId of clonedEventBySourceId.keys())
         finishTarget(sourceId);
     for (const event of clonedEventBySourceId.values()) {
+        if (event.content?.kind === 'function_call' && event.content.name === 'Read') {
+            const args = event.content.args;
+            if (args && typeof args === 'object' && 'path' in args && typeof args.path === 'string')
+                event.content = {
+                    ...event.content,
+                    args: {
+                        ...args,
+                        ...rewriteReadInput(args, references, clonedEventBySourceId),
+                    },
+                };
+        }
         if (event.content?.kind === 'text')
-            event.content.text = rewriteLedgerArchiveText(event.content.text, references);
+            event.content.text = rewriteCopiedText(event.content.text, references, clonedEventBySourceId);
         if (event.content?.kind === 'function_call' && event.content.name === 'ArchiveRead') {
             const args = event.content.args;
             if (args && typeof args === 'object' && 'ref' in args && typeof args.ref === 'string') {
@@ -412,18 +433,19 @@ export async function cloneConversationRuntimeLedger(input) {
             terminalEvent,
         };
     });
-    const archiveReadCalls = new Set(flattenedPlans.flatMap((plan) => plan.events.flatMap((event) => event.content?.kind === 'function_response' && event.content.name === 'ArchiveRead'
+    const archiveReadCalls = new Set(flattenedPlans.flatMap((plan) => plan.events.flatMap((event) => event.content?.kind === 'function_response' &&
+        (event.content.name === 'ArchiveRead' || event.content.name === 'Read')
         ? [`${event.turnId}:${event.content.id}`]
         : [])));
     const copiedMessages = input.copiedMessages.map((message) => {
         const copied = rewriteConversationCopyMessage(message, references);
         if (copied.type === 'user' || copied.type === 'assistant')
-            return { ...copied, text: rewriteLedgerArchiveText(copied.text, references) };
+            return { ...copied, text: rewriteCopiedText(copied.text, references, clonedEventBySourceId) };
         if (copied.type === 'tool_result' &&
             archiveReadCalls.has(`${copied.turnId}:${copied.toolUseId}`)) {
             return {
                 ...copied,
-                content: rewriteArchiveReadResult(copied.content, references),
+                content: rewriteReadPage(rewriteArchiveReadResult(copied.content, references), references, clonedEventBySourceId),
             };
         }
         return copied;
@@ -479,8 +501,71 @@ export async function cloneConversationRuntimeLedger(input) {
 function rewriteLedgerArchiveText(text, references) {
     for (const [source, target] of references.ledgerArchives ?? [])
         text = text.split(source).join(target.resourceRef);
+    for (const [source, target] of references.runtimeEventIds)
+        text = text
+            .split(`maka://runtime/tool-results/${encodeURIComponent(source)}`)
+            .join(`maka://runtime/tool-results/${encodeURIComponent(target)}`);
     return text;
 }
+/** Text identifies generated addresses; the structured Read rewriter owns their semantics. */
+function rewriteCopiedText(text, references, clonedEvents) {
+    return rewriteLedgerArchiveText(text, references).replace(/maka:\/\/read\/[A-Za-z0-9_-]+\?at=\d+&sha=[a-f0-9]{32}(?![A-Za-z0-9_?&#=%/-])/g, (path) => rewriteReadInput({ path }, references, clonedEvents).path);
+}
+function rewriteReadInput(input, references, clonedEvents) {
+    let original;
+    try {
+        original = resolveReadInput(input).path;
+    }
+    catch {
+        return input;
+    }
+    const prefix = 'maka://runtime/tool-results/';
+    const eventId = parseToolResultEventAddress(original);
+    if (original.startsWith(prefix) && !eventId)
+        return input;
+    const path = eventId
+        ? `${prefix}${encodeURIComponent(references.runtimeEventIds.get(eventId) ?? eventId)}`
+        : rewriteLedgerArchiveText(references.mode === 'exact'
+            ? rewriteAttachmentResourceRefs(original, references.artifactIds)
+            : original, references);
+    if (!input.path.startsWith('maka://read/'))
+        return { ...input, path };
+    const url = new URL(input.path);
+    if (eventId && path !== original) {
+        const copied = clonedEvents.get(eventId);
+        const projection = copied && baseToolResultProjection(copied);
+        const digest = projection &&
+            createHash('sha256')
+                .update(readableToolResult(serializeToolResultProjectionV1(projection)))
+                .digest('hex')
+                .slice(0, 32);
+        if (digest !== url.searchParams.get('sha'))
+            return { path };
+    }
+    url.pathname = `/${Buffer.from(path).toString('base64url')}`;
+    return { ...input, path: url.toString() };
+}
+function rewriteReadPage(value, references, clonedEvents) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return value;
+    const page = value;
+    if (page.kind === 'json')
+        return { ...page, value: rewriteReadPage(page.value, references, clonedEvents) };
+    const next = page.next;
+    if (!next || typeof next !== 'object' || !('path' in next) || typeof next.path !== 'string')
+        return value;
+    const rewritten = rewriteReadInput(next, references, clonedEvents);
+    const reset = next.path.startsWith('maka://read/') && !rewritten.path.startsWith('maka://read/');
+    return {
+        ...page,
+        next: rewritten,
+        ...(reset
+            ? {
+                continuationReset: 'The copied resource changed. Use next to read it from the beginning.',
+            }
+            : {}),
+    };
+}
 /** Only ArchiveRead's defined envelope is rewritten, never its opaque content/items. */
 function rewriteArchiveReadResult(value, references, before) {
     if (!value || typeof value !== 'object' || Array.isArray(value))
@@ -679,6 +764,11 @@ function cloneAgentRunEvent(event, ids, references, sourceCompactableEvents, clo
         const match = matchHistoryCompactCheckpointPrefix(sourceCheckpoint, sourceCompactableEvents);
         if (match.reason)
             return null;
+        // Rebinding a digest must not make an already stale source summary valid.
+        const sourceEffective = reduceEffectiveModelProjections(match.coveredRuntimeEvents, [...clonedTransitions.keys()].map((record) => decodeModelProjectionTransition(record.data?.transition, record.sessionId))).events;
+        if (sourceCheckpoint.coverage.effectiveSourceDigest !==
+            historyCompactSourceDigest(sourceEffective))
+            return null;
         // Copy is an admission seam for the sectioned summary contract: a marked
         // checkpoint whose summary no longer satisfies the COMPLETE predicate —
         // re-runnable here on structure and truncation (the size floor needs the
@@ -704,7 +794,8 @@ function cloneAgentRunEvent(event, ids, references, sourceCompactableEvents, clo
         const checkpoint = buildHistoryCompactCheckpoint({
             sessionId: references.targetSessionId,
             coveredRuntimeEvents,
-            summary: rewriteLedgerArchiveText(sourceCheckpoint.summary, references),
+            effectiveCoveredRuntimeEvents: reduceEffectiveModelProjections(coveredRuntimeEvents, [...clonedTransitions.values()].filter((transition) => transition !== null)).events,
+            summary: rewriteCopiedText(sourceCheckpoint.summary, references, clonedRuntimeEvents),
             highWaterName: sourceCheckpoint.highWaterName,
             highWaterSeq: sourceCheckpoint.highWaterSeq,
             now: sourceCheckpoint.createdAt,
@@ -789,7 +880,11 @@ function cloneModelProjectionTransition(event, references, clonedRuntimeEvents,
                 }
                 : {}),
         });
-        references.ledgerArchives?.set(buildToolResultArchiveResourceRef(placeholder), rewritten);
+        if (rewritten.page) {
+            delete rewritten.page;
+            rewritten.page = readToolResultPage(serialized, { path: rewritten.resourceRef }, READ_PAGE_MAX_CHARS - JSON.stringify(rewritten).length - 32);
+        }
+        references.ledgerArchives?.set(placeholder.resourceRef ?? buildToolResultArchiveResourceRef(placeholder), rewritten);
     }
     else {
         rewritten = rewriteArchivedToolResult(placeholder, references);
@@ -803,7 +898,7 @@ function cloneModelProjectionTransition(event, references, clonedRuntimeEvents,
             toolName: source.target.toolName,
         },
         sourceProjection,
-        replacement: archivedToolResultProjection(rewritten),
+        replacement: archivedToolResultProjection(rewritten, source.replacement),
         // The applied chain is copied in fold order, so a predecessor is always
         // rebuilt before its successor. An unmapped one means the chain broke, and
         // rooting the successor instead would change what the fold decides.

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

@@ -27,6 +27,7 @@
 // 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 { lstat, realpath, stat } from 'node:fs/promises';
 import { isAbsolute } from 'node:path';
 import { ToolOutcomeUnknownError } from '@maka/core/events';
@@ -37,7 +38,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 +114,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 +269,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({
@@ -534,7 +538,7 @@ function createWorkspaceFilesystemExecutor(workspace) {
                         label: 'Grep',
                         scope,
                     });
-                    const { matches } = await workspace.grepFiles({
+                    const result = await workspace.grepFiles({
                         cwd,
                         pattern: operation.pattern,
                         path,
@@ -544,7 +548,7 @@ function createWorkspaceFilesystemExecutor(workspace) {
                         timeoutMs: operation.timeoutMs,
                         ...(abortSignal ? { abortSignal } : {}),
                     });
-                    return { kind: 'grep', matches };
+                    return { kind: 'grep', ...result };
                 }
             }
         },

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']