ultra-builder-pro-cli 0.20.0 → 0.21.1

package/orchestrator/session-runner.cjs

@@ -16,7 +16,10 @@ const { randomUUID } = require('node:crypto');
 
 const ops = require('../mcp-server/lib/state-ops.cjs');
 const workflows = require('../mcp-server/lib/workflow-state.cjs');
-const skillMiner = require('./skill-miner.cjs');
+const contextSpine = require('../mcp-server/lib/context-spine.cjs');
+const runtimePaths = require('../mcp-server/lib/runtime-paths.cjs');
+const gitBootstrap = require('../mcp-server/lib/git-bootstrap.cjs');
+const closeJournal = require('./session-close-journal.cjs');
 
 const EXPECTED_EXECUTION_GATE_CODES = new Set([
   'TASK_EXECUTION_CONTRACT_INCOMPLETE',
@@ -25,6 +28,22 @@ const EXPECTED_EXECUTION_GATE_CODES = new Set([
   'WORKFLOW_PLAN_NOT_COMPLETED',
   'WORKFLOW_PLAN_TASK_SET_STALE',
   'WORKFLOW_PLAN_TASK_CONTRACT_STALE',
+  'WORKFLOW_PLAN_CONTEXT_STALE',
+  'WORKFLOW_IMPLEMENTATION_CONTEXT_REQUIRED',
+  'WORKFLOW_IMPLEMENTATION_CONTEXT_STALE',
+  'ADMISSION_DENIED',
+  'ACTIVE_SESSION_LEASE_CONFLICT',
+  'SESSION_CLOSE_PENDING',
+  'CIRCUIT_TRIPPED',
+  'LEGACY_RUNTIME_CONFLICT',
+  'LEGACY_RUNTIME_MIGRATION_FAILED',
+  'RUNTIME_ADMISSION_ROLLBACK_FAILED',
+  'RUNTIME_STATE_CONFLICT',
+  'RUNTIME_STATE_MIGRATION_FAILED',
+  'RUNTIME_STATE_NOT_QUIESCENT',
+  'SESSION_CLOSE_JOURNAL_INVALID',
+  'SESSION_CLOSE_JOURNAL_CONFLICT',
+  'SESSION_CLOSE_CONFLICT',
 ]);
 
 class SessionRunnerError extends Error {
@@ -36,14 +55,103 @@ class SessionRunnerError extends Error {
   }
 }
 
+function findExpectedExecutionGate(error) {
+  const seen = new Set();
+  let current = error;
+  while (current && (typeof current === 'object' || typeof current === 'function')) {
+    if (seen.has(current)) return null;
+    seen.add(current);
+    if (EXPECTED_EXECUTION_GATE_CODES.has(current.code)) return current;
+    current = current.cause;
+  }
+  return null;
+}
+
 function isExpectedExecutionGate(error) {
-  return Boolean(error && EXPECTED_EXECUTION_GATE_CODES.has(error.code));
+  return Boolean(findExpectedExecutionGate(error));
+}
+
+function assertSessionId(sid) {
+  if (typeof sid !== 'string'
+      || sid.length === 0
+      || sid.length > 128
+      || sid === '.'
+      || sid === '..'
+      || path.isAbsolute(sid)
+      || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(sid)) {
+    throw new SessionRunnerError(
+      'WORKTREE_SCOPE_INVALID',
+      `session id is not a safe worktree leaf: ${String(sid)}`,
+    );
+  }
+  return sid;
+}
+
+function assertManagedWorktreeRoot(repoRoot, { validateRuntimeTree = true } = {}) {
+  const managedBase = runtimePaths.validateProjectLayout(
+    repoRoot, { env: {}, validateRuntimeTree },
+  ).worktreesDir;
+  const stat = fs.lstatSync(managedBase, { throwIfNoEntry: false });
+  if (stat && (stat.isSymbolicLink() || !stat.isDirectory())) {
+    throw new SessionRunnerError(
+      'WORKTREE_SCOPE_INVALID',
+      `managed worktree root must be a real directory: ${managedBase}`,
+    );
+  }
+  return managedBase;
+}
+
+function assertManagedWorktreePath(repoRoot, candidate, {
+  sid = null,
+  validateRuntimeTree = true,
+} = {}) {
+  if (!repoRoot || typeof candidate !== 'string' || !candidate) {
+    throw new SessionRunnerError(
+      'WORKTREE_SCOPE_INVALID',
+      'repoRoot and a managed worktree path are required',
+    );
+  }
+  const expectedSid = assertSessionId(sid === null ? path.basename(candidate) : sid);
+  const managedBase = assertManagedWorktreeRoot(repoRoot, { validateRuntimeTree });
+  if (String(candidate).split(/[\\/]+/).includes('..')) {
+    throw new SessionRunnerError(
+      'WORKTREE_SCOPE_INVALID',
+      `worktree path may not contain traversal segments: ${candidate}`,
+    );
+  }
+  const resolved = path.resolve(repoRoot, candidate);
+  if (path.basename(resolved) !== expectedSid) {
+    throw new SessionRunnerError(
+      'WORKTREE_SCOPE_INVALID',
+      `worktree path must be the exact managed child for session ${expectedSid}: ${candidate}`,
+    );
+  }
+  const candidateStat = fs.lstatSync(resolved, { throwIfNoEntry: false });
+  if (candidateStat && (candidateStat.isSymbolicLink() || !candidateStat.isDirectory())) {
+    throw new SessionRunnerError(
+      'WORKTREE_SCOPE_INVALID',
+      `managed worktree path must be a real directory: ${candidate}`,
+    );
+  }
+  const physicalManaged = physicalCandidate(managedBase);
+  const physicalResolved = physicalCandidate(resolved);
+  const physicalRelative = path.relative(physicalManaged, physicalResolved);
+  if (physicalRelative !== expectedSid) {
+    throw new SessionRunnerError(
+      'WORKTREE_SCOPE_INVALID',
+      `worktree path must resolve to the exact managed child ${expectedSid}: ${candidate}`,
+    );
+  }
+  return resolved;
 }
 
 function gitWorktreeAdd(repoRoot, worktreePath, ref = 'HEAD') {
-  fs.mkdirSync(path.dirname(worktreePath), { recursive: true });
+  const managedPath = assertManagedWorktreePath(repoRoot, worktreePath, {
+    sid: path.basename(worktreePath),
+  });
+  fs.mkdirSync(path.dirname(managedPath), { recursive: true });
   try {
-    execFileSync('git', ['worktree', 'add', '--detach', worktreePath, ref], {
+    execFileSync('git', ['worktree', 'add', '--detach', managedPath, ref], {
       cwd: repoRoot, stdio: 'pipe',
     });
   } catch (err) {
@@ -52,23 +160,137 @@ function gitWorktreeAdd(repoRoot, worktreePath, ref = 'HEAD') {
 }
 
 function gitWorktreeRemove(repoRoot, worktreePath) {
+  const managedPath = assertManagedWorktreePath(repoRoot, worktreePath, {
+    sid: path.basename(worktreePath),
+    validateRuntimeTree: false,
+  });
   try {
-    execFileSync('git', ['worktree', 'remove', '--force', worktreePath], {
+    execFileSync('git', ['worktree', 'remove', managedPath], {
       cwd: repoRoot, stdio: 'pipe',
     });
-  } catch (_err) {
-    // worktree may already be detached; fall through to fs removal
+  } catch (error) {
+    throw new SessionRunnerError(
+      'WORKTREE_FAILED',
+      `git worktree remove failed: ${
+        error.stderr ? error.stderr.toString().trim() : error.message
+      }`,
+      { cause: error },
+    );
   }
-  if (fs.existsSync(worktreePath)) {
-    fs.rmSync(worktreePath, { recursive: true, force: true });
+}
+
+function gitWorktreeRegistry(repoRoot) {
+  try {
+    const output = execFileSync('git', ['worktree', 'list', '--porcelain'], {
+      cwd: repoRoot,
+      encoding: 'utf8',
+      stdio: 'pipe',
+    });
+    return new Set(output
+      .split(/\r?\n/)
+      .filter((line) => line.startsWith('worktree '))
+      .map((line) => physicalCandidate(line.slice('worktree '.length))));
+  } catch (error) {
+    throw new SessionRunnerError(
+      'WORKTREE_FAILED',
+      `git worktree registry read failed: ${
+        error.stderr ? error.stderr.toString().trim() : error.message
+      }`,
+      { cause: error },
+    );
   }
 }
 
+function removeExactPrunableWorktreeRegistry(repoRoot, managedPath) {
+  let reported;
+  try {
+    reported = execFileSync('git', ['rev-parse', '--git-common-dir'], {
+      cwd: repoRoot,
+      encoding: 'utf8',
+      stdio: 'pipe',
+    }).trim();
+  } catch (error) {
+    throw new SessionRunnerError(
+      'WORKTREE_FAILED',
+      `cannot resolve Git common directory: ${
+        error.stderr ? error.stderr.toString().trim() : error.message
+      }`,
+      { cause: error },
+    );
+  }
+  const commonDir = fs.realpathSync(
+    path.isAbsolute(reported) ? reported : path.resolve(repoRoot, reported),
+  );
+  const registryRoot = path.join(commonDir, 'worktrees');
+  const rootStat = fs.lstatSync(registryRoot, { throwIfNoEntry: false });
+  if (!rootStat?.isDirectory() || rootStat.isSymbolicLink()) {
+    throw new SessionRunnerError(
+      'WORKTREE_FAILED',
+      `Git still registers ${managedPath}, but its exact worktree metadata root is unavailable`,
+    );
+  }
+  const expected = path.resolve(managedPath);
+  const matches = [];
+  for (const entry of fs.readdirSync(registryRoot, { withFileTypes: true })) {
+    if (!entry.isDirectory() || entry.isSymbolicLink()) continue;
+    const adminDir = path.join(registryRoot, entry.name);
+    const gitdirFile = path.join(adminDir, 'gitdir');
+    const gitdirStat = fs.lstatSync(gitdirFile, { throwIfNoEntry: false });
+    if (!gitdirStat?.isFile() || gitdirStat.isSymbolicLink()) continue;
+    const gitdir = fs.readFileSync(gitdirFile, 'utf8').trim();
+    if (!gitdir) continue;
+    const recorded = path.dirname(
+      path.isAbsolute(gitdir) ? path.resolve(gitdir) : path.resolve(adminDir, gitdir),
+    );
+    if (recorded === expected) matches.push(adminDir);
+  }
+  if (matches.length !== 1) {
+    throw new SessionRunnerError(
+      'WORKTREE_FAILED',
+      `cannot identify one exact Git registry entry for removed worktree ${managedPath}`,
+    );
+  }
+  fs.rmSync(matches[0], { recursive: true, force: false });
+}
+
+function reconcileRemovedWorktree(repoRoot, worktreePath, { sid } = {}) {
+  const managedPath = assertManagedWorktreePath(repoRoot, worktreePath, {
+    sid: sid || path.basename(worktreePath),
+    validateRuntimeTree: false,
+  });
+  const registryKey = physicalCandidate(managedPath);
+  let registry = gitWorktreeRegistry(repoRoot);
+  if (fs.existsSync(managedPath)) {
+    gitWorktreeRemove(repoRoot, managedPath);
+  } else if (registry.has(registryKey)) {
+    try {
+      execFileSync('git', ['worktree', 'remove', '--force', managedPath], {
+        cwd: repoRoot,
+        stdio: 'pipe',
+      });
+    } catch {
+      removeExactPrunableWorktreeRegistry(repoRoot, managedPath);
+    }
+  }
+  registry = gitWorktreeRegistry(repoRoot);
+  if (!fs.existsSync(managedPath) && registry.has(registryKey)) {
+    removeExactPrunableWorktreeRegistry(repoRoot, managedPath);
+    registry = gitWorktreeRegistry(repoRoot);
+  }
+  if (registry.has(registryKey)) {
+    throw new SessionRunnerError(
+      'WORKTREE_FAILED',
+      `Git still registers the managed worktree after removal: ${managedPath}`,
+    );
+  }
+  return managedPath;
+}
+
 function authorityLinkIsIgnored(worktreePath) {
   try {
     execFileSync(
       'git',
-      ['check-ignore', '--quiet', '--no-index', '--', '.ultra'],
+      ['check-ignore', '--quiet', '--no-index', '--', '.ultra/.runtime'],
       { cwd: worktreePath, stdio: 'ignore' },
     );
     return true;
@@ -125,7 +347,7 @@ function ensureAuthorityLinkIgnored(worktreePath) {
     fs.mkdirSync(path.dirname(excludePath), { recursive: true });
     fs.writeFileSync(
       excludePath,
-      `${prefix}${separator}# Ultra Builder Pro session authority\n.ultra\n`,
+      `${prefix}${separator}# Ultra Builder Pro shared session runtime\n/.ultra/.runtime\n`,
     );
     if (!authorityLinkIsIgnored(worktreePath)) {
       throw new Error('Git still does not ignore the session authority link');
@@ -137,17 +359,34 @@ function ensureAuthorityLinkIgnored(worktreePath) {
     } catch { /* best effort */ }
     throw new SessionRunnerError(
       'WORKTREE_AUTHORITY_NOT_IGNORED',
-      `cannot establish a safe local ignore rule for .ultra: ${error.message}`,
+      `cannot establish a safe local ignore rule for .ultra/.runtime: ${error.message}`,
       { cause: error },
     );
   }
   return { changed: true, path: excludePath };
 }
 
-function linkAuthorityIntoWorktree(repoRoot, worktreePath) {
-  const authorityDir = path.resolve(repoRoot, '.ultra');
-  const stateDbPath = path.join(authorityDir, 'state.db');
-  const linkPath = path.join(worktreePath, '.ultra');
+function linkAuthorityIntoWorktree(repoRoot, worktreePath, {
+  authority: preadmittedAuthority = null,
+} = {}) {
+  let authority = preadmittedAuthority;
+  if (!authority) {
+    try {
+      authority = runtimePaths.ensureRuntimeState(repoRoot, {
+        admitStorageBoundary: () => gitBootstrap.ensureExistingProjectStorageBoundary(repoRoot),
+      });
+    } catch (error) {
+      throw new SessionRunnerError(
+        'WORKTREE_AUTHORITY_NOT_IGNORED',
+        `cannot establish the project Ultra storage boundary: ${error.message}`,
+        { cause: error },
+      );
+    }
+  }
+  const authorityDir = authority.runtimeDir;
+  const stateDbPath = authority.stateDbPath;
+  const worktreeUltraDir = path.join(worktreePath, '.ultra');
+  const linkPath = path.join(worktreeUltraDir, '.runtime');
   if (!fs.existsSync(stateDbPath)) {
     throw new SessionRunnerError(
       'WORKTREE_AUTHORITY_MISSING',
@@ -156,20 +395,31 @@ function linkAuthorityIntoWorktree(repoRoot, worktreePath) {
   }
   ensureAuthorityLinkIgnored(worktreePath);
   try {
+    fs.mkdirSync(worktreeUltraDir, { recursive: true });
     if (fs.existsSync(linkPath) || fs.lstatSync(linkPath, { throwIfNoEntry: false })) {
       throw new SessionRunnerError(
         'WORKTREE_AUTHORITY_CONFLICT',
-        `worktree already contains an .ultra entry at ${linkPath}`,
+        `worktree already contains an .ultra/.runtime entry at ${linkPath}`,
       );
     }
     fs.symlinkSync(
-      process.platform === 'win32' ? authorityDir : path.relative(worktreePath, authorityDir),
+      process.platform === 'win32' ? authorityDir : path.relative(worktreeUltraDir, authorityDir),
       linkPath,
       process.platform === 'win32' ? 'junction' : 'dir',
     );
     if (fs.realpathSync(path.join(linkPath, 'state.db')) !== fs.realpathSync(stateDbPath)) {
       throw new Error('linked state.db does not resolve to the central authority');
     }
+    try {
+      gitBootstrap.assertUltraStorageBoundary(worktreePath);
+    } catch (error) {
+      fs.rmSync(linkPath, { force: true });
+      throw new SessionRunnerError(
+        'WORKTREE_STORAGE_BOUNDARY_STALE',
+        `selected worktree revision does not preserve Ultra semantic artifacts: ${error.message}`,
+        { cause: error },
+      );
+    }
     return { authorityDir, stateDbPath, linkPath };
   } catch (error) {
     throw error instanceof SessionRunnerError ? error : new SessionRunnerError(
@@ -181,14 +431,17 @@ function linkAuthorityIntoWorktree(repoRoot, worktreePath) {
 }
 
 function worktreeRemovalBlocker(repoRoot, worktreePath) {
-  if (!fs.existsSync(worktreePath)) return null;
+  const managedPath = assertManagedWorktreePath(repoRoot, worktreePath, {
+    sid: path.basename(worktreePath),
+  });
+  if (!fs.existsSync(managedPath)) return null;
   try {
     const status = execFileSync('git', ['status', '--porcelain=v1'], {
-      cwd: worktreePath, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'],
+      cwd: managedPath, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'],
     }).trim();
     if (status) return 'worktree contains uncommitted changes';
     const sessionHead = execFileSync('git', ['rev-parse', 'HEAD'], {
-      cwd: worktreePath, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'],
+      cwd: managedPath, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'],
     }).trim();
     const repositoryHead = execFileSync('git', ['rev-parse', 'HEAD'], {
       cwd: repoRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'],
@@ -253,15 +506,28 @@ function changeTaskIntegrationBlocker(db, task, worktreePath) {
   return null;
 }
 
+function physicalCandidate(candidate) {
+  let existing = candidate;
+  while (!fs.lstatSync(existing, { throwIfNoEntry: false })) {
+    const parent = path.dirname(existing);
+    if (parent === existing) break;
+    existing = parent;
+  }
+  const physicalExisting = fs.realpathSync(existing);
+  return path.resolve(physicalExisting, path.relative(existing, candidate));
+}
+
 function resolveWorktreeBase(repoRoot, requestedBase) {
-  const managedBase = path.resolve(repoRoot, '.ultra', 'worktrees');
+  const managedBase = runtimePaths.pathsFor(repoRoot).worktreesDir;
   const resolved = requestedBase
     ? path.resolve(repoRoot, requestedBase)
     : managedBase;
-  if (resolved !== managedBase && !resolved.startsWith(`${managedBase}${path.sep}`)) {
+  const physicalManaged = physicalCandidate(managedBase);
+  const physicalResolved = physicalCandidate(resolved);
+  if (resolved !== path.resolve(managedBase) || physicalResolved !== physicalManaged) {
     throw new SessionRunnerError(
       'WORKTREE_SCOPE_INVALID',
-      `worktree_base must stay inside ${managedBase}`,
+      `worktree_base must be the canonical managed root ${managedBase}`,
     );
   }
   return resolved;
@@ -295,9 +561,126 @@ function assertSessionTaskReady(db, repoRoot, taskId) {
     );
   }
   workflows.assertCurrentPlan(db, task.change_id, repoRoot);
+  const implementationContext = contextSpine.validateContextSnapshot(db, {
+    change_id: task.change_id,
+    task_id: task.id,
+    role: 'implement',
+    gate: 'implementation',
+  }, {
+    rootDir: repoRoot,
+    require_current_checkout: true,
+  });
+  if (!implementationContext.snapshot) {
+    throw new workflows.WorkflowStateError(
+      'WORKFLOW_IMPLEMENTATION_CONTEXT_REQUIRED',
+      `task ${task.id} requires a ready implementation Context before session admission`,
+      { blockers: implementationContext.blockers },
+    );
+  }
+  if (implementationContext.blockers.length > 0) {
+    throw new workflows.WorkflowStateError(
+      'WORKFLOW_IMPLEMENTATION_CONTEXT_STALE',
+      `task ${task.id} implementation Context is stale`,
+      { blockers: implementationContext.blockers },
+    );
+  }
+  const planningContext = contextSpine.validateContextSnapshot(db, {
+    change_id: task.change_id,
+    task_id: null,
+    role: 'plan',
+    gate: 'planning',
+  }, {
+    rootDir: repoRoot,
+    require_current_checkout: true,
+  });
+  if (!planningContext.snapshot || planningContext.blockers.length > 0) {
+    throw new workflows.WorkflowStateError(
+      'WORKFLOW_PLAN_CONTEXT_STALE',
+      `change ${task.change_id} planning Context is stale at session admission`,
+      { blockers: planningContext.blockers },
+    );
+  }
   return task;
 }
 
+function admissionCheck(db, repoRoot, taskId, options = {}) {
+  assertSessionTaskReady(db, repoRoot, taskId);
+  const pendingClose = closeJournal.findForTask(repoRoot, taskId);
+  if (pendingClose) {
+    return {
+      can_spawn: false,
+      conflict: {
+        sid: pendingClose.sid,
+        status: 'closing',
+        heartbeat_age_ms: 0,
+      },
+      recommended_action: 'recover_close',
+    };
+  }
+  return ops.admissionCheck(db, taskId, options);
+}
+
+function startSessionProcess({
+  db,
+  repoRoot,
+  sid,
+  command,
+  args = [],
+  env = {},
+  stdio = 'ignore',
+  authority = null,
+}) {
+  if (!db || !repoRoot || !sid || typeof command !== 'string' || !command.trim()) {
+    throw new SessionRunnerError(
+      'VALIDATION_ERROR',
+      'db, repoRoot, sid, and an executable command are required',
+    );
+  }
+  if (!Array.isArray(args)) {
+    throw new SessionRunnerError('VALIDATION_ERROR', 'session process args must be an array');
+  }
+  const session = ops.readSession(db, sid);
+  if (!session) throw new SessionRunnerError('SESSION_NOT_FOUND', `session ${sid} not found`);
+  if (session.status !== 'running' || session.pid !== null) {
+    throw new SessionRunnerError(
+      'SESSION_NOT_STARTABLE',
+      `session ${sid} cannot start from status=${session.status}, pid=${String(session.pid)}`,
+    );
+  }
+  const worktreePath = assertManagedWorktreePath(repoRoot, session.worktree_path, { sid });
+  const resolvedAuthority = authority || runtimePaths.ensureRuntimeState(repoRoot, {
+    admitStorageBoundary: () => gitBootstrap.ensureExistingProjectStorageBoundary(repoRoot),
+  });
+  let proc;
+  try {
+    proc = spawn(command, args, {
+      cwd: worktreePath,
+      env: {
+        ...process.env,
+        ...env,
+        UBP_SESSION_ID: sid,
+        UBP_TASK_ID: session.task_id,
+        UBP_RUNTIME: session.runtime,
+        UBP_WORKTREE: worktreePath,
+        UBP_ARTIFACT_DIR: session.artifact_dir,
+        UBP_DB_PATH: resolvedAuthority.stateDbPath,
+        UBP_ROOT_DIR: worktreePath,
+        UBP_AUTHORITY_ROOT: repoRoot,
+      },
+      stdio,
+      detached: false,
+    });
+    if (Number.isInteger(proc.pid)) {
+      ops.updateSession(db, sid, { pid: proc.pid });
+    }
+    return proc;
+  } catch (error) {
+    try { if (proc && !proc.killed) proc.kill('SIGTERM'); } catch { /* best effort */ }
+    try { ops.updateSession(db, sid, { status: 'crashed' }); } catch { /* preserve original error */ }
+    throw error;
+  }
+}
+
 function spawnSession({
   db,
   repoRoot,
@@ -311,6 +694,9 @@ function spawnSession({
   worktreeRef = 'HEAD',
   worktree_base = null,
   lease_seconds = 1800,
+  mark_task_started = false,
+  takeover_timeout_ms = 5000,
+  takeover_poll_ms = 25,
 }) {
   if (!db) throw new SessionRunnerError('VALIDATION_ERROR', 'db handle required');
   if (!repoRoot) throw new SessionRunnerError('VALIDATION_ERROR', 'repoRoot required');
@@ -332,6 +718,25 @@ function spawnSession({
   // Validate workflow authority before takeover can terminate the prior worker
   // or any filesystem mutation creates a new worktree.
   assertSessionTaskReady(db, repoRoot, task_id);
+  let authority;
+  try {
+    authority = runtimePaths.ensureRuntimeState(repoRoot, {
+      admitStorageBoundary: () => gitBootstrap.ensureExistingProjectStorageBoundary(repoRoot),
+    });
+  } catch (error) {
+    throw new SessionRunnerError(
+      'WORKTREE_AUTHORITY_NOT_IGNORED',
+      `cannot establish the project Ultra storage boundary: ${error.message}`,
+      { cause: error },
+    );
+  }
+  const pendingClose = closeJournal.findForTask(repoRoot, task_id);
+  if (pendingClose) {
+    throw new SessionRunnerError(
+      'SESSION_CLOSE_PENDING',
+      `task ${task_id} has an unfinished close intent for session ${pendingClose.sid}; recover it before spawning or taking over`,
+    );
+  }
   if (!verdict.can_spawn && !takeover) {
     const err = new SessionRunnerError(
       'ADMISSION_DENIED',
@@ -352,6 +757,15 @@ function spawnSession({
           );
         }
       }
+      if (!waitForProcessExit(priorSession.pid, {
+        timeoutMs: takeover_timeout_ms,
+        pollMs: takeover_poll_ms,
+      })) {
+        throw new SessionRunnerError(
+          'TAKEOVER_FAILED',
+          `prior session ${verdict.conflict.sid} process ${priorSession.pid} did not exit; its lease remains authoritative`,
+        );
+      }
     }
     ops.updateSession(db, verdict.conflict.sid, { status: 'crashed' });
   }
@@ -359,61 +773,78 @@ function spawnSession({
   // 2. Mint sid + paths
   const sid = mintSessionId();
   const worktree_path = path.join(worktreeBase, sid);
-  const artifact_dir = path.join(repoRoot, '.ultra', 'sessions', sid);
+  const artifact_dir = path.join(runtimePaths.pathsFor(repoRoot).sessionsDir, sid);
 
   // 3. Git worktree (throws WORKTREE_FAILED on failure)
   gitWorktreeAdd(repoRoot, worktree_path, worktreeRef);
-  let authority;
   try {
-    authority = linkAuthorityIntoWorktree(repoRoot, worktree_path);
+    authority = linkAuthorityIntoWorktree(repoRoot, worktree_path, { authority });
     fs.mkdirSync(artifact_dir, { recursive: true });
   } catch (error) {
+    try {
+      fs.rmSync(path.join(worktree_path, '.ultra', '.runtime'), { force: true });
+    } catch { /* best effort */ }
     gitWorktreeRemove(repoRoot, worktree_path);
     throw error;
   }
 
-  // 4. Spawn child process (optional — the active host may consume the worktree)
-  let proc = null;
-  if (command) {
-    proc = spawn(command, args, {
-      cwd: worktree_path,
-      env: {
-        ...process.env,
-        ...env,
-        UBP_SESSION_ID: sid,
-        UBP_TASK_ID: task_id,
-        UBP_RUNTIME: runtime,
-        UBP_WORKTREE: worktree_path,
-        UBP_ARTIFACT_DIR: artifact_dir,
-        UBP_DB_PATH: authority.stateDbPath,
-        UBP_ROOT_DIR: worktree_path,
-        UBP_AUTHORITY_ROOT: repoRoot,
-      },
-      stdio,
-      detached: false,
-    });
-  }
-
-  // 5. Write session record
+  // 4. Persist the task/worktree binding before any worker can run a hook or
+  // resolve UBP_DB_PATH. This is the anti-spoof authority hand-off.
   let session;
   try {
     session = ops.createSession(db, {
       sid,
       task_id,
       runtime,
-      pid: proc ? proc.pid : null,
+      pid: null,
       worktree_path,
       artifact_dir,
       lease_seconds,
     });
   } catch (err) {
-    // state.db insert failed — roll back worktree + child
-    if (proc && !proc.killed) { try { proc.kill('SIGTERM'); } catch (_) { /* ignore */ } }
+    // state.db insert failed — no worker has started; roll back the worktree.
     gitWorktreeRemove(repoRoot, worktree_path);
     try { fs.rmSync(artifact_dir, { recursive: true, force: true }); } catch (_) { /* ignore */ }
     throw err;
   }
 
+  // Automated dispatch must publish the running task state before the worker
+  // can observe or complete it. Manual host-owned sessions retain the caller's
+  // task state unless they explicitly opt into this ordering contract.
+  try {
+    if (mark_task_started && ops.readTask(db, task_id)?.status === 'pending') {
+      ops.updateTaskStatus(db, task_id, 'in_progress');
+    }
+  } catch (error) {
+    try { ops.updateSession(db, sid, { status: 'crashed' }); } catch { /* preserve original error */ }
+    try { gitWorktreeRemove(repoRoot, worktree_path); } catch { /* recovery keeps evidence */ }
+    try { fs.rmSync(artifact_dir, { recursive: true, force: true }); } catch { /* ignore */ }
+    throw error;
+  }
+
+  // 5. Spawn child process only after the durable binding exists. The active
+  // host may also consume the returned worktree without a child process.
+  let proc = null;
+  try {
+    if (command) {
+      proc = startSessionProcess({
+        db,
+        repoRoot,
+        sid,
+        command,
+        args,
+        env,
+        stdio,
+        authority,
+      });
+      session = ops.readSession(db, sid);
+    }
+  } catch (error) {
+    ops.updateSession(db, sid, { status: 'crashed' });
+    try { gitWorktreeRemove(repoRoot, worktree_path); } catch { /* recovery keeps evidence */ }
+    throw error;
+  }
+
   return {
     sid,
     worktree_path,
@@ -425,6 +856,48 @@ function spawnSession({
   };
 }
 
+function processIsExecuting(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+  } catch (error) {
+    if (error.code === 'ESRCH') return false;
+    if (error.code !== 'EPERM') throw error;
+  }
+  try {
+    const state = execFileSync('ps', ['-o', 'stat=', '-p', String(pid)], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    return Boolean(state) && !state.startsWith('Z');
+  } catch {
+    // A failed ps lookup after signal 0 normally means the process vanished.
+    try {
+      process.kill(pid, 0);
+      return true;
+    } catch (error) {
+      return error.code !== 'ESRCH';
+    }
+  }
+}
+
+function waitForProcessExit(pid, {
+  timeoutMs = 5000,
+  pollMs = 25,
+} = {}) {
+  const deadline = Date.now() + timeoutMs;
+  while (processIsExecuting(pid)) {
+    if (Date.now() >= deadline) return false;
+    Atomics.wait(
+      new Int32Array(new SharedArrayBuffer(4)),
+      0,
+      0,
+      Math.min(pollMs, Math.max(1, deadline - Date.now())),
+    );
+  }
+  return true;
+}
+
 function closeSession({
   db,
   repoRoot,
@@ -433,34 +906,129 @@ function closeSession({
   status = 'completed',
   remove_worktree = false,
   kill_signal = 'SIGTERM',
-  mineSkill = false,
-  skillsRoot = null,
   autoMerge = false,
   mergeBaseBranch = 'main',
+  kill_timeout_ms = 5000,
+  kill_poll_ms = 25,
 } = {}) {
   if (!db || !sid) throw new SessionRunnerError('VALIDATION_ERROR', 'db + sid required');
+  if (!closeJournal.TERMINAL_STATUSES.has(status)) {
+    throw new SessionRunnerError(
+      'VALIDATION_ERROR',
+      `session close status must be completed or crashed, got ${String(status)}`,
+    );
+  }
   const session = ops.readSession(db, sid);
   if (!session) {
     throw new SessionRunnerError('SESSION_NOT_FOUND', `session ${sid} not found`);
   }
-  if (remove_worktree && !autoMerge) {
-    const blocker = worktreeRemovalBlocker(repoRoot, session.worktree_path);
-    if (blocker) {
+  if (closeJournal.TERMINAL_STATUSES.has(session.status)) {
+    if (session.status !== status) {
       throw new SessionRunnerError(
-        'WORKTREE_NOT_INTEGRATED',
-        `refusing to remove ${session.worktree_path}: ${blocker}`,
+        'SESSION_TERMINAL_CONFLICT',
+        `session ${sid} is already ${session.status} and cannot be closed as ${status}`,
       );
     }
+    // A terminal row may contain a legacy PID that has since been reused by an
+    // unrelated process. Terminal authority is idempotent: never signal that
+    // PID, and clear it before reconciling any durable close intent.
+    if (session.pid !== null) ops.updateSession(db, sid, { pid: null });
+    const intent = repoRoot ? closeJournal.read(repoRoot, sid) : null;
+    if (intent) {
+      if (intent.requested_status !== status
+          || intent.task_id !== session.task_id
+          || path.resolve(intent.worktree_path) !== path.resolve(session.worktree_path)) {
+        throw new SessionRunnerError(
+          'SESSION_CLOSE_JOURNAL_CONFLICT',
+          `session ${sid} terminal state conflicts with its durable close intent`,
+        );
+      }
+    }
+    if ((intent || remove_worktree) && repoRoot && session.worktree_path) {
+      assertManagedWorktreePath(repoRoot, session.worktree_path, { sid: session.sid });
+      if (fs.existsSync(session.worktree_path)) {
+        const blocker = worktreeRemovalBlocker(repoRoot, session.worktree_path);
+        if (blocker) {
+          throw new SessionRunnerError(
+            'WORKTREE_NOT_INTEGRATED',
+            `refusing to remove ${session.worktree_path}: ${blocker}`,
+          );
+        }
+      }
+      if (!intent) {
+        closeJournal.prepare(repoRoot, {
+          sid,
+          task_id: session.task_id,
+          requested_status: status,
+          worktree_path: session.worktree_path,
+        });
+      }
+      try {
+        reconcileRemovedWorktree(repoRoot, session.worktree_path, { sid: session.sid });
+        closeJournal.update(repoRoot, sid, {
+          phase: 'worktree_removed',
+          error: null,
+        });
+        closeJournal.discard(repoRoot, sid);
+      } catch (error) {
+        closeJournal.update(repoRoot, sid, {
+          phase: 'recovery_failed',
+          error: error.message,
+        });
+        throw error;
+      }
+    }
+    return {
+      sid,
+      status,
+      worktree_preserved: Boolean(
+        session.worktree_path && fs.existsSync(session.worktree_path),
+      ),
+    };
   }
-  if (session.pid) {
-    try { process.kill(session.pid, kill_signal); }
-    catch (_) { /* already dead */ }
+  if ((remove_worktree || autoMerge) && session.worktree_path) {
+    assertManagedWorktreePath(repoRoot, session.worktree_path, { sid: session.sid });
+  }
+  let closeIntentPrepared = false;
+  if (remove_worktree && !autoMerge && repoRoot && session.worktree_path) {
+    closeJournal.prepare(repoRoot, {
+      sid,
+      task_id: session.task_id,
+      requested_status: status,
+      worktree_path: session.worktree_path,
+    });
+    closeIntentPrepared = true;
   }
-  // Phase 7.3 — opt-in skill mining reads durable task/session events. It
-  // cannot advance task or workflow state.
-  if (mineSkill && skillsRoot) {
-    try { skillMiner.mineSession(db, { sid, skillsRoot }); }
-    catch (err) { process.stderr.write(`skill-miner error: ${err.message}\n`); }
+  if (session.pid) {
+    try {
+      process.kill(session.pid, kill_signal);
+    } catch (error) {
+      if (error.code !== 'ESRCH') {
+        throw new SessionRunnerError(
+          'SESSION_TERMINATION_FAILED',
+          `cannot signal session ${sid} process ${session.pid}: ${error.message}`,
+          { cause: error },
+        );
+      }
+    }
+    if (!waitForProcessExit(session.pid, {
+      timeoutMs: kill_timeout_ms,
+      pollMs: kill_poll_ms,
+    })) {
+      if (closeIntentPrepared) {
+        closeJournal.update(repoRoot, sid, {
+          phase: 'worker_running',
+          error: `process ${session.pid} did not exit after ${kill_timeout_ms}ms`,
+        });
+      }
+      throw new SessionRunnerError(
+        'SESSION_TERMINATION_TIMEOUT',
+        `session ${sid} process ${session.pid} did not exit after ${kill_timeout_ms}ms; lease and worktree were preserved`,
+      );
+    }
+    // The owned worker is gone. Clear its reusable OS identifier even if a
+    // later merge or worktree gate keeps this close intent recoverable.
+    ops.updateSession(db, sid, { pid: null });
   }
   // Phase 8B.4 — opt-in auto-merge. Conflict preserves worktree for the
   // human; clean/no-op merges fall through to normal removal below.
@@ -505,9 +1073,40 @@ function closeSession({
       }
     }
   }
+  if (effectiveRemove && repoRoot && session.worktree_path) {
+    const blocker = worktreeRemovalBlocker(repoRoot, session.worktree_path);
+    if (blocker) {
+      throw new SessionRunnerError(
+        'WORKTREE_NOT_INTEGRATED',
+        `refusing to remove ${session.worktree_path}: ${blocker}`,
+      );
+    }
+    if (!closeIntentPrepared) {
+      closeJournal.prepare(repoRoot, {
+        sid,
+        task_id: session.task_id,
+        requested_status: status,
+        worktree_path: session.worktree_path,
+      });
+      closeIntentPrepared = true;
+    }
+    try {
+      gitWorktreeRemove(repoRoot, session.worktree_path);
+      closeJournal.update(repoRoot, sid, {
+        phase: 'worktree_removed',
+        error: null,
+      });
+    } catch (error) {
+      closeJournal.update(repoRoot, sid, {
+        phase: 'removal_failed',
+        error: error.message,
+      });
+      throw error;
+    }
+  }
   ops.updateSession(db, sid, { status });
   if (effectiveRemove && repoRoot && session.worktree_path) {
-    gitWorktreeRemove(repoRoot, session.worktree_path);
+    closeJournal.discard(repoRoot, sid);
   }
   const out = {
     sid,
@@ -533,21 +1132,32 @@ function attachHeartbeat(db, sid, { intervalMs = 30000 } = {}) {
 module.exports = {
   SessionRunnerError,
   EXPECTED_EXECUTION_GATE_CODES,
+  findExpectedExecutionGate,
   isExpectedExecutionGate,
   spawnSession,
+  startSessionProcess,
   closeSession,
   attachHeartbeat,
+  admissionCheck,
   assertSessionTaskReady,
   // exposed for tests
   _internal: {
     gitWorktreeAdd,
     gitWorktreeRemove,
+    gitWorktreeRegistry,
+    reconcileRemovedWorktree,
     mintSessionId,
     authorityLinkIsIgnored,
     ensureAuthorityLinkIgnored,
     linkAuthorityIntoWorktree,
     worktreeRemovalBlocker,
     changeTaskIntegrationBlocker,
+    processIsExecuting,
+    waitForProcessExit,
+    closeJournal,
     resolveWorktreeBase,
+    assertSessionId,
+    assertManagedWorktreeRoot,
+    assertManagedWorktreePath,
   },
 };