@moretea-labs/forge 1.5.1 → 1.6.0

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,

package/src/runtime/control-plane/execution/direct-edit-work-completion.ts

@@ -1,8 +1,11 @@
 import { createHash } from 'crypto';
 import { getEditSession, listEditSessions, type EditSession } from '../../../cli/editing/edit-session';
+import { globMatches } from '../../../cli/mcp/paths';
 import { runProcess } from '../../../effects/process-runner';
-import { getWorkContract, recordWorkCompletionReceipt } from '../facade/work-contract-store';
-import { isTerminalWorkContractStatus, type DirectEditWorkCompletionReceipt } from '../facade/types';
+import { completeRequirementFromWork } from '../persistence/requirement-store';
+import { getWorkContract, recordWorkCompletionReceipt, updateWorkContract } from '../facade/work-contract-store';
+import { isDirectEditWorkCompletionReceipt, isTerminalWorkContractStatus, type DirectEditWorkCompletionReceipt, type WorkReconciliationRecord } from '../facade/types';
+import { effectiveVerificationEvidence } from './verification-evidence';
 
 export interface DirectEditWorkCompletionReconciliation {
   completedWorkIds: string[];
@@ -149,3 +152,155 @@ export function reconcileFinalizedDirectEditWorksAfterCommit(input: {
 
   return { completedWorkIds, examinedSessionIds, skipped, targetBranch, targetRevision };
 }
+
+export interface ReviewedDirectEditWorkReconciliationInput {
+  controllerHome: string;
+  repoId: string;
+  checkoutId: string;
+  repoRoot: string;
+  workId: string;
+  targetBranch: string;
+  targetRevision: string;
+  comparedPaths: string[];
+  reviewer: string;
+  rationale: string;
+  cleanupOwnershipProof: string;
+  reviewedAt?: string;
+}
+
+function exactCommit(repoRoot: string, revision: string, label: string): string {
+  const result = git(repoRoot, ['rev-parse', '--verify', `${revision}^{commit}`]);
+  if (!result.ok || !result.stdout.trim()) throw new Error(`DIRECT_EDIT_WORK_RECONCILIATION_${label}_INVALID`);
+  return result.stdout.trim();
+}
+
+function comparedRevisionPaths(repoRoot: string, baseRevision: string, targetRevision: string): string[] {
+  const result = git(repoRoot, ['diff', '--name-only', '-z', baseRevision, targetRevision]);
+  if (!result.ok) throw new Error('DIRECT_EDIT_WORK_RECONCILIATION_CHANGED_PATHS_UNAVAILABLE');
+  return [...new Set(result.stdout.split('\0').filter(Boolean))].sort((left, right) => left.localeCompare(right));
+}
+
+function normalizedComparedPaths(paths: string[]): string[] {
+  const normalized = [...new Set(paths.map((path) => path.trim()))].sort((left, right) => left.localeCompare(right));
+  if (normalized.length === 0 || normalized.length > 100 || normalized.some((path) => !path || path.startsWith('/') || path.includes('\0') || path.split('/').some((part) => part === '' || part === '.' || part === '..'))) {
+    throw new Error('DIRECT_EDIT_WORK_RECONCILIATION_PATHS_INVALID');
+  }
+  return normalized;
+}
+
+/**
+ * Explicitly close a historically delivered Direct Edit Work whose original
+ * edit-session binding was missed. This is never inferred: the caller must
+ * supply the exact accepted revision and the complete reviewed path set.
+ */
+export function acceptReviewedDirectEditWorkReconciliation(input: ReviewedDirectEditWorkReconciliationInput): {
+  workId: string;
+  reconciliation: WorkReconciliationRecord;
+  receipt: DirectEditWorkCompletionReceipt;
+} {
+  const work = getWorkContract({ controllerHome: input.controllerHome, repoId: input.repoId }, input.workId);
+  if (!work || work.repoId !== input.repoId) throw new Error(`DIRECT_EDIT_WORK_RECONCILIATION_WORK_NOT_FOUND: ${input.workId}`);
+  if (work.checkoutId && work.checkoutId !== input.checkoutId) throw new Error(`DIRECT_EDIT_WORK_RECONCILIATION_CHECKOUT_MISMATCH: ${input.workId}`);
+  if (work.completionReceipt) {
+    const completionReceipt = work.completionReceipt;
+    if (isDirectEditWorkCompletionReceipt(completionReceipt) && completionReceipt.reconciliationId) {
+      const existing = work.reconciliations.find((entry) => entry.reconciliationId === completionReceipt.reconciliationId);
+      if (existing) return { workId: work.workId, reconciliation: existing, receipt: completionReceipt };
+    }
+    throw new Error(`DIRECT_EDIT_WORK_RECONCILIATION_WORK_TERMINAL: ${input.workId}`);
+  }
+  if (isTerminalWorkContractStatus(work.status) || work.workKind !== 'repository_change') {
+    throw new Error(`DIRECT_EDIT_WORK_RECONCILIATION_WORK_NOT_ELIGIBLE: ${input.workId}`);
+  }
+  if (!work.baseRevision?.trim()) throw new Error('DIRECT_EDIT_WORK_RECONCILIATION_BASE_REVISION_MISSING');
+
+  const baseRevision = exactCommit(input.repoRoot, work.baseRevision, 'BASE_REVISION');
+  const targetRevision = exactCommit(input.repoRoot, input.targetRevision.trim(), 'TARGET_REVISION');
+  const targetBranch = input.targetBranch.trim();
+  if (!targetBranch) throw new Error('DIRECT_EDIT_WORK_RECONCILIATION_TARGET_BRANCH_REQUIRED');
+  if (!git(input.repoRoot, ['merge-base', '--is-ancestor', baseRevision, targetRevision]).ok) {
+    throw new Error('DIRECT_EDIT_WORK_RECONCILIATION_TARGET_NOT_DESCENDANT');
+  }
+  if (!git(input.repoRoot, ['merge-base', '--is-ancestor', targetRevision, targetBranch]).ok) {
+    throw new Error('DIRECT_EDIT_WORK_RECONCILIATION_TARGET_UNREACHABLE');
+  }
+
+  const comparedPaths = normalizedComparedPaths(input.comparedPaths);
+  const actualPaths = comparedRevisionPaths(input.repoRoot, baseRevision, targetRevision);
+  if (comparedPaths.length !== actualPaths.length || comparedPaths.some((path, index) => path !== actualPaths[index])) {
+    throw new Error('DIRECT_EDIT_WORK_RECONCILIATION_PATH_COMPARISON_MISMATCH');
+  }
+  for (const path of comparedPaths) {
+    if (work.forbiddenPaths.some((pattern) => globMatches(pattern, path))) throw new Error(`DIRECT_EDIT_WORK_RECONCILIATION_FORBIDDEN_PATH: ${path}`);
+    if (work.allowedPaths.length > 0 && !work.allowedPaths.some((pattern) => globMatches(pattern, path))) throw new Error(`DIRECT_EDIT_WORK_RECONCILIATION_PATH_OUT_OF_SCOPE: ${path}`);
+  }
+  const dirty = git(input.repoRoot, ['status', '--porcelain=v1', '--', ...comparedPaths]);
+  if (!dirty.ok || dirty.stdout.trim()) throw new Error('DIRECT_EDIT_WORK_RECONCILIATION_OWNED_PATHS_DIRTY');
+
+  let verifiedAt = new Date().toISOString();
+  for (const checkId of work.checks) {
+    const current = effectiveVerificationEvidence(work.checkRefs, {
+      sourceRevision: targetRevision,
+      checkId,
+      requestedChecks: work.checks,
+    }).find((entry) => entry.current && entry.record.outcome === 'valid_pass');
+    if (!current) throw new Error(`DIRECT_EDIT_WORK_RECONCILIATION_CHECK_EVIDENCE_STALE: ${checkId}`);
+    verifiedAt = current.record.completedAt ?? current.record.recordedAt ?? verifiedAt;
+  }
+
+  const reviewer = input.reviewer.trim();
+  const rationale = input.rationale.trim();
+  const cleanupOwnershipProof = input.cleanupOwnershipProof.trim();
+  const reviewedAt = input.reviewedAt ?? new Date().toISOString();
+  if (!reviewer || !rationale || !cleanupOwnershipProof || Number.isNaN(Date.parse(reviewedAt))) {
+    throw new Error('DIRECT_EDIT_WORK_RECONCILIATION_REVIEW_METADATA_INVALID');
+  }
+  const reconciliationId = `RECNC-${createHash('sha256').update([input.repoId, input.workId, baseRevision, targetRevision, comparedPaths.join('\0'), reviewer, reviewedAt].join('\0')).digest('hex').slice(0, 16)}`;
+  const reconciliation: WorkReconciliationRecord = {
+    schemaVersion: 1,
+    reconciliationId,
+    originalExpectedRevision: targetRevision,
+    observedTargetRevision: targetRevision,
+    baseRevision,
+    targetBranch,
+    reachable: true,
+    method: 'owned_path_tree',
+    comparedPaths,
+    reviewer: reviewer.slice(0, 200),
+    reviewedAt,
+    unrecoverableStages: ['receipt'],
+    cleanupOwnershipProof: cleanupOwnershipProof.slice(0, 2_000),
+    rationale: rationale.slice(0, 2_000),
+    outcome: 'accepted_equivalence',
+  };
+  updateWorkContract({ controllerHome: input.controllerHome, repoId: input.repoId }, input.workId, {
+    reconciliations: [reconciliation, ...work.reconciliations.filter((entry) => entry.reconciliationId !== reconciliationId)],
+  });
+
+  const recordedAt = new Date().toISOString();
+  const receipt: DirectEditWorkCompletionReceipt = {
+    schemaVersion: 1,
+    receiptId: `REC-direct-edit-reconciled-${createHash('sha256').update(`${input.repoId}\0${input.workId}\0${reconciliationId}\0${targetRevision}`).digest('hex').slice(0, 20)}`,
+    source: 'direct_edit_work',
+    workId: input.workId,
+    reconciliationId,
+    targetBranch,
+    targetRevision,
+    sourceRevision: targetRevision,
+    baseRevision,
+    changedPaths: comparedPaths,
+    delivery: { kind: 'commit', status: 'integrated', strategy: 'already_integrated', reachable: true, recordedAt },
+    cleanup: { status: 'complete', warnings: [], blockers: [], recordedAt },
+    verifiedAt,
+    recordedAt,
+  };
+  const recorded = recordWorkCompletionReceipt(
+    { controllerHome: input.controllerHome, repoId: input.repoId },
+    input.workId,
+    receipt,
+    'completed_changed',
+    'repository_change',
+  );
+  if (recorded.requirementId) completeRequirementFromWork({ controllerHome: input.controllerHome }, { requirementId: recorded.requirementId, work: recorded });
+  return { workId: input.workId, reconciliation, receipt };
+}

package/src/runtime/control-plane/execution/execution-identity.ts

@@ -134,6 +134,53 @@ function gitPath(root: string, args: string[]): string | undefined {
   }
 }
 
+interface GitExecutionSnapshot {
+  topLevel?: string;
+  commonDirectory?: string;
+  branch?: string;
+  head?: string;
+}
+
+function resolvedGitPath(root: string, value: string | undefined): string | undefined {
+  if (!value) return undefined;
+  try {
+    return realpathSync(isAbsolute(value) ? value : resolve(root, value));
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Read the checkout identity in one Git child process on the normal committed
+ * path. This preserves the same fail-closed fields as the former six probes;
+ * unborn repositories fall back to the individual observations because HEAD is
+ * intentionally absent there.
+ */
+function gitExecutionSnapshot(root: string): GitExecutionSnapshot {
+  const combined = gitText(root, ['rev-parse', '--show-toplevel', '--git-common-dir', 'HEAD', '--abbrev-ref', 'HEAD']);
+  if (combined) {
+    const lines = combined.split('\n').map((line) => line.trim());
+    if (lines.length >= 4) {
+      return {
+        topLevel: resolvedGitPath(root, lines[0]),
+        commonDirectory: resolvedGitPath(root, lines[1]),
+        head: lines[2] || undefined,
+        branch: lines[3] && lines[3] !== 'HEAD' ? lines[3] : undefined,
+      };
+    }
+  }
+  // Rare unborn/failure fallback keeps legacy behavior rather than turning a
+  // missing HEAD into a false workspace identity failure.
+  const topLevel = gitPath(root, ['rev-parse', '--show-toplevel']);
+  const commonDirectory = gitPath(root, ['rev-parse', '--git-common-dir']);
+  return {
+    topLevel,
+    commonDirectory,
+    branch: topLevel ? gitText(topLevel, ['branch', '--show-current']) : undefined,
+    head: topLevel ? gitText(topLevel, ['rev-parse', '--verify', 'HEAD']) : undefined,
+  };
+}
+
 export function classifyGitCommonDirectoryDrift(input: {
   repoId: string;
   checkoutId: string;
@@ -304,18 +351,15 @@ export function assertExecutionIdentity(input: {
         actual: resolvedCwd,
       });
     }
-    const gitTopLevel = gitPath(resolvedCwd, ['rev-parse', '--show-toplevel']);
-    const gitCommonDirectory = gitPath(resolvedCwd, ['rev-parse', '--git-common-dir']);
-    const currentBranch = gitTopLevel ? gitText(gitTopLevel, ['branch', '--show-current']) : undefined;
-    const currentHead = gitTopLevel ? gitText(gitTopLevel, ['rev-parse', '--verify', 'HEAD']) : undefined;
+    const gitSnapshot = gitExecutionSnapshot(resolvedCwd);
     return Object.freeze({
       ...identity,
       canonicalRoot: workspaceRoot,
       resolvedCwd,
-      gitTopLevel,
-      gitCommonDirectory,
-      currentBranch,
-      currentHead,
+      gitTopLevel: gitSnapshot.topLevel,
+      gitCommonDirectory: gitSnapshot.commonDirectory,
+      currentBranch: gitSnapshot.branch,
+      currentHead: gitSnapshot.head,
     });
   }
 
@@ -377,7 +421,8 @@ export function assertExecutionIdentity(input: {
     });
   }
 
-  const gitTopLevel = gitPath(resolvedCwd, ['rev-parse', '--show-toplevel']);
+  const gitSnapshot = gitExecutionSnapshot(resolvedCwd);
+  const gitTopLevel = gitSnapshot.topLevel;
   if (!gitTopLevel || !samePath(gitTopLevel, registeredRoot)) {
     fail('GIT_TOPLEVEL_MISMATCH', 'Git top-level differs from expected checkout root', {
       repoId: identity.repositoryId,
@@ -387,9 +432,15 @@ export function assertExecutionIdentity(input: {
     });
   }
 
-  const gitCommonDirectory = gitPath(resolvedCwd, ['rev-parse', '--git-common-dir']);
-  const registeredCommonDirectory = gitPath(registeredRoot, ['rev-parse', '--git-common-dir']);
-  const repositoryCommonDirectory = gitPath(registered.canonicalRoot, ['rev-parse', '--git-common-dir']);
+  const gitCommonDirectory = gitSnapshot.commonDirectory;
+  // Once the observed top-level is proven equal to registeredRoot, querying the
+  // same checkout again cannot add identity evidence. Only a linked worktree
+  // needs one extra canonical-repository common-dir observation.
+  const registeredCommonDirectory = gitCommonDirectory;
+  const repositoryRoot = realpathOrFail(registered.canonicalRoot, 'WORKTREE_MISSING', 'repository canonical root');
+  const repositoryCommonDirectory = samePath(repositoryRoot, registeredRoot)
+    ? gitCommonDirectory
+    : gitPath(repositoryRoot, ['rev-parse', '--git-common-dir']);
   const commonDirectoryDrift = classifyGitCommonDirectoryDrift({
     repoId: identity.repositoryId,
     checkoutId: identity.checkoutId,
@@ -423,8 +474,8 @@ export function assertExecutionIdentity(input: {
     });
   }
 
-  const currentBranch = gitText(registeredRoot, ['branch', '--show-current']);
-  const currentHead = gitText(registeredRoot, ['rev-parse', '--verify', 'HEAD']);
+  const currentBranch = gitSnapshot.branch;
+  const currentHead = gitSnapshot.head;
   if (identity.branch && currentBranch !== identity.branch) {
     fail('WORK_HANDLE_BRANCH_CHANGED', 'branch drifted from execution identity', {
       repoId: identity.repositoryId,