@myagentroam/node 0.9.95 → 0.9.97

package/dist/codex-app-server.js

@@ -9,22 +9,11 @@ import { createInterface } from 'node:readline';
 import { minimalRunnerEnvironment, platformCliInvocation, runRunnerProbe } from './operational.js';
 const REQUEST_TIMEOUT_MS = 15_000;
 /**
- * Maps the facts that the Node can actually establish to user-visible
- * controls.  In particular, seeing an external thread never implies that it
- * is safe to write to its active turn.
+ * Maps the facts that the Node can establish to the unified session controls.
+ * Native-session activation is validated atomically with the first message.
  */
 export function codexSessionControl(input) {
-    if (!input.available)
-        return { level: 'UNAVAILABLE', capabilities: [] };
-    if (input.sharedControl) {
-        return {
-            level: 'SHARED_CONTROL',
-            capabilities: ['history.read', 'events.live', 'turn.start', 'turn.steer', 'turn.interrupt']
-        };
-    }
-    if (input.nativeThreadId !== null && input.nativeControl === 'EXTERNAL') {
-        return { level: 'OBSERVE_ONLY', capabilities: ['history.read'] };
-    }
+    void [input.available, input.nativeThreadId, input.nativeControl];
     if (input.activeTurn) {
         return {
             level: 'MANAGED',
@@ -32,7 +21,7 @@ export function codexSessionControl(input) {
         };
     }
     return {
-        level: 'RESUMABLE',
+        level: 'MANAGED',
         capabilities: ['history.read', 'turn.start']
     };
 }

package/dist/connector.js

@@ -635,7 +635,6 @@ export class NodeConnector {
             runners: this.runners,
             capabilities: () => this.capabilities,
             hasManagedActiveRun: (session) => hasManagedActiveRun(this.runtime, session),
-            externalActivity: (sessionId) => this.sessionState.externalActivity.get(sessionId),
             projectionForNative: (session) => this.nativeSessionProjectionService.projectionForNative(session)
         });
         this.nativeSessionProjectionService = new NativeSessionProjectionService({
@@ -851,28 +850,12 @@ export class NodeConnector {
             configuration: (session) => this.nativeSessionProjectionService.resumedConfiguration(session),
             workspacePath: (workspaceId) => this.database?.getWorkspace(workspaceId)?.path,
             rememberNative: (nativeSessionId, sessionId) => this.managedRunnerSessions.remember(nativeSessionId, sessionId),
-            stage: (session) => {
-                const configuration = this.nativeSessionProjectionService.resumedConfiguration(session);
-                return this.runtime.createAgentSession({
-                    workspaceId: session.workspaceId,
-                    runner: session.runner,
-                    externalSessionId: session.externalSessionId ?? session.id,
-                    nativeControl: 'EXTERNAL',
-                    cwd: session.cwd,
-                    model: configuration.model,
-                    effort: configuration.effort,
-                    access: configuration.access,
-                    ...(session.runnerTitle === null ? {} : { title: session.runnerTitle }),
-                    ...(session.customTitle === null ? {} : { customTitle: session.customTitle })
-                });
-            },
             resolve: (sessionId) => this.nativeSessionProjectionService.resolve(sessionId)
         });
         this.sessionCommandService = new SessionCommandService({
             runtime: this.runtime,
             runners: this.runners,
             projection: this.nativeSessionProjectionService,
-            resume: this.externalSessionResumeService,
             profiles: () => this.runnerService.profiles(),
             present: (session) => this.sessionPresentationService.present(session),
             resumeQueueAfterCommandRun: (sessionId) => this.workspaceQueueWorkbenchService.resumeAfterCommandRun(sessionId),
@@ -1018,7 +1001,6 @@ export class NodeConnector {
             runtime: this.runtime,
             runners: this.runners,
             projection: this.nativeSessionProjectionService,
-            resume: this.externalSessionResumeService,
             cachedNative: () => [...this.sessionState.directNative.values()],
             cachedWorkspace: (workspaceId) => this.workspaceCoordinator.cachedSessions(workspaceId),
             discoverWorkspace: (workspaceId) => this.nativeSessionProjectionService.discoverWorkspace(workspaceId),

package/dist/runner/claude/managed-run-controller.js

@@ -115,7 +115,7 @@ export class ClaudeManagedRunController {
             return;
         if (typeof payload.externalSessionId === 'string' &&
             !this.runner.execution.managedNativeIds.has(payload.externalSessionId)) {
-            this.host.emit(runId, 'run.rejected', { code: 'EXTERNAL_SESSION_OBSERVE_ONLY' }, 'FAILED');
+            this.host.emit(runId, 'run.rejected', { code: 'SESSION_ACTIVATION_REQUIRED' }, 'FAILED');
             return;
         }
         this.host.active.add(runId);

package/dist/runner/claude-code-runner.js

@@ -147,62 +147,28 @@ export class ClaudeCodeRunner extends AbstractRunner {
             : this.client.forkSession(session.externalSessionId, session.cwd, boundary, title);
     }
     presentSession(session, capabilities, context) {
-        if (capabilities.claudeCode.available && session.nativeControl === 'MAR_MANAGED') {
-            const runtimeCapabilities = [
-                'history.read',
-                'events.live',
-                'turn.start',
-                'turn.queue',
-                'turn.interrupt',
-                'run.cancel',
-                'approval.respond',
-                'session.rename',
-                'session.remove',
-                'session.pin',
-                ...(session.externalSessionId === null ? [] : ['session.rewind'])
-            ];
-            return {
-                activity: context.managedActive ? 'MANAGED_ACTIVE' : 'IDLE',
-                control: {
-                    level: 'MANAGED',
-                    capabilities: ['history.read', 'events.live', 'turn.start', 'turn.interrupt']
-                },
-                commandStates: context.commandStates,
-                runtime: { level: 'MANAGED', capabilities: runtimeCapabilities, reasonCode: null }
-            };
-        }
-        if (capabilities.claudeCode.available && session.externalSessionId !== null) {
-            const runtimeCapabilities = [
-                'history.read',
-                'turn.start',
-                'session.rename',
-                'session.remove',
-                'session.pin',
-                'session.rewind'
-            ];
-            return {
-                activity: 'IDLE',
-                control: { level: 'RESUMABLE', capabilities: ['history.read', 'turn.start'] },
-                commandStates: context.commandStates,
-                runtime: { level: 'RESUMABLE', capabilities: runtimeCapabilities, reasonCode: null }
-            };
-        }
+        void capabilities;
         const runtimeCapabilities = [
             'history.read',
             'events.live',
+            'turn.start',
+            'turn.queue',
+            'turn.interrupt',
+            'run.cancel',
+            'approval.respond',
             'session.rename',
             'session.remove',
-            'session.pin'
+            'session.pin',
+            ...(session.externalSessionId === null ? [] : ['session.rewind'])
         ];
         return {
-            activity: 'UNAVAILABLE',
-            control: { level: 'OBSERVE_ONLY', capabilities: ['history.read', 'events.live'] },
+            activity: context.managedActive ? 'MANAGED_ACTIVE' : 'IDLE',
+            control: {
+                level: 'MANAGED',
+                capabilities: ['history.read', 'events.live', 'turn.start', 'turn.interrupt']
+            },
             commandStates: context.commandStates,
-            runtime: {
-                level: 'OBSERVE_ONLY',
-                capabilities: runtimeCapabilities,
-                reasonCode: 'EXTERNAL_SESSION_OBSERVE_ONLY'
-            }
+            runtime: { level: 'MANAGED', capabilities: runtimeCapabilities, reasonCode: null }
         };
     }
     prepareMessageInput(input, collaborationMode) {

package/dist/runner/codex/managed-run-controller.js

@@ -357,7 +357,7 @@ export class CodexManagedRunController {
         }
         if (typeof payload.externalSessionId === 'string' &&
             (session === undefined || session.nativeControl !== 'MAR_MANAGED')) {
-            this.host.emit(runId, 'run.rejected', { code: 'EXTERNAL_THREAD_OBSERVE_ONLY' }, 'FAILED');
+            this.host.emit(runId, 'run.rejected', { code: 'SESSION_ACTIVATION_REQUIRED' }, 'FAILED');
             return;
         }
         try {

package/dist/runner/codex-runner.js

@@ -309,10 +309,7 @@ export class CodexRunner extends AbstractRunner {
             return { activity: 'IDLE', session: context.create(external) };
         }
         catch {
-            return {
-                activity: 'UNAVAILABLE',
-                failureCode: 'RUNNER_RESUME_FAILED'
-            };
+            return { failureCode: 'RUNNER_RESUME_FAILED' };
         }
     }
     async discoverSessions(context, workspace) {
@@ -391,13 +388,7 @@ export class CodexRunner extends AbstractRunner {
             nativeControl: session.nativeControl,
             activeTurn
         });
-        const activity = !capabilities.codex.available
-            ? 'UNAVAILABLE'
-            : context.managedActive
-                ? 'MANAGED_ACTIVE'
-                : session.nativeControl === 'EXTERNAL'
-                    ? (context.externalActivity ?? 'IDLE')
-                    : 'IDLE';
+        const activity = context.managedActive ? 'MANAGED_ACTIVE' : 'IDLE';
         return {
             control,
             activity,
@@ -406,13 +397,15 @@ export class CodexRunner extends AbstractRunner {
                 level: control.level,
                 capabilities: [
                     ...control.capabilities,
-                    ...(control.level === 'MANAGED' ? ['turn.queue', 'run.cancel', 'approval.respond'] : []),
+                    'turn.queue',
+                    'run.cancel',
+                    'approval.respond',
                     'session.rename',
                     'session.remove',
                     'session.pin',
                     ...(session.externalSessionId === null ? [] : ['session.rewind'])
                 ],
-                reasonCode: control.level === 'UNAVAILABLE' ? 'RUNNER_UNAVAILABLE' : null
+                reasonCode: null
             }
         };
     }

package/dist/runner/mar-agent-runner.js

@@ -170,14 +170,7 @@ export class MarAgentRunner extends AbstractRunner {
         };
     }
     presentSession(session, capabilities, context) {
-        if (!this.available(capabilities))
-            return {
-                activity: 'UNAVAILABLE',
-                control: { level: 'UNAVAILABLE', capabilities: [] },
-                runtime: { level: 'UNAVAILABLE', capabilities: [], reasonCode: 'RUNNER_UNAVAILABLE' },
-                commandStates: context.commandStates
-            };
-        const managed = session.nativeControl === 'MAR_MANAGED';
+        void capabilities;
         const activity = context.managedActive ? 'MANAGED_ACTIVE' : 'IDLE';
         const runtimeCapabilities = [
             'history.read',
@@ -195,11 +188,11 @@ export class MarAgentRunner extends AbstractRunner {
         return {
             activity,
             control: {
-                level: managed ? 'MANAGED' : 'RESUMABLE',
+                level: 'MANAGED',
                 capabilities: ['history.read', 'events.live', 'turn.start', 'turn.interrupt']
             },
             runtime: {
-                level: managed ? 'MANAGED' : 'RESUMABLE',
+                level: 'MANAGED',
                 capabilities: runtimeCapabilities,
                 reasonCode: null
             },

package/dist/runner/opencode-runner.js

@@ -206,7 +206,7 @@ export class OpenCodeRunner extends AbstractRunner {
         const projection = context.projectionFor(external);
         const session = projection === undefined ? context.create(external) : context.promote(projection.id);
         return session === undefined
-            ? { activity: 'UNAVAILABLE', failureCode: 'RUNNER_RESUME_FAILED' }
+            ? { failureCode: 'RUNNER_RESUME_FAILED' }
             : { activity: 'IDLE', session: context.ensureConfiguration(session) };
     }
     async readOfficialConversation(session, input, managedTurn) {
@@ -227,18 +227,8 @@ export class OpenCodeRunner extends AbstractRunner {
         return this.managedTurns.get(nativeTurnId);
     }
     presentSession(session, capabilities, context) {
-        const available = capabilities.openCode?.available === true;
-        const managed = session.nativeControl === 'MAR_MANAGED';
-        const activity = context.managedActive
-            ? 'MANAGED_ACTIVE'
-            : (context.externalActivity ?? (available ? 'IDLE' : 'UNAVAILABLE'));
-        if (!available)
-            return {
-                activity: 'UNAVAILABLE',
-                control: { level: 'UNAVAILABLE', capabilities: [] },
-                runtime: { level: 'UNAVAILABLE', capabilities: [], reasonCode: 'RUNNER_UNAVAILABLE' },
-                commandStates: context.commandStates
-            };
+        void capabilities;
+        const activity = context.managedActive ? 'MANAGED_ACTIVE' : 'IDLE';
         const runtimeCapabilities = [
             'history.read',
             'events.live',
@@ -256,15 +246,13 @@ export class OpenCodeRunner extends AbstractRunner {
         return {
             activity,
             control: {
-                level: managed ? 'MANAGED' : activity === 'IDLE' ? 'RESUMABLE' : 'OBSERVE_ONLY',
-                capabilities: managed || activity === 'IDLE'
-                    ? ['history.read', 'events.live', 'turn.start', 'turn.interrupt']
-                    : ['history.read', 'events.live']
+                level: 'MANAGED',
+                capabilities: ['history.read', 'events.live', 'turn.start', 'turn.interrupt']
             },
             runtime: {
-                level: managed ? 'MANAGED' : activity === 'IDLE' ? 'RESUMABLE' : 'OBSERVE_ONLY',
+                level: 'MANAGED',
                 capabilities: runtimeCapabilities,
-                reasonCode: activity === 'EXTERNAL_ACTIVE' ? 'EXTERNAL_SESSION_OBSERVE_ONLY' : null
+                reasonCode: null
             },
             commandStates: context.commandStates
         };

package/dist/service/conversation-history-service.js

@@ -317,7 +317,7 @@ export class ConversationHistoryService {
     async refreshExternalActivity(session) {
         const runner = this.options.runners.require(session.runner);
         if (!runner.available(this.options.capabilities())) {
-            this.options.setExternalActivity(session.id, 'UNAVAILABLE');
+            this.options.setExternalActivity(session.id, 'IDLE');
             return;
         }
         const activity = await runner.readExternalActivity(session);

package/dist/service/external-session-resume-service.js

@@ -31,6 +31,7 @@ export class ExternalSessionResumeService {
             return this.options.ensureConfiguration(prior);
         const runner = this.options.runners.product(external.runner);
         if (runner === undefined) {
+            this.options.state.externalActivity.set(external.id, 'IDLE');
             this.setFailure(external.id, 'RUNNER_UNAVAILABLE');
             return undefined;
         }
@@ -78,6 +79,8 @@ export class ExternalSessionResumeService {
         }
         if (result.activity !== undefined)
             this.options.state.externalActivity.set(external.id, result.activity);
+        else if (result.failureCode === 'RUNNER_UNAVAILABLE')
+            this.options.state.externalActivity.set(external.id, 'IDLE');
         if (result.session !== undefined) {
             this.options.state.resumedByDirectId.set(external.id, result.session.id);
             return result.session;
@@ -102,32 +105,12 @@ export class ExternalSessionResumeService {
         const resumed = await this.resume(current);
         if (resumed !== undefined)
             return resumed;
-        if (this.options.state.externalActivity.get(current.id) === 'EXTERNAL_ACTIVE')
+        if (this.options.state.externalActivity.get(current.id) === 'BUSY')
             throw new Error('EXTERNAL_SESSION_ACTIVE');
         throw new Error(this.options.state.messageResumeFailures.get(current.id) ?? this.failure(current.id).code);
     }
     async acceptForMessage(sessionId) {
-        const resumedId = this.options.state.resumedByDirectId.get(sessionId);
-        const current = this.options.runtime.getAgentSession(resumedId ?? sessionId) ??
-            (await this.options.resolve(sessionId));
-        if (current === undefined)
-            throw new Error('SESSION_NOT_FOUND');
-        if (current.nativeControl !== 'EXTERNAL')
-            return { session: current, ready: Promise.resolve(current), deferred: false };
-        const staged = this.options.projectionFor(current) ?? this.options.stage(current);
-        const ready = this.resume(current).then((session) => {
-            if (session !== undefined)
-                return session;
-            if (this.options.state.externalActivity.get(current.id) === 'EXTERNAL_ACTIVE')
-                throw new Error('EXTERNAL_SESSION_ACTIVE');
-            throw new Error(this.options.state.messageResumeFailures.get(current.id) ?? this.failure(current.id).code);
-        });
-        return { session: staged, ready, deferred: true };
-    }
-    delivery(session) {
-        return session.nativeControl === 'EXTERNAL' && session.externalSessionId !== null
-            ? 'RESUMABLE'
-            : 'REJECTED';
+        return { session: await this.resolveForMessage(sessionId) };
     }
     clearFailure(sessionId) {
         const timer = this.options.state.failureTimers.get(sessionId);

package/dist/service/node-control-message-service.js

@@ -68,7 +68,7 @@ export class NodeControlMessageService {
             this.cancelRun(envelope);
             return;
         }
-        if (envelope.type === 'session.resume' || envelope.type === 'lease.reconcile') {
+        if (envelope.type === 'lease.reconcile') {
             this.options.send('ack', { type: envelope.type }, envelope.id);
             return;
         }

package/dist/service/node-upgrade-coordinator.js

@@ -62,7 +62,6 @@ export class NodeUpgradeCoordinator {
     blocks(operation) {
         return (this.pending() &&
             (operation === 'session.start' ||
-                operation === 'session.resume' ||
                 operation === 'session.message' ||
                 operation === 'session.command.execute' ||
                 operation === 'runner.command.execute' ||

package/dist/service/session-catalog-service.js

@@ -11,7 +11,6 @@ export class SessionCatalogService {
     operations() {
         return {
             'session.list': (data) => this.list(record(data)),
-            'session.resume': (data) => this.resume(record(data)),
             'session.remove': (data) => this.enqueueMutation(() => this.remove(record(data))),
             'workspace.sessions.cleanup': (data) => this.enqueueMutation(() => this.cleanupWorkspaceSessions(record(data))),
             'session.rewind': (data) => this.enqueueMutation(() => this.rewind(record(data))),
@@ -100,30 +99,6 @@ export class SessionCatalogService {
             }));
         }
     }
-    async resume(input) {
-        if (typeof input.sessionId !== 'string')
-            throw new Error('SESSION_INVALID');
-        const value = this.options.runtime.getAgentSession(input.sessionId) ??
-            (await this.options.projection.resolve(input.sessionId));
-        if (value === undefined)
-            throw new Error('SESSION_NOT_FOUND');
-        if (value.nativeControl !== 'EXTERNAL')
-            return {
-                session: this.options.present(value),
-                delivery: this.options.resume.delivery(value)
-            };
-        const resumed = await this.options.resume.resume(value);
-        const failure = resumed === undefined ? this.options.resume.failure(value.id) : undefined;
-        return {
-            session: this.options.present(resumed ?? value),
-            delivery: resumed === undefined ? 'REJECTED' : 'RESUMABLE',
-            ...(resumed === undefined
-                ? {
-                    reasonCode: failure?.code ?? 'SESSION_RESUME_REJECTED'
-                }
-                : {})
-        };
-    }
     enqueueMutation(operation) {
         const result = this.rewindQueue.then(operation);
         this.rewindQueue = result.then(() => undefined, () => undefined);
@@ -263,7 +238,7 @@ export class SessionCatalogService {
                 this.options.runtime
                     .listRunsForSession(session.id)
                     .some((run) => !isTerminalRunStatus(run.status)) ||
-                this.options.externalActivity(session.id) === 'EXTERNAL_ACTIVE') {
+                this.options.externalActivity(session.id) === 'BUSY') {
                 skipped += 1;
                 continue;
             }
@@ -317,7 +292,7 @@ export class SessionCatalogService {
                 throw new Error('SESSION_ACTIVE');
             if (session.nativeControl === 'EXTERNAL') {
                 await this.options.refreshActivity(session);
-                if (this.options.externalActivity(session.id) === 'EXTERNAL_ACTIVE')
+                if (this.options.externalActivity(session.id) === 'BUSY')
                     throw new Error('SESSION_ACTIVE');
             }
             if (requireCleanupSafety) {

package/dist/service/session-command-service.js

@@ -39,9 +39,9 @@ export class SessionCommandService {
             (await this.options.projection.resolveCurrent(input.sessionId));
         if (resolved === undefined)
             throw new Error('SESSION_NOT_FOUND');
-        const session = resolved.nativeControl === 'EXTERNAL' ? await this.options.resume.resume(resolved) : resolved;
-        if (session === undefined)
-            throw new Error('RUNNER_COMMAND_UNAVAILABLE');
+        if (resolved.nativeControl === 'EXTERNAL')
+            throw new Error('SESSION_ACTIVATION_REQUIRED');
+        const session = resolved;
         const command = this.options
             .profiles()
             .find((profile) => profile.runner === session.runner)

package/dist/service/session-message-service.js

@@ -88,7 +88,7 @@ export class SessionMessageService {
         const publicContent = missionMessage?.activated === true ? 'Mission Start' : content;
         const intent = missionMessage === undefined ? requestedIntent : 'REPLACE_CURRENT';
         const operation = (async () => {
-            const acceptedSession = accepted.deferred ? accepted.session : await accepted.ready;
+            const acceptedSession = accepted.session;
             const session = this.options.runtime.getAgentSession(acceptedSession.id) ?? acceptedSession;
             const runId = randomUUID();
             const queueBeforeCreate = this.options.runtime.sessionQueue(session.id);
@@ -108,16 +108,12 @@ export class SessionMessageService {
             const sessionForPresentation = input.__mission === true
                 ? session
                 : this.options.runtime.setTemporaryTitleIfMissing(session.id, sessionTitleFromFirstMessage(content));
-            const deferPreparation = accepted.deferred && attachmentIds.length === 0 && inlineAttachments.length === 0;
             this.options.emitSession(sessionForPresentation);
             if (created.queueItem === undefined)
                 this.options.coordinator.publishCurrentTurn(created.run.id);
             const prepare = async () => {
                 try {
-                    const readySession = await accepted.ready;
-                    const currentSession = this.options.runtime.getAgentSession(readySession.id) ?? readySession;
-                    if (deferPreparation)
-                        this.options.emitSession(currentSession);
+                    const currentSession = this.options.runtime.getAgentSession(session.id) ?? session;
                     const uploaded = await this.options.uploads.resolve(session.workspaceId, attachmentIds);
                     const attachments = attachmentIds.length === 0
                         ? inlineAttachments
@@ -190,15 +186,7 @@ export class SessionMessageService {
                     throw error;
                 }
             };
-            if (deferPreparation)
-                void prepare().catch(() => undefined);
-            const delivery = deferPreparation
-                ? created.queueItem === undefined
-                    ? 'STARTED'
-                    : intent === 'REPLACE_CURRENT'
-                        ? 'RESTARTING'
-                        : 'QUEUED'
-                : await prepare();
+            const delivery = await prepare();
             return {
                 session: this.options.present(sessionForPresentation),
                 run: created.run,

package/dist/service/session-presentation-service.js

@@ -14,7 +14,6 @@ export class SessionPresentationService {
             .require(session.runner)
             .presentSession(session, this.options.capabilities(), {
             managedActive: this.options.hasManagedActiveRun(session),
-            externalActivity: this.options.externalActivity(session.id),
             commandStates: this.options.commands.list(session.id)
         });
         return {

package/dist/service/workspace-code-navigation-service.js

@@ -88,6 +88,7 @@ const buildWaiters = [];
 export class WorkspaceCodeNavigationService {
     options;
     builds = new Map();
+    preparations = new Map();
     candidateRefreshes = new Map();
     locations = new Map();
     failures = new Map();
@@ -96,6 +97,49 @@ export class WorkspaceCodeNavigationService {
     constructor(options) {
         this.options = options;
     }
+    async prepare(workspace, input) {
+        if (typeof input.path !== 'string' || input.path.length === 0 || input.path.length > 4096)
+            throw new Error('SYMBOL_DEFINITION_INVALID');
+        if (!isNavigablePath(input.path))
+            return { state: 'READY' };
+        if (!(await this.available()))
+            return { state: 'UNAVAILABLE' };
+        const location = await this.indexLocation(workspace);
+        this.locations.set(workspace.id, location);
+        this.forgotten.delete(location.directory);
+        const manifest = await readManifest(location.manifest);
+        const tags = manifest === undefined
+            ? undefined
+            : await tagsPath(location, manifest).catch(() => undefined);
+        const reusable = manifest !== undefined &&
+            tags !== undefined &&
+            (await tagsAvailable(tags)) &&
+            manifest.sourceFiles !== undefined;
+        const current = reusable &&
+            manifest.schemaVersion === INDEX_SCHEMA_VERSION &&
+            manifest.optionsVersion === INDEX_OPTIONS_VERSION &&
+            manifest.ctagsVersion === BUNDLED_CTAGS_VERSION;
+        const cachedCandidates = this.options.files.index(workspace).peekContentCandidates();
+        const forceRefreshGeneration = this.forceFreshCandidates.get(workspace.id);
+        if (reusable) {
+            if (!current || cachedCandidates === undefined || forceRefreshGeneration !== undefined)
+                this.refreshCandidatesInBackground(workspace, location, manifest, {
+                    requireFresh: forceRefreshGeneration !== undefined,
+                    mustBuild: !current || forceRefreshGeneration !== undefined,
+                    forceRefreshGeneration
+                });
+            return { state: current ? 'READY' : 'STALE' };
+        }
+        const failure = this.failures.get(location.directory);
+        if (failure !== undefined &&
+            !this.builds.has(location.directory) &&
+            !this.preparations.has(location.directory)) {
+            this.failures.delete(location.directory);
+            return { state: 'FAILED', failureCode: failure };
+        }
+        this.startInitialBuild(workspace, location);
+        return { state: 'BUILDING' };
+    }
     async definition(workspace, input) {
         const path = input.path;
         const symbol = input.symbol;
@@ -276,15 +320,32 @@ export class WorkspaceCodeNavigationService {
         };
     }
     startBuild(input, location, previous) {
-        void this.ensureBuild(input, location, previous).catch((error) => {
-            const failure = buildFailure(error);
-            this.failures.set(location.directory, failure);
-            nodeLog('workspace.code_navigation.index.failed', {
-                nodeId: this.options.nodeId(),
-                failureCode: failure,
-                sourceFiles: input.entries.length,
-                candidateScanMs: input.candidateScanMs
-            });
+        void this.ensureBuild(input, location, previous).catch((error) => this.recordBuildFailure(location, error, input));
+    }
+    startInitialBuild(workspace, location) {
+        if (this.builds.has(location.directory) || this.preparations.has(location.directory))
+            return;
+        const preparation = this.indexInput(workspace, true)
+            .then((input) => {
+            if (this.forgotten.has(location.directory))
+                return;
+            return this.ensureBuild(input, location);
+        })
+            .catch((error) => this.recordBuildFailure(location, error))
+            .finally(() => {
+            if (this.preparations.get(location.directory) === preparation)
+                this.preparations.delete(location.directory);
+        });
+        this.preparations.set(location.directory, preparation);
+    }
+    recordBuildFailure(location, error, input) {
+        const failure = buildFailure(error);
+        this.failures.set(location.directory, failure);
+        nodeLog('workspace.code_navigation.index.failed', {
+            nodeId: this.options.nodeId(),
+            failureCode: failure,
+            sourceFiles: input?.entries.length ?? 0,
+            candidateScanMs: input?.candidateScanMs ?? 0
         });
     }
     refreshCandidatesInBackground(workspace, location, manifest, options = {

package/dist/service/workspace-content-search-service.js

@@ -53,29 +53,38 @@ export class WorkspaceContentSearchService {
     search(workspace, input) {
         if (typeof input.query !== 'string' || input.query.length < 1 || input.query.length > 256)
             throw new Error('FILE_CONTENT_SEARCH_INVALID');
-        const key = `${workspace.id}\0${input.query.toLocaleLowerCase()}`;
+        if (input.regex !== undefined && typeof input.regex !== 'boolean')
+            throw new Error('FILE_CONTENT_SEARCH_INVALID');
+        const search = { query: input.query, regex: input.regex === true };
+        const queryKey = search.regex ? search.query : search.query.toLocaleLowerCase();
+        const key = `${workspace.id}\0${search.regex}\0${queryKey}`;
         const existing = this.pending.get(key);
         if (existing !== undefined)
             return existing;
-        const task = this.perform(workspace, input.query).finally(() => this.pending.delete(key));
+        const task = this.perform(workspace, search).finally(() => this.pending.delete(key));
         this.pending.set(key, task);
         return task;
     }
-    async perform(workspace, query) {
+    async perform(workspace, search) {
         const deadline = Date.now() + TIMEOUT_MS;
         const release = await acquireSearch(deadline);
         try {
+            if (search.regex && this.ripgrep === null)
+                throw new Error('RIPGREP_RESOURCE_UNAVAILABLE');
             const prepared = await this.candidates(workspace, deadline);
-            if (prepared.files.length === 0)
+            if (prepared.files.length === 0) {
+                if (search.regex)
+                    await this.validateNativeRegex(workspace.path, search, deadline);
                 return {
                     matches: [],
                     engine: 'NODE',
                     truncated: prepared.truncated || Date.now() >= deadline,
                     skippedFiles: prepared.skippedFiles
                 };
+            }
             if (this.ripgrep !== null) {
                 try {
-                    const matches = await this.nativeSearch('RIPGREP', workspace.path, prepared.files, query, deadline);
+                    const matches = await this.nativeSearch('RIPGREP', workspace.path, prepared.files, search, deadline);
                     return {
                         matches: matches.slice(0, RESULT_LIMIT),
                         engine: 'RIPGREP',
@@ -83,11 +92,13 @@ export class WorkspaceContentSearchService {
                         skippedFiles: prepared.skippedFiles
                     };
                 }
-                catch {
+                catch (error) {
+                    if (search.regex)
+                        throw error;
                     // Missing, incompatible or failed bundled resources safely fall through.
                 }
             }
-            const fallback = await nodeSearch(prepared.files, query, deadline);
+            const fallback = await nodeSearch(prepared.files, search.query, deadline);
             return {
                 matches: fallback.matches.slice(0, RESULT_LIMIT),
                 engine: 'NODE',
@@ -99,6 +110,14 @@ export class WorkspaceContentSearchService {
             release();
         }
     }
+    async validateNativeRegex(root, search, deadline) {
+        const command = commandFor('RIPGREP', [], search, this.ripgrep ?? undefined);
+        const result = await runCommand(command.file, [...command.args, '-'], root, deadline);
+        if (result.code === 2)
+            throw new Error('FILE_CONTENT_SEARCH_INVALID');
+        if (!command.validCodes.includes(result.code))
+            throw new Error('CONTENT_SEARCH_COMMAND_FAILED');
+    }
     async candidates(workspace, deadline) {
         const root = await realpath(workspace.path);
         let candidates;
@@ -139,21 +158,24 @@ export class WorkspaceContentSearchService {
         }
         return { files, skippedFiles, truncated };
     }
-    async nativeSearch(engine, root, files, query, deadline) {
+    async nativeSearch(engine, root, files, search, deadline) {
         const matches = [];
         const argumentBatchBytes = this.platform === 'win32' ? WINDOWS_ARGUMENT_BATCH_BYTES : POSIX_ARGUMENT_BATCH_BYTES;
         for (const batch of batches(files, argumentBatchBytes)) {
             if (Date.now() >= deadline || matches.length > RESULT_LIMIT)
                 break;
-            const command = commandFor(engine, batch, query, this.ripgrep ?? undefined);
+            const command = commandFor(engine, batch, search, this.ripgrep ?? undefined);
             const result = await runCommand(command.file, command.args, root, deadline, engine === 'RIPGREP');
-            if (!command.validCodes.includes(result.code))
+            if (!command.validCodes.includes(result.code)) {
+                if (search.regex && result.code === 2)
+                    throw new Error('FILE_CONTENT_SEARCH_INVALID');
                 throw new Error('CONTENT_SEARCH_COMMAND_FAILED');
+            }
             const paths = new Map(batch.flatMap((file) => [
                 [normalizeResultPath(file.path, this.platform), file.path],
                 [normalizeResultPath(file.absolutePath, this.platform), file.path]
             ]));
-            matches.push(...parseOutput(engine, result.stdout, query).map((match) => ({
+            matches.push(...parseOutput(engine, result.stdout, search).map((match) => ({
                 ...match,
                 path: paths.get(normalizeResultPath(match.path, this.platform)) ??
                     (() => {
@@ -213,7 +235,7 @@ function batches(files, maximumBytes) {
         result.push(current);
     return result;
 }
-function commandFor(engine, files, query, ripgrep) {
+function commandFor(engine, files, search, ripgrep) {
     const paths = files.map((file) => file.path);
     if (engine === 'RIPGREP')
         return {
@@ -224,12 +246,12 @@ function commandFor(engine, files, query, ripgrep) {
             args: [
                 '--json',
                 '--no-config',
-                '--fixed-strings',
                 '--ignore-case',
                 '--max-count',
                 String(PER_FILE_LIMIT),
+                ...(search.regex ? [] : ['--fixed-strings']),
                 '--',
-                query,
+                search.query,
                 ...paths
             ],
             validCodes: [0, 1]
@@ -301,14 +323,14 @@ async function runCommand(file, args, cwd, deadline, stopAfterResultLimit = fals
         });
     });
 }
-function parseOutput(engine, output, query) {
+function parseOutput(engine, output, search) {
     if (engine === 'RIPGREP')
-        return parseRipgrep(output, query);
+        return parseRipgrep(output, search);
     if (engine === 'GREP')
-        return parseGrep(output, query);
-    return parsePowerShell(output, query);
+        return parseGrep(output, search);
+    return parsePowerShell(output, search);
 }
-function parseRipgrep(output, query) {
+function parseRipgrep(output, search) {
     return output
         .toString('utf8')
         .split('\n')
@@ -320,7 +342,9 @@ function parseRipgrep(output, query) {
             return [];
         const data = value.data;
         const preview = String(data?.lines?.text).replace(/[\r\n]+$/u, '');
-        const column = lowerIndex(preview, query);
+        const column = search.regex
+            ? regexRipgrepIndex(preview, data?.submatches)
+            : lowerIndex(preview, search.query);
         if (typeof data?.path?.text !== 'string' || !Number.isInteger(data.line_number) || column < 0)
             throw new Error('CONTENT_SEARCH_OUTPUT_INVALID');
         return [
@@ -333,7 +357,7 @@ function parseRipgrep(output, query) {
         ];
     });
 }
-function parseGrep(output, query) {
+function parseGrep(output, search) {
     const matches = [];
     let offset = 0;
     while (offset < output.length) {
@@ -345,7 +369,7 @@ function parseGrep(output, query) {
         const record = output.subarray(separator + 1, end).toString('utf8');
         const colon = record.indexOf(':');
         const preview = record.slice(colon + 1).replace(/\r$/u, '');
-        const column = lowerIndex(preview, query);
+        const column = lowerIndex(preview, search.query);
         if (colon < 1 || column < 0)
             throw new Error('CONTENT_SEARCH_OUTPUT_INVALID');
         matches.push({
@@ -358,7 +382,7 @@ function parseGrep(output, query) {
     }
     return matches;
 }
-function parsePowerShell(output, query) {
+function parsePowerShell(output, search) {
     return output
         .toString('utf8')
         .split(/\r?\n/u)
@@ -370,7 +394,7 @@ function parsePowerShell(output, query) {
             !Number.isInteger(match.line) ||
             typeof match.preview !== 'string')
             throw new Error('CONTENT_SEARCH_OUTPUT_INVALID');
-        const column = lowerIndex(match.preview, query);
+        const column = lowerIndex(match.preview, search.query);
         if (column < 0)
             throw new Error('CONTENT_SEARCH_OUTPUT_INVALID');
         return [
@@ -445,6 +469,12 @@ async function nodeSearch(files, query, deadline) {
 function lowerIndex(source, query) {
     return source.toLocaleLowerCase().indexOf(query.toLocaleLowerCase());
 }
+function regexRipgrepIndex(preview, submatches) {
+    const start = submatches?.[0]?.start;
+    if (typeof start !== 'number' || !Number.isInteger(start) || start < 0)
+        return -1;
+    return Buffer.from(preview, 'utf8').subarray(0, start).toString('utf8').length;
+}
 function limitPerFile(matches) {
     const counts = new Map();
     return matches.filter((match) => {

package/dist/service/workspace-file-service.js

@@ -1,7 +1,7 @@
 import { tmpdir } from 'node:os';
 import { isAbsolute, win32 } from 'node:path';
 import { listWorkspaceFiles, mutateWorkspaceFile, normalizeFilePreviewPath, readAllowedFileContentRange, readWorkspaceFileContentRange, readAllowedTextFile, readWorkspaceTextFile, writeWorkspaceTextFile, WorkspaceFileIndex } from '../workspace.js';
-const INDEX_CACHE_LIMIT = 8;
+const INDEX_CACHE_LIMIT = 32;
 export class WorkspaceFileService {
     state;
     allowedRoots;

package/dist/service/workspace-workbench-service.js

@@ -37,6 +37,7 @@ export class WorkspaceWorkbenchService {
             'workspace.files.search': (data) => this.searchFiles(record(data)),
             'workspace.files.mutate': (data) => this.mutateFile(record(data)),
             'workspace.content.search': (data) => this.searchContent(record(data)),
+            'workspace.symbol.prepare': (data) => this.prepareSymbolIndex(record(data)),
             'workspace.symbol.definition': (data) => this.symbolDefinition(record(data)),
             'workspace.files.upload.preflight': (data) => this.preflight(record(data)),
             'workspace.files.upload.create': (data) => this.createUpload(record(data)),
@@ -116,6 +117,10 @@ export class WorkspaceWorkbenchService {
         const workspace = this.options.requireWorkspace(input.workspaceId);
         return { definition: await this.codeNavigation.definition(workspace, input) };
     }
+    async prepareSymbolIndex(input) {
+        const workspace = this.options.requireWorkspace(input.workspaceId);
+        return { preparation: await this.codeNavigation.prepare(workspace, input) };
+    }
     async preflight(input) {
         return {
             uploads: await this.options.uploads.preflight(this.options.requireWorkspace(input.workspaceId), input)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myagentroam/node",
-  "version": "0.9.95",
+  "version": "0.9.97",
   "description": "MyAgentRoam Node runtime CLI.",
   "license": "Apache-2.0 AND GPL-2.0-or-later",
   "type": "module",
@@ -30,8 +30,8 @@
     "npm": "11.12.1",
     "ws": "^8.21.3",
     "zod": "4.4.3",
-    "@myagentroam/agent": "0.9.95",
-    "@myagentroam/protocol": "0.9.95"
+    "@myagentroam/agent": "0.9.97",
+    "@myagentroam/protocol": "0.9.97"
   },
   "devDependencies": {
     "@types/ws": "^8.18.1"