@moretea-labs/forge 1.5.0 → 1.6.0

package/src/cli/mcp/transports/http.ts

@@ -1,4 +1,6 @@
 import { randomUUID, timingSafeEqual } from 'crypto';
+import { existsSync, watch } from 'fs';
+import { dirname } from 'path';
 import express, { type Request, type Response, type NextFunction } from 'express';
 import { tokenHandler } from '@modelcontextprotocol/sdk/server/auth/handlers/token.js';
 import { revocationHandler } from '@modelcontextprotocol/sdk/server/auth/handlers/revoke.js';
@@ -37,7 +39,7 @@ import { readForgeRuntimeStatus } from '../../../runtime/control-plane/runtime-s
 import { runtimeIdentitySnapshot } from '../../../runtime/gateway/mcp/runtime-tools';
 import { projectionBlocksReadiness, readRepositoryProjectionSnapshot } from '../../../runtime/projections/materialized-view';
 import { readRuntimeGeneration } from '../../../runtime/control-plane/runtime-generation';
-import { readRuntimeStatusSnapshot } from '../../../runtime/root/status';
+import { readRuntimeStatusSnapshot, runtimeStatusPath } from '../../../runtime/root/status';
 import { getRepository, listRepositories } from '../../repositories/registry';
 import { buildControllerTaskLedgerProjection } from '../../controller/task-ledger';
 import { legacyIssueAuthorityRetired } from '../../controller/legacy-issue-cutover';
@@ -95,6 +97,24 @@ function isInitializeRequest(body: unknown): boolean {
   return typeof body === 'object' && body !== null && (body as Record<string, unknown>).method === 'initialize';
 }
 
+function isServerDiscoverRequest(body: unknown): boolean {
+  return typeof body === 'object' && body !== null && (body as Record<string, unknown>).method === 'server/discover';
+}
+
+function sendLegacyServerDiscoverUnsupported(res: Response, body: unknown): void {
+  const record = typeof body === 'object' && body !== null ? body as Record<string, unknown> : {};
+  const id = typeof record.id === 'string' || typeof record.id === 'number' || record.id === null ? record.id : null;
+  res.setHeader('Cache-Control', 'no-store');
+  res.status(404).json({
+    jsonrpc: '2.0',
+    id,
+    error: {
+      code: -32601,
+      message: 'Method not found',
+    },
+  });
+}
+
 function initializeClientIdentity(req: Request, body: unknown, route: McpSessionRoute, principalId: string): string {
   const params = typeof body === 'object' && body !== null
     ? (body as { params?: { clientInfo?: { name?: unknown; version?: unknown } } }).params
@@ -676,6 +696,15 @@ async function handleMcpPost(
     return;
   }
   const sessionId = req.headers['mcp-session-id'] as string | undefined;
+  // MCP 2026-07-28 clients probe legacy servers with server/discover before
+  // falling back to the initialize-era protocol. Forge still serves the
+  // legacy stateful transport, so reject the unsupported modern RPC with the
+  // protocol-prescribed Method not found / HTTP 404 response instead of
+  // misclassifying it as a missing-session HTTP 400.
+  if (isServerDiscoverRequest(body)) {
+    sendLegacyServerDiscoverUnsupported(res, body);
+    return;
+  }
   if (isInitializeRequest(body)) {
     if (sessionId) {
       res.setHeader('Mcp-Session-Reset', 'reinitialized');
@@ -713,6 +742,7 @@ async function handleMcpPost(
         principalId,
       });
       const runtimeSchema = await resolveRuntimeSchema?.(sessionContext);
+      let server: ReturnType<typeof createForgeMcpServerFromContext> | undefined;
       transport = new StreamableHTTPServerTransport({
         sessionIdGenerator: () => randomUUID(),
         onsessioninitialized: (newSessionId: string): void => {
@@ -725,6 +755,7 @@ async function handleMcpPost(
             clientIdentity,
             toolSurfaceFingerprint: runtimeSchema?.fingerprint ?? currentToolSurfaceFingerprint(),
             toolNames: runtimeSchema?.toolNames,
+            notifyToolListChanged: async () => { await server?.sendToolListChanged(); },
           });
           initializedSessionId = newSessionId;
         },
@@ -732,7 +763,7 @@ async function handleMcpPost(
       transport.onclose = () => {
         if (transport?.sessionId) registry.detach(transport.sessionId);
       };
-      const server = createForgeMcpServerFromContext(sessionContext, runtimeSchema);
+      server = createForgeMcpServerFromContext(sessionContext, runtimeSchema);
       await server.connect(transport);
       await transport.handleRequest(req, res, body);
     } finally {
@@ -890,6 +921,23 @@ export async function startMcpHttp(opts: McpHttpOptions): Promise<void> {
   const currentRuntimeToolSurfaceFingerprint = () => runtimeControllerHome
     ? readRuntimeStatusSnapshot(runtimeControllerHome)?.toolSurfaceFingerprint
     : undefined;
+  let observedRuntimeToolSurfaceFingerprint = currentRuntimeToolSurfaceFingerprint();
+  let toolSurfaceNotificationTimer: ReturnType<typeof setTimeout> | undefined;
+  const runtimeStatusDirectory = runtimeControllerHome ? dirname(runtimeStatusPath(runtimeControllerHome)) : undefined;
+  const runtimeStatusWatcher = runtimeStatusDirectory && existsSync(runtimeStatusDirectory)
+    ? watch(runtimeStatusDirectory, { persistent: false }, (_event, filename) => {
+      if (String(filename ?? '') !== 'status.json') return;
+      if (toolSurfaceNotificationTimer) clearTimeout(toolSurfaceNotificationTimer);
+      toolSurfaceNotificationTimer = setTimeout(() => {
+        const currentFingerprint = currentRuntimeToolSurfaceFingerprint();
+        if (!currentFingerprint || currentFingerprint === observedRuntimeToolSurfaceFingerprint) return;
+        observedRuntimeToolSurfaceFingerprint = currentFingerprint;
+        void sessionRegistry.notifyToolListChanged(currentFingerprint);
+      }, 25);
+      toolSurfaceNotificationTimer.unref();
+    })
+    : undefined;
+  runtimeStatusWatcher?.on('error', () => undefined);
   const resolveRuntimeSchema = runtimeControllerHome
     ? async (context: McpToolContext): Promise<CanonicalRuntimeToolSchema | undefined> => {
       if (!('controllerHome' in context)) return undefined;
@@ -1233,6 +1281,8 @@ export async function startMcpHttp(opts: McpHttpOptions): Promise<void> {
 
   httpServer.on('close', () => {
     clearInterval(cleanupTimer);
+    if (toolSurfaceNotificationTimer) clearTimeout(toolSurfaceNotificationTimer);
+    runtimeStatusWatcher?.close();
     void sessionRegistry.closeAll('shutdown');
   });
 

package/src/cli/mcp/transports/session-registry.ts

@@ -31,6 +31,9 @@ export interface ManagedMcpSession<
   toolSurfaceFingerprint?: string;
   /** Exact tool names returned by the Canonical Runtime at initialize time. */
   toolNames?: string[];
+  /** Standard MCP tools/list_changed notification bound to this session's connected Server. */
+  notifyToolListChanged?: () => Promise<void> | void;
+  lastNotifiedToolSurfaceFingerprint?: string;
   createdAt: number;
   lastActivityAt: number;
   streamOpenedAt?: number;
@@ -88,6 +91,7 @@ interface RegisterMcpSession<TTransport extends ClosableMcpTransport, TContext>
   clientIdentity: string;
   toolSurfaceFingerprint?: string;
   toolNames?: string[];
+  notifyToolListChanged?: () => Promise<void> | void;
   initialPost?: boolean;
 }
 
@@ -206,6 +210,26 @@ export class McpSessionRegistry<
     if (session) session.lastActivityAt = this.now();
   }
 
+  async notifyToolListChanged(currentFingerprint: string | undefined): Promise<number> {
+    if (!currentFingerprint) return 0;
+    let notified = 0;
+    await Promise.all(Array.from(this.sessions.values()).map(async (session) => {
+      if (!session.toolSurfaceFingerprint
+        || session.toolSurfaceFingerprint === currentFingerprint
+        || session.lastNotifiedToolSurfaceFingerprint === currentFingerprint
+        || !session.notifyToolListChanged) return;
+      try {
+        await session.notifyToolListChanged();
+        session.lastNotifiedToolSurfaceFingerprint = currentFingerprint;
+        notified += 1;
+      } catch {
+        // Fingerprint fencing remains authoritative. A broken notification
+        // stream must not mark a stale session as refreshed or close active work.
+      }
+    }));
+    return notified;
+  }
+
   beginPost(sessionId: string): ManagedMcpSession<TTransport, TContext> | undefined {
     const session = this.sessions.get(sessionId);
     if (!session) return undefined;

package/src/cli/repositories/command-classifier.ts

@@ -80,6 +80,77 @@ function shellSegments(command: string): string[] {
   return segments;
 }
 
+function shellWordsPreservingQuotes(segment: string): string[] {
+  const words: string[] = [];
+  let current = '';
+  let quote: "'" | '"' | undefined;
+  let escaped = false;
+  const flush = () => {
+    if (current) words.push(current);
+    current = '';
+  };
+  for (let index = 0; index < segment.length; index += 1) {
+    const char = segment[index]!;
+    if (escaped) { current += char; escaped = false; continue; }
+    if (char === '\\' && quote !== "'") { escaped = true; continue; }
+    if (quote) {
+      if (char === quote) quote = undefined;
+      else current += char;
+      continue;
+    }
+    if (char === "'" || char === '"') { quote = char; continue; }
+    if (/\s/.test(char)) { flush(); continue; }
+    current += char;
+  }
+  flush();
+  return words;
+}
+
+const SAFE_SQLITE_READ_OPTIONS = new Set([
+  '-safe', '--safe', '-readonly', '--readonly', '-batch', '--batch',
+  '-header', '--header', '-noheader', '--noheader', '-json', '--json',
+  '-csv', '--csv', '-list', '--list', '-line', '--line', '-column', '--column',
+  '-tabs', '--tabs', '-table', '--table', '-box', '--box', '-markdown', '--markdown',
+  '-quote', '--quote', '-ascii', '--ascii',
+]);
+
+function isSingleReadOnlySql(sql: string): boolean {
+  const normalized = sql.trim();
+  if (!normalized || normalized.startsWith('.')) return false;
+  const withoutTrailingSemicolon = normalized.endsWith(';') ? normalized.slice(0, -1).trimEnd() : normalized;
+  if (withoutTrailingSemicolon.includes(';')) return false;
+  if (!/^(?:select\b|with\b)/i.test(withoutTrailingSemicolon)) return false;
+  return !/\b(?:insert|update|delete|replace|create|drop|alter|vacuum|attach|detach|reindex|analyze|pragma|begin|commit|rollback|savepoint|release)\b/i.test(withoutTrailingSemicolon);
+}
+
+function isSafeReadOnlySqliteWords(rawWords: string[]): boolean {
+  const words = rawWords.filter(Boolean);
+  const program = words[0]?.split(/[\\/]/).at(-1)?.toLowerCase();
+  if (program !== 'sqlite3') return false;
+  const args = words.slice(1);
+  if (args.some((word) => /^(?:--?nonce)(?:=|$)/i.test(word) || /^(?:--?unsafe-testing)(?:=|$)/i.test(word))) return false;
+  let safe = false;
+  let readonly = false;
+  let index = 0;
+  for (; index < args.length; index += 1) {
+    const arg = args[index]!;
+    if (!arg.startsWith('-')) break;
+    if (!SAFE_SQLITE_READ_OPTIONS.has(arg.toLowerCase())) return false;
+    if (arg === '-safe' || arg === '--safe') safe = true;
+    if (arg === '-readonly' || arg === '--readonly') readonly = true;
+  }
+  if (!safe || !readonly) return false;
+  const database = args[index];
+  const sql = args[index + 1];
+  if (!database || !sql || args.length !== index + 2) return false;
+  return isSingleReadOnlySql(sql);
+}
+
+function isSafeReadOnlySqliteSegment(segment: string): boolean {
+  const stripped = segment.replace(/^\s*(?:[A-Za-z_][A-Za-z0-9_]*=[^\s]+\s+)*/, '');
+  return isSafeReadOnlySqliteWords(shellWordsPreservingQuotes(stripped));
+}
+
 function isSedInPlaceSegment(segment: string): boolean {
   const words = firstWords(segment);
   if (words[0]?.toLowerCase() !== 'sed') return false;
@@ -177,11 +248,18 @@ function readOnlyGitSegment(words: string[], _segment: string): boolean {
   return isReadOnlyGitCommand(words);
 }
 
+function isReadOnlyCodegraphCommand(words: string[]): boolean {
+  const program = words[0]?.split(/[\\/]/).at(-1)?.toLowerCase();
+  return program === 'codegraph' && words[1]?.toLowerCase() === 'status';
+}
+
 function isReadOnlySegment(segment: string): boolean {
   const words = firstWords(segment);
   const program = words[0]?.toLowerCase();
   if (!program) return false;
   if (program === 'git') return readOnlyGitSegment(words, segment);
+  if (isReadOnlyCodegraphCommand(words)) return true;
+  if (program === 'sqlite3') return isSafeReadOnlySqliteSegment(segment);
   if (program === 'find') return !/(?:-delete|-exec|-execdir|-ok|-okdir)\b/.test(segment);
   if (program === 'sed') return !isSedInPlaceSegment(segment);
   if (program === 'gh') {
@@ -193,6 +271,26 @@ function isReadOnlySegment(segment: string): boolean {
 /** Package scripts that are local validation (not install/publish/mutate deps). */
 const SAFE_PACKAGE_SCRIPT = /^(?:test|check|lint|typecheck|format:check|tsc)(?::|$)/i;
 
+function isReadOnlyLoopbackCurl(words: string[]): boolean {
+  const program = words[0]?.split(/[\\/]/).at(-1)?.toLowerCase();
+  if (program !== 'curl') return false;
+  const args = words.slice(1);
+  const writeFlags = new Set(['-d', '--data', '--data-raw', '--data-binary', '-f', '--form', '-t', '--upload-file', '-o', '--output', '-O', '--remote-name']);
+  if (args.some((arg) => writeFlags.has(arg))) return false;
+  for (let index = 0; index < args.length; index += 1) {
+    if (args[index] === '-X' || args[index] === '--request') {
+      if (!/^(?:GET|HEAD)$/i.test(args[index + 1] ?? '')) return false;
+      index += 1;
+    }
+  }
+  const urls = args.filter((arg) => /^https?:\/\//i.test(arg));
+  if (urls.length === 0) return false;
+  return urls.every((url) => {
+    try { return ['127.0.0.1', 'localhost', '::1'].includes(new URL(url).hostname.toLowerCase()); }
+    catch { return false; }
+  });
+}
+
 function isSafePackageRunner(program: string, words: string[]): boolean {
   if (!['bun', 'npm', 'pnpm', 'yarn', 'node'].includes(program)) return false;
   // bun test <path>, npm test, etc.
@@ -440,6 +538,15 @@ function classifyArgvCommand(
   if (program === 'git' && isReadOnlyGitCommand(argv)) {
     return { risk: 'readonly', confirmation: 'none', reasons: ['the argv command is a recognized repository-local read operation'] };
   }
+  if (isReadOnlyCodegraphCommand(argv)) {
+    return { risk: 'readonly', confirmation: 'none', reasons: ['CodeGraph status only observes the local semantic index'] };
+  }
+  if (program === 'curl' && isReadOnlyLoopbackCurl(argv)) {
+    return { risk: 'readonly', confirmation: 'none', reasons: ['curl performs a read-only loopback HTTP observation without writing response data to disk'] };
+  }
+  if (program === 'sqlite3' && isSafeReadOnlySqliteWords(argv)) {
+    return { risk: 'readonly', confirmation: 'none', reasons: ['sqlite3 is constrained by safe mode, readonly database access, and one read-only SQL statement'] };
+  }
   // Explicit shell wrappers are common in generated diagnostics. Re-classify
   // the fixed inner command instead of treating `sh -c` / `bash -lc` wrappers
   // as workspace mutations. Unsafe shell constructs are still rejected by the
@@ -484,6 +591,12 @@ function classifyArgvCommand(
     || (['npm', 'bun', 'pnpm', 'yarn'].includes(program) && ['install', 'add', 'remove', 'update', 'run'].includes(subcommand ?? ''))) {
     return { risk: 'workspace_write', confirmation: 'authorization', reasons: ['writes repository files'] };
   }
+  // Package-manager `version` is a mutation command (for example
+  // `npm version 1.5.1 --no-git-tag-version` updates package metadata). Keep
+  // flag-style queries such as `npm --version` on the readonly path below.
+  if (['npm', 'pnpm', 'yarn'].includes(program) && subcommand === 'version') {
+    return { risk: 'workspace_write', confirmation: 'authorization', reasons: ['package-manager version command may update package metadata'] };
+  }
   // Lightweight project script info queries stay readonly when they only request help/version.
   if (['bun', 'node', 'npm', 'pnpm', 'yarn', 'python', 'python3', 'cargo', 'go', 'swift'].includes(program)
     && argv.slice(1).some((word) => word === '--help' || word === '-h' || word === '--version' || word === '-V' || word === 'version' || word === 'help')) {

package/src/cli/repositories/safe-patch.ts

@@ -7,6 +7,7 @@ import {
   getEditSession,
   type EditOperation,
   type EditSession,
+  type EditSessionBinding,
   type EditSessionPatchError,
 } from '../editing/edit-session';
 import { getMcpPolicy } from '../mcp/policy';
@@ -345,6 +346,7 @@ export function applySafePatch(repository: RepositoryRecord, input: {
   continueOnError?: unknown;
   refreshFingerprints?: unknown;
   recoverStaleSession?: unknown;
+  binding?: EditSessionBinding;
 }): SafePatchApplyResult {
   const operations = normalizedSafePatchOperations(input.operations);
   if (operations.length === 0) throw new Error('SAFE_PATCH_OPERATIONS_REQUIRED: provide at least one operation');
@@ -356,7 +358,7 @@ export function applySafePatch(repository: RepositoryRecord, input: {
   const allowedPaths = Array.isArray(input.allowedPaths) ? input.allowedPaths.map((item) => String(item).trim()).filter(Boolean) : undefined;
   let session = sessionId
     ? getEditSession(repository.canonicalRoot, sessionId)
-    : beginEditSession(repository.canonicalRoot, { purpose: String(input.purpose ?? 'Safe repository patch').trim() || 'Safe repository patch', allowedPaths });
+    : beginEditSession(repository.canonicalRoot, { purpose: String(input.purpose ?? 'Safe repository patch').trim() || 'Safe repository patch', allowedPaths, binding: input.binding });
   const createdSession = !sessionId;
   let recoveredSession: SafePatchRecoveredSession | undefined;
   const appliedChunks: SafePatchAppliedChunk[] = [];
@@ -376,17 +378,17 @@ export function applySafePatch(repository: RepositoryRecord, input: {
       continue;
     }
     try {
-      session = applyEditOperations(repository.canonicalRoot, policy, session.sessionId, preflight.operations.map(stripInternalIndex), { expectedRevision, maxBatchOperations: MAX_SAFE_PATCH_CHUNK_SIZE });
+      session = applyEditOperations(repository.canonicalRoot, policy, session.sessionId, preflight.operations.map(stripInternalIndex), { expectedRevision, maxBatchOperations: MAX_SAFE_PATCH_CHUNK_SIZE, binding: input.binding });
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       if (!sessionId && input.recoverStaleSession !== false && message.includes('EDIT_SESSION_FINGERPRINT_STALE')) {
         const previousSessionId = session.sessionId;
-        session = beginEditSession(repository.canonicalRoot, { purpose: `${String(input.purpose ?? 'Safe repository patch').trim() || 'Safe repository patch'} (recovered)`, allowedPaths });
+        session = beginEditSession(repository.canonicalRoot, { purpose: `${String(input.purpose ?? 'Safe repository patch').trim() || 'Safe repository patch'} (recovered)`, allowedPaths, binding: input.binding });
         expectedRevision = session.currentRevision;
         recoveredSession = { reason: 'Previous edit session fingerprints were stale; remaining chunks were moved into a fresh session.', previousSessionId, newSessionId: session.sessionId };
         const retry = preflightChunk(repository, group, chunkIndex, refresh);
         if (retry.failures.length === 0) {
-          session = applyEditOperations(repository.canonicalRoot, policy, session.sessionId, retry.operations.map(stripInternalIndex), { expectedRevision, maxBatchOperations: MAX_SAFE_PATCH_CHUNK_SIZE });
+          session = applyEditOperations(repository.canonicalRoot, policy, session.sessionId, retry.operations.map(stripInternalIndex), { expectedRevision, maxBatchOperations: MAX_SAFE_PATCH_CHUNK_SIZE, binding: input.binding });
         } else {
           failures.push(...retry.failures);
           failedChunk = chunkIndex;

package/src/cli/repositories/structured-git.ts

@@ -236,18 +236,60 @@ export function repositoryGitFinishWorkflow(controllerHome: string, repository:
   const featureBranch = assertSafeBranchName(input.featureBranch ?? before.branch);
   const targetBranch = assertSafeBranchName(input.targetBranch ?? repository.defaultBranch ?? 'main');
   const steps: RepositoryGitFinishResult['steps'] = [];
-  if (!before.clean) {
-    return { repoId: repository.repoId, checkoutId: repository.activeCheckoutId, featureBranch, targetBranch, before, steps, after: before, completed: false, error: { code: 'GIT_WORKTREE_NOT_CLEAN', message: 'Commit or revert all changes before finishing a workflow.' } };
+  const alreadyOnTarget = before.branch === targetBranch;
+  if (!before.clean && !alreadyOnTarget) {
+    return { repoId: repository.repoId, checkoutId: repository.activeCheckoutId, featureBranch, targetBranch, before, steps, after: before, completed: false, error: { code: 'GIT_WORKTREE_NOT_CLEAN', message: 'Commit or revert changes before switching branches to finish a workflow.' } };
   }
   if (featureBranch === targetBranch) {
     return { repoId: repository.repoId, checkoutId: repository.activeCheckoutId, featureBranch, targetBranch, before, steps, after: before, completed: false, error: { code: 'GIT_ALREADY_ON_TARGET', message: 'Current/feature branch equals target branch; nothing to merge or delete.' } };
   }
-  const switchTarget = executeRepositoryGitCommand(controllerHome, repository, { args: ['switch', targetBranch], authorization: 'explicit_user_request', ...input });
-  steps.push({ name: 'switch_target', execution: switchTarget });
-  if (switchTarget.status !== 'executed' || switchTarget.ok !== true) return { repoId: repository.repoId, checkoutId: repository.activeCheckoutId, featureBranch, targetBranch, before, steps, after: repositoryGitStatus(repository), completed: false, error: { code: 'GIT_SWITCH_TARGET_FAILED', message: switchTarget.stderr || 'git switch failed' } };
-  const merge = executeRepositoryGitCommand(controllerHome, repository, { args: ['merge', ...(input.noFf === true ? ['--no-ff'] : ['--ff-only']), featureBranch], authorization: 'explicit_user_request', ...input });
+  if (!alreadyOnTarget) {
+    const switchTarget = executeRepositoryGitCommand(controllerHome, repository, { args: ['switch', targetBranch], authorization: 'explicit_user_request', ...input });
+    steps.push({ name: 'switch_target', execution: switchTarget });
+    if (switchTarget.status !== 'executed' || switchTarget.ok !== true) return { repoId: repository.repoId, checkoutId: repository.activeCheckoutId, featureBranch, targetBranch, before, steps, after: repositoryGitStatus(repository), completed: false, error: { code: 'GIT_SWITCH_TARGET_FAILED', message: switchTarget.stderr || 'git switch failed' } };
+  }
+  const protectTrackedChanges = alreadyOnTarget && (before.staged.length > 0 || before.unstaged.length > 0);
+  const finishAuthorization = 'explicit_user_request' as const;
+  let stashRef: string | null = null;
+  if (protectTrackedChanges) {
+    const stash = executeRepositoryGitCommand(controllerHome, repository, { args: ['stash', 'push', '-m', `forge-finish:${input.workId ?? featureBranch}`], authorization: finishAuthorization, ...input });
+    steps.push({ name: 'stash_target_changes', execution: stash });
+    if (stash.status !== 'executed' || stash.ok !== true) return { repoId: repository.repoId, checkoutId: repository.activeCheckoutId, featureBranch, targetBranch, before, steps, after: repositoryGitStatus(repository), completed: false, error: { code: 'GIT_STASH_LOCAL_CHANGES_FAILED', message: stash.stderr || 'git stash push failed' } };
+    stashRef = gitText(repository, ['rev-parse', 'refs/stash']);
+    if (!stashRef) return { repoId: repository.repoId, checkoutId: repository.activeCheckoutId, featureBranch, targetBranch, before, steps, after: repositoryGitStatus(repository), completed: false, error: { code: 'GIT_STASH_REFERENCE_MISSING', message: 'Tracked changes were stashed but the stash reference could not be resolved.' } };
+    const workingTreeMerge = runGit(repository, ['merge-tree', '--write-tree', featureBranch, stashRef], 128 * 1024);
+    const indexTreeMerge = runGit(repository, ['merge-tree', '--write-tree', featureBranch, `${stashRef}^2`], 128 * 1024);
+    if (!workingTreeMerge.ok || !indexTreeMerge.ok) {
+      const restore = executeRepositoryGitCommand(controllerHome, repository, { args: ['stash', 'apply', '--index', stashRef], authorization: finishAuthorization, ...input });
+      steps.push({ name: 'restore_target_changes_after_preflight_conflict', execution: restore });
+      if (restore.status !== 'executed' || restore.ok !== true) return { repoId: repository.repoId, checkoutId: repository.activeCheckoutId, featureBranch, targetBranch, before, steps, after: repositoryGitStatus(repository), completed: false, error: { code: 'GIT_LOCAL_CHANGES_RESTORE_FAILED', message: restore.stderr || 'Tracked target changes could not be restored after integration preflight; recovery stash was retained.' } };
+      const drop = executeRepositoryGitCommand(controllerHome, repository, { args: ['stash', 'drop', stashRef], authorization: finishAuthorization, ...input });
+      steps.push({ name: 'drop_target_stash', execution: drop });
+      return { repoId: repository.repoId, checkoutId: repository.activeCheckoutId, featureBranch, targetBranch, before, steps, after: repositoryGitStatus(repository), completed: false, error: { code: 'GIT_LOCAL_CHANGES_REAPPLY_CONFLICT', message: workingTreeMerge.stderr || indexTreeMerge.stderr || 'Tracked target changes conflict with the feature branch; target branch was left unchanged and local changes were restored.' } };
+    }
+  }
+  const applyTrackedStash = (name: string): RepositoryGitExecution | undefined => {
+    if (!stashRef) return undefined;
+    const execution = executeRepositoryGitCommand(controllerHome, repository, { args: ['stash', 'apply', '--index', stashRef], authorization: finishAuthorization, ...input });
+    steps.push({ name, execution });
+    return execution;
+  };
+  const dropTrackedStash = (): void => {
+    if (!stashRef) return;
+    const execution = executeRepositoryGitCommand(controllerHome, repository, { args: ['stash', 'drop', stashRef], authorization: finishAuthorization, ...input });
+    steps.push({ name: 'drop_target_stash', execution });
+  };
+  const merge = executeRepositoryGitCommand(controllerHome, repository, { args: ['merge', ...(input.noFf === true ? ['--no-ff'] : ['--ff-only']), featureBranch], authorization: finishAuthorization, ...input });
   steps.push({ name: 'merge_feature', execution: merge });
-  if (merge.status !== 'executed' || merge.ok !== true) return { repoId: repository.repoId, checkoutId: repository.activeCheckoutId, featureBranch, targetBranch, before, steps, after: repositoryGitStatus(repository), completed: false, error: { code: 'GIT_MERGE_FAILED', message: merge.stderr || 'git merge failed' } };
+  if (merge.status !== 'executed' || merge.ok !== true) {
+    const restore = applyTrackedStash('restore_target_changes_after_merge_failure');
+    if (restore && (restore.status !== 'executed' || restore.ok !== true)) return { repoId: repository.repoId, checkoutId: repository.activeCheckoutId, featureBranch, targetBranch, before, steps, after: repositoryGitStatus(repository), completed: false, error: { code: 'GIT_LOCAL_CHANGES_RESTORE_FAILED', message: restore.stderr || 'git stash apply failed while restoring the pre-merge target state' } };
+    dropTrackedStash();
+    return { repoId: repository.repoId, checkoutId: repository.activeCheckoutId, featureBranch, targetBranch, before, steps, after: repositoryGitStatus(repository), completed: false, error: { code: 'GIT_MERGE_FAILED', message: merge.stderr || 'git merge failed' } };
+  }
+  const reapply = applyTrackedStash('reapply_target_changes');
+  if (reapply && (reapply.status !== 'executed' || reapply.ok !== true)) return { repoId: repository.repoId, checkoutId: repository.activeCheckoutId, featureBranch, targetBranch, before, steps, after: repositoryGitStatus(repository), completed: false, error: { code: 'GIT_LOCAL_CHANGES_RESTORE_FAILED', message: reapply.stderr || 'Tracked target changes passed merge-tree preflight but could not be reapplied after merge; recovery stash was retained.' } };
+  dropTrackedStash();
   if (input.deleteBranch !== false) {
     const del = executeRepositoryGitCommand(controllerHome, repository, { args: ['branch', '-d', featureBranch], authorization: 'explicit_user_request', ...input });
     steps.push({ name: 'delete_feature_branch', execution: del });

package/src/cli/repository/inspector.ts

@@ -1,5 +1,5 @@
 import { createHash } from 'crypto';
-import { existsSync, lstatSync, readdirSync, readFileSync, statSync } from 'fs';
+import { existsSync, lstatSync, readdirSync, readFileSync, realpathSync, statSync } from 'fs';
 import { join } from 'path';
 import { runProcess } from '../../effects/process-runner';
 import { globMatches, resolveMcpPath } from '../mcp/paths';
@@ -264,6 +264,8 @@ export interface SearchRepositoryOptions {
 
 export interface SearchRepositoryManyOptions {
   queries: string[];
+  /** Pre-resolved exact candidate files. Skips repository inventory discovery. */
+  files?: string[];
   includeGlobs?: string[];
   excludeGlobs?: string[];
   maxResultsPerQuery?: number;
@@ -327,7 +329,17 @@ export function searchRepositoryMany(
   const maxFiles = Math.min(Math.max(opts.maxFiles ?? 5000, 1), 20_000);
   const includes = opts.includeGlobs ?? [];
   const excludes = [...(includes.length === 0 ? DEFAULT_EXCLUDES : []), ...(opts.excludeGlobs ?? [])];
-  const inventory = searchInventory(repoRoot, includes, excludes, maxFiles, opts.cacheKey);
+  const directFiles = opts.files?.map((path) => path.trim()).filter(Boolean);
+  const directCandidates = directFiles
+    ? Array.from(new Set(directFiles)).filter((path) => !isExcluded(path, excludes))
+    : undefined;
+  const inventory = directCandidates && directCandidates.length > 0
+    ? {
+        files: directCandidates.slice(0, maxFiles),
+        candidateCount: directCandidates.length,
+        cacheHit: false,
+      }
+    : searchInventory(repoRoot, includes, excludes, maxFiles, opts.cacheKey);
   const needles = queries.map((query) => ({ query, needle: opts.caseSensitive ? query : query.toLowerCase() }));
   const counts = new Map(queries.map((query) => [query, 0]));
   const results: SearchRepositoryManyResult['results'] = [];
@@ -335,10 +347,11 @@ export function searchRepositoryMany(
   let policyDeniedFiles = 0;
   let skippedLargeFiles = 0;
   let skippedBinaryFiles = 0;
+  const canonicalRepoRoot = realpathSync(repoRoot);
 
   for (const path of inventory.files) {
     if (needles.every(({ query }) => (counts.get(query) ?? 0) >= maxResultsPerQuery)) break;
-    const decision = resolveMcpPath(repoRoot, path, policy, 'read');
+    const decision = resolveMcpPath(repoRoot, path, policy, 'read', canonicalRepoRoot);
     if (!decision.ok || !decision.absolutePath) {
       policyDeniedFiles += 1;
       continue;

package/src/runtime/assistant/intent.ts

@@ -370,8 +370,8 @@ export function runAssistantRoutineNow(
     relatedRoutineId: routine.routineId,
     relatedRequestId: requestId,
     jobIds: [],
-    recommendations: ['Claim or create Work for this routine, then execute it through an explicit external Controller.'],
-    data: { routine: touched, externalControllerRequired: true },
+    recommendations: ['Resume this existing Routine authority through its external Controller context. Do not create a new Work merely because the timer fired.'],
+    data: { routine: touched, externalControllerRequired: true, createWorkOnTrigger: false },
   });
   return {
     schemaVersion: 1,
@@ -381,7 +381,7 @@ export function runAssistantRoutineNow(
     requestId,
     understoodIntent: 'run_routine',
     displayTitle: `Routine requires an external Controller: ${routine.name}`,
-    displayText: 'No ExecutionJob was created. Continue this routine from the recorded Inbox item with an explicitly claimed Controller session.',
+    displayText: 'No ExecutionJob or new Work was created. Continue the existing Routine authority from the recorded Inbox item with an explicitly claimed Controller session.',
     requiresConfirmation: false,
     plan: [],
     routine: touched,