@moretea-labs/forge 1.5.0-rc.1

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

@@ -0,0 +1,53 @@
+export type RepositoryCommandValue = string | string[];
+
+export interface CanonicalRepositoryCommand {
+  readonly kind: 'shell' | 'argv';
+  /** The durable, audit, approval, and transport representation. */
+  readonly value: RepositoryCommandValue;
+  /** Present only for typed argv commands. */
+  readonly executable?: string;
+  /** Present only for typed argv commands. Never passed through a shell. */
+  readonly args?: readonly string[];
+  /** Present only for legacy shell-string commands. */
+  readonly shellCommand?: string;
+}
+
+const MAX_COMMAND_LENGTH = 32 * 1024;
+
+export function normalizeRepositoryCommand(input: unknown): CanonicalRepositoryCommand {
+  if (typeof input === 'string') {
+    const shellCommand = input.trim();
+    if (!shellCommand) throw new Error('COMMAND_INVALID: command is required');
+    if (shellCommand.includes('\0')) throw new Error('COMMAND_INVALID: command contains a null byte');
+    return { kind: 'shell', value: shellCommand, shellCommand };
+  }
+  if (!Array.isArray(input)) {
+    throw new Error('COMMAND_INVALID: command must be a shell string or argv string array');
+  }
+  if (input.length === 0) throw new Error('COMMAND_INVALID: argv must contain an executable');
+  const argv = input.map((part, index) => {
+    if (typeof part !== 'string') {
+      throw new Error(`COMMAND_INVALID: argv[${index}] must be a string`);
+    }
+    if (part.includes('\0')) throw new Error(`COMMAND_INVALID: argv[${index}] contains a null byte`);
+    return part;
+  });
+  if (!argv[0]?.trim()) throw new Error('COMMAND_INVALID: argv executable is required');
+  if (argv.reduce((total, part) => total + part.length, 0) > MAX_COMMAND_LENGTH) {
+    throw new Error(`COMMAND_INVALID: command exceeds ${MAX_COMMAND_LENGTH} characters`);
+  }
+  return {
+    kind: 'argv',
+    value: argv,
+    executable: argv[0],
+    args: argv.slice(1),
+  };
+}
+
+export function commandValue(command: CanonicalRepositoryCommand): RepositoryCommandValue {
+  return typeof command.value === 'string' ? command.value : [...command.value];
+}
+
+export function commandExecutable(command: CanonicalRepositoryCommand): string {
+  return command.kind === 'argv' ? command.executable! : command.shellCommand!;
+}

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

@@ -0,0 +1,264 @@
+import { existsSync, realpathSync, statSync } from 'fs';
+import { dirname, isAbsolute, join, relative, resolve } from 'path';
+import type { ExternalFilesystemGrant } from '../../runtime/safe-tooling/external-filesystem';
+import { externalFilesystemGrantExpired } from '../../runtime/safe-tooling/external-filesystem';
+import type { RepositoryRecord } from './types';
+import { normalizeRepositoryCommand, type CanonicalRepositoryCommand } from './command-normalization';
+
+const MAX_COMMAND_LENGTH = 32 * 1024;
+
+export type RepositoryCommandExternalPathOperation = 'external_read' | 'external_copy_into_workspace';
+
+export interface RepositoryCommandExternalPathUsage {
+  token: string;
+  canonicalPath: string;
+  operation: RepositoryCommandExternalPathOperation;
+  grantKey: string;
+  grantRoot: string;
+}
+
+function pathInside(root: string, candidate: string): boolean {
+  const rel = relative(root, candidate);
+  const parentPrefix = `..${process.platform === 'win32' ? '\\' : '/'}`;
+  return rel === '' || (rel !== '..' && !rel.startsWith(parentPrefix) && !isAbsolute(rel));
+}
+
+function nearestExistingPath(candidate: string): string | undefined {
+  let current = candidate;
+  while (!existsSync(current)) {
+    const parent = dirname(current);
+    if (parent === current) return undefined;
+    current = parent;
+  }
+  return current;
+}
+
+export function resolveRepositoryCommandCwd(
+  repository: RepositoryRecord,
+  requestedCwd: string | undefined,
+): { root: string; cwd: string; relativeCwd: string } {
+  if (!repository.enabled) throw new Error(`REPOSITORY_DISABLED: ${repository.repoId}`);
+  const root = realpathSync(repository.canonicalRoot);
+  const raw = requestedCwd?.trim() || '.';
+  if (raw.includes('\0')) throw new Error('COMMAND_SCOPE_DENIED: cwd contains a null byte');
+  const candidate = resolve(root, raw);
+  if (!existsSync(candidate)) throw new Error(`COMMAND_SCOPE_DENIED: cwd does not exist: ${raw}`);
+  const cwd = realpathSync(candidate);
+  if (!statSync(cwd).isDirectory()) throw new Error(`COMMAND_SCOPE_DENIED: cwd is not a directory: ${raw}`);
+  const relativeCwd = relative(root, cwd) || '.';
+  if (!pathInside(root, cwd)) throw new Error(`COMMAND_SCOPE_DENIED: cwd escapes repository root: ${raw}`);
+  return { root, cwd, relativeCwd };
+}
+
+export function assertRepositoryCommandAllowed(command: string): string {
+  const normalized = command.trim();
+  if (!normalized) throw new Error('COMMAND_INVALID: command is required');
+  if (normalized.length > MAX_COMMAND_LENGTH) {
+    throw new Error(`COMMAND_INVALID: command exceeds ${MAX_COMMAND_LENGTH} characters`);
+  }
+  if (normalized.includes('\0')) throw new Error('COMMAND_INVALID: command contains a null byte');
+
+  const denied: Array<[RegExp, string]> = [
+    [/\$\(|`/, 'nested command substitution is not allowed'],
+    [/(?:^|[;&|]\s*)(?:eval|source)\b|(?:^|[;&|]\s*)\.\s+[^/]/i, 'dynamic shell evaluation is not allowed'],
+    [/\b(?:bash|sh|zsh|fish|dash|cmd|powershell|pwsh)\b\s+(?:-[^\s]*c\b|\/c\b)/i, 'nested shell execution is not allowed'],
+    [/\b(?:python\d*|node|ruby|perl)\b\s+(?:-[ce]\b|--eval\b)/i, 'inline interpreter execution is not allowed'],
+    [/(?:^|[\s'"=])(?:\.\.(?:\/|\\)|~(?:\/|\\)|[A-Za-z]:[\\/])/, 'ambiguous parent/home/drive paths are not allowed; use repo-relative paths or an authorized absolute external path'],
+    [/(?:^|[;&|]\s*)cd(?:\s|$)/i, 'use the cwd argument instead of cd'],
+    [/\b(?:env|printenv)\b|\bgh\s+auth\s+token\b|\bgit\s+credential\b|\bsecurity\s+find-(?:generic|internet)-password\b/i, 'credential or environment inspection is not allowed'],
+    [/(?:^|[\s'"/])(?:\.ssh|\.aws|\.gnupg|Library\/Keychains|login\.keychain|\.config\/gh\/hosts\.yml)(?:[\s'"/]|$)/i, 'sensitive credential paths are not allowed'],
+    [/(?:^|[;&|]\s*)(?:curl|wget|scp|sftp|ftp|nc|ncat|netcat|socat|ssh)(?:\s|$)/i, 'direct network or exfiltration utilities are not allowed'],
+    [/\bgit\s+(?:--git-dir|--work-tree|-C)\b|\b(?:GIT_DIR|GIT_WORK_TREE)\s*=/i, 'Git repository scope overrides are not allowed'],
+    [/\bgit\s+config\b[^\n]*(?:--global|--system)\b/i, 'global or system Git configuration changes are not allowed'],
+  ];
+  for (const [pattern, reason] of denied) {
+    if (pattern.test(normalized)) throw new Error(`COMMAND_POLICY_DENIED: ${reason}`);
+  }
+  return normalized;
+}
+
+export function assertRepositoryCommandInputAllowed(input: unknown): CanonicalRepositoryCommand {
+  const command = normalizeRepositoryCommand(input);
+  if (command.kind === 'shell') {
+    assertRepositoryCommandAllowed(command.shellCommand!);
+    return command;
+  }
+  const executableName = command.executable!.split(/[\\/]/).at(-1)?.toLowerCase() ?? '';
+  const args = command.args ?? [];
+  const shellFlag = args.some((arg) => ['-c', '/c', '-Command'].includes(arg));
+  if (['bash', 'sh', 'zsh', 'fish', 'dash', 'cmd', 'powershell', 'pwsh'].includes(executableName) && shellFlag) {
+    throw new Error('COMMAND_POLICY_DENIED: nested shell execution is not allowed');
+  }
+  if (['node', 'nodejs', 'bun', 'deno', 'ruby', 'perl', 'python', 'python3'].includes(executableName)
+    && args.some((arg) => ['-c', '-e', '--eval'].includes(arg))) {
+    throw new Error('COMMAND_POLICY_DENIED: inline interpreter execution is not allowed');
+  }
+  if (args.some((arg) => /(?:^|[\\/])\.\.(?:[\\/]|$)|^(?:~|[A-Za-z]:[\\/])/.test(arg))) {
+    throw new Error('COMMAND_POLICY_DENIED: ambiguous parent/home/drive paths are not allowed; use repo-relative paths or an authorized absolute external path');
+  }
+  if (args.some((arg) => /(?:^|[\\/])(?:\.ssh|\.aws|\.gnupg|Library[\\/]Keychains|login\.keychain|\.config[\\/]gh[\\/]hosts\.yml)(?:[\\/]|$)/i.test(arg))) {
+    throw new Error('COMMAND_POLICY_DENIED: sensitive credential paths are not allowed');
+  }
+  if (executableName === 'git' && args.some((arg) => ['--git-dir', '--work-tree', '-C'].includes(arg))) {
+    throw new Error('COMMAND_POLICY_DENIED: Git repository scope overrides are not allowed');
+  }
+  if (executableName === 'git' && args[0] === 'config' && args.some((arg) => ['--global', '--system'].includes(arg))) {
+    throw new Error('COMMAND_POLICY_DENIED: global or system Git configuration changes are not allowed');
+  }
+  if (['env', 'printenv', 'curl', 'wget', 'scp', 'sftp', 'ftp', 'nc', 'ncat', 'netcat', 'socat', 'ssh'].includes(executableName)) {
+    throw new Error('COMMAND_POLICY_DENIED: credential or network inspection is not allowed');
+  }
+  return command;
+}
+
+function shellSegments(command: string): string[] {
+  const segments: string[] = [];
+  let current = '';
+  let quote: "'" | '"' | undefined;
+  let escaped = false;
+  const flush = () => {
+    const segment = current.trim();
+    if (segment) segments.push(segment);
+    current = '';
+  };
+  for (let index = 0; index < command.length; index += 1) {
+    const character = command[index]!;
+    if (escaped) { current += character; escaped = false; continue; }
+    if (character === '\\' && quote !== "'") { current += character; escaped = true; continue; }
+    if (quote) { current += character; if (character === quote) quote = undefined; continue; }
+    if (character === "'" || character === '"') { quote = character; current += character; continue; }
+    if (character === ';' || character === '|' || character === '&') {
+      flush();
+      if (command[index + 1] === character) index += 1;
+      continue;
+    }
+    current += character;
+  }
+  flush();
+  return segments;
+}
+
+function shellWords(segment: string): string[] {
+  return segment.match(/"(?:\\.|[^"])*"|'[^']*'|[^\s<>]+/g)?.map((word) => word.replace(/^['"]|['"]$/g, '')) ?? [];
+}
+
+function stripTrailingPunctuation(token: string): string {
+  return token.replace(/[,*?]+$/g, '');
+}
+
+function sensitivePathDenied(canonicalPath: string): boolean {
+  const lower = canonicalPath.toLowerCase();
+  return [
+    '/.ssh',
+    '/.gnupg',
+    '/library/keychains',
+    '/library/application support/google/chrome/default/cookies',
+    '/library/application support/google/chrome/default/network/cookies',
+    '/library/application support/firefox/profiles',
+    '/library/application support/1password',
+    '/library/group containers/2bua8c4s2c.com.1password',
+    '/.aws',
+    '/.config/gcloud',
+    '/.kube',
+    '/id_rsa',
+    '/id_dsa',
+    '/id_ecdsa',
+    '/id_ed25519',
+  ].some((fragment) => lower.includes(fragment));
+}
+
+function readOnlyProgram(program: string | undefined): boolean {
+  return Boolean(program && [
+    'pwd', 'ls', 'rg', 'grep', 'egrep', 'fgrep', 'cat', 'head', 'tail', 'wc',
+    'sort', 'uniq', 'cut', 'tr', 'stat', 'file', 'basename', 'dirname', 'printf',
+    'echo', 'du', 'df', 'realpath', 'readlink', 'jq', 'shasum', 'sha256sum', 'find',
+  ].includes(program.toLowerCase()));
+}
+
+function grantCoversPath(grant: ExternalFilesystemGrant, canonicalPath: string, operation: RepositoryCommandExternalPathOperation): boolean {
+  if (externalFilesystemGrantExpired(grant)) return false;
+  if (operation === 'external_read' && grant.mode !== 'read') return false;
+  if (operation === 'external_copy_into_workspace' && grant.mode !== 'copy_into_repo') return false;
+  const rel = relative(grant.canonicalRoot, canonicalPath);
+  return rel === '' || (rel !== '..' && !rel.startsWith(`..${process.platform === 'win32' ? '\\' : '/'}`) && !isAbsolute(rel));
+}
+
+function operationForToken(words: string[], index: number, external: string, cwd: string, root: string): RepositoryCommandExternalPathOperation | 'external_write' | 'unsupported' {
+  const program = words[0]?.toLowerCase();
+  if (!program) return 'unsupported';
+  if (program === 'cp' || program === 'install') {
+    const operands = words.slice(1).filter((word) => word && !word.startsWith('-'));
+    const operandIndex = operands.indexOf(external);
+    const destination = operands.at(-1);
+    if (operandIndex >= 0 && destination && external !== destination) {
+      const destinationPath = resolve(cwd, stripTrailingPunctuation(destination));
+      const existingDestination = nearestExistingPath(destinationPath);
+      const resolvedDestination = existingDestination ? realpathSync(existingDestination) : destinationPath;
+      return pathInside(root, resolvedDestination) ? 'external_copy_into_workspace' : 'external_write';
+    }
+    return 'external_write';
+  }
+  if (program === 'find' && words.some((word) => ['-delete', '-exec', '-execdir', '-ok', '-okdir'].includes(word))) return 'external_write';
+  if (readOnlyProgram(program)) return 'external_read';
+  if (index === 0) return 'unsupported';
+  return 'external_write';
+}
+
+export function assertCommandPathOperandsStayInRepository(
+  command: string | CanonicalRepositoryCommand,
+  cwd: string,
+  root: string,
+  externalGrants: ExternalFilesystemGrant[] = [],
+): RepositoryCommandExternalPathUsage[] {
+  const usages: RepositoryCommandExternalPathUsage[] = [];
+  const segments = typeof command === 'string'
+    ? shellSegments(command).map((segment) => ({ raw: segment, words: shellWords(segment) }))
+    : command.kind === 'shell'
+      ? shellSegments(command.shellCommand!).map((segment) => ({ raw: segment, words: shellWords(segment) }))
+      : [{ raw: '', words: [command.executable!, ...(command.args ?? [])] }];
+  for (const { raw: segment, words } of segments) {
+    const redirectionTarget = segment.match(/(?:^|\s)(?:\d?>?>)\s*(\/[^\s]+)/)?.[1];
+    if (redirectionTarget && !redirectionTarget.startsWith('/dev/null')) {
+      throw new Error(`COMMAND_SCOPE_DENIED: external writes are not allowed from repository commands: ${redirectionTarget}`);
+    }
+    for (let index = 0; index < words.length; index += 1) {
+      const token = words[index]!;
+      if (!token || token.startsWith('-') || /^[A-Za-z][A-Za-z0-9+.-]*:\/\//.test(token)) continue;
+      if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(token)) continue;
+      if (index === 0) continue;
+      const candidateToken = stripTrailingPunctuation(token);
+      const absoluteInput = candidateToken.startsWith('/');
+      if (!absoluteInput && !/[./\\*?]/.test(candidateToken) && !existsSync(join(cwd, candidateToken))) continue;
+      const candidate = absoluteInput ? resolve(candidateToken) : resolve(cwd, candidateToken);
+      const existing = nearestExistingPath(candidate);
+      if (!existing) continue;
+      const resolved = realpathSync(existing);
+      if (pathInside(root, resolved)) continue;
+      if (!absoluteInput) {
+        throw new Error(`COMMAND_SCOPE_DENIED: command operand escapes repository root through a symlink or parent path: ${token}`);
+      }
+      if (sensitivePathDenied(resolved)) {
+        throw new Error(`COMMAND_SCOPE_DENIED: sensitive external path is never allowed in repository commands: ${token}`);
+      }
+      const operation = operationForToken(words, index, token, cwd, root);
+      if (operation === 'external_write') {
+        throw new Error(`COMMAND_SCOPE_DENIED: external writes are not allowed from repository commands: ${token}`);
+      }
+      if (operation === 'unsupported') {
+        throw new Error(`COMMAND_SCOPE_DENIED: external path is only allowed for read-only commands or copy-into-repository sources: ${token}`);
+      }
+      const grant = externalGrants.find((entry) => grantCoversPath(entry, resolved, operation));
+      if (!grant) {
+        throw new Error(`EXTERNAL_FILESYSTEM_GRANT_REQUIRED: ${operation} requires an active ${operation === 'external_read' ? 'read' : 'copy_into_repo'} grant for ${token}`);
+      }
+      usages.push({
+        token,
+        canonicalPath: resolved,
+        operation,
+        grantKey: grant.key,
+        grantRoot: grant.canonicalRoot,
+      });
+    }
+  }
+  return usages;
+}

package/src/cli/repositories/controller-home.ts

@@ -0,0 +1,88 @@
+import { existsSync, mkdirSync } from 'fs';
+import { homedir } from 'os';
+import { join, resolve } from 'path';
+
+export function resolveControllerHome(explicit?: string): string {
+  const configured = explicit?.trim()
+    || process.env.FORGE_CONTROLLER_HOME?.trim()
+    || (process.env.XDG_STATE_HOME?.trim()
+      ? join(process.env.XDG_STATE_HOME.trim(), 'forge', 'controller')
+      : join(homedir(), '.forge', 'controller'));
+  return resolve(configured);
+}
+
+/**
+ * Prefer env, then repo-local self-host layout (`_ops/controller-home`) used by
+ * `forge runtime service install`, then the user-global default.
+ */
+export function resolveRepoPreferredControllerHome(repoRoot?: string, explicit?: string): string {
+  const trimmedExplicit = explicit?.trim();
+  if (trimmedExplicit) return resolveControllerHome(trimmedExplicit);
+  const configured = process.env.FORGE_CONTROLLER_HOME?.trim();
+  if (configured) return resolveControllerHome(configured);
+  if (repoRoot?.trim()) {
+    const opsHome = join(resolve(repoRoot.trim()), '_ops', 'controller-home');
+    if (existsSync(join(opsHome, 'mcp', 'mcp.local.json')) || existsSync(opsHome)) {
+      return resolve(opsHome);
+    }
+  }
+  return resolveControllerHome();
+}
+
+export function ensureControllerHome(explicit?: string): string {
+  const home = resolveControllerHome(explicit);
+  for (const child of ['', 'repositories', 'system', 'locks', 'indexes', 'audit', 'mcp', 'sessions', 'work-handles']) {
+    mkdirSync(join(home, child), { recursive: true });
+  }
+  return home;
+}
+
+export function ensureRepoPreferredControllerHome(repoRoot?: string, explicit?: string): string {
+  return ensureControllerHome(resolveRepoPreferredControllerHome(repoRoot, explicit));
+}
+
+export const CONTROLLER_SCOPE_REPO_ID = '__controller__';
+
+export function controllerSystemRoot(controllerHome: string): string {
+  return join(resolveControllerHome(controllerHome), 'system');
+}
+
+/** Resolve the one durable Controller Home. Runtime slot paths are not valid homes. */
+export function durableControllerHome(controllerHome?: string): string {
+  return resolveControllerHome(controllerHome);
+}
+
+export function repositoryControllerRoot(controllerHome: string, repoId: string): string {
+  // Durable repository state lives below the one Controller Home.
+  const durableHome = durableControllerHome(controllerHome);
+  return repoId === CONTROLLER_SCOPE_REPO_ID
+    ? controllerSystemRoot(durableHome)
+    : join(resolveControllerHome(durableHome), 'repositories', repoId);
+}
+
+export function ensureRepositoryControllerLayout(controllerHome: string, repoId: string): string {
+  const root = repositoryControllerRoot(controllerHome, repoId);
+  for (const child of [
+    '',
+    'runs',
+    'jobs',
+    'worktrees',
+    'artifacts',
+    'locks',
+    'indexes',
+    'edit-sessions',
+    'controller',
+    'local-bridge',
+    'ephemeral-issues',
+    'work-handles',
+    'results',
+    'audit',
+    'processes',
+    'leases',
+    'workflows',
+    'projections',
+  ]) {
+    mkdirSync(join(root, child), { recursive: true });
+  }
+  return root;
+}

package/src/cli/repositories/entity-migration.ts

@@ -0,0 +1,199 @@
+import { existsSync, readFileSync, readdirSync, renameSync, statSync, writeFileSync } from 'fs';
+import { dirname, join, relative } from 'path';
+import type { EntityMigrationReport, RepositoryRecord } from './types';
+
+function atomicJson(path: string, value: unknown): void {
+  const temp = join(dirname(path), `.${path.split(/[\\/]/).at(-1)}.${process.pid}.${Date.now()}.tmp`);
+  writeFileSync(temp, `${JSON.stringify(value, null, 2)}\n`, 'utf-8');
+  renameSync(temp, path);
+}
+
+function listFiles(root: string, relativeRoot: string, predicate: (path: string) => boolean): string[] {
+  const absolute = join(root, relativeRoot);
+  if (!existsSync(absolute)) return [];
+  const result: string[] = [];
+  const visit = (path: string): void => {
+    const stat = statSync(path);
+    if (stat.isDirectory()) {
+      for (const name of readdirSync(path)) visit(join(path, name));
+    } else if (stat.isFile() && predicate(path)) {
+      result.push(path);
+    }
+  };
+  visit(absolute);
+  return result;
+}
+
+function bindOwnedField(value: Record<string, unknown>, key: string, expected: string, label: string): boolean {
+  const current = value[key];
+  if (current === undefined || current === null || current === '') {
+    value[key] = expected;
+    return true;
+  }
+  if (current !== expected) {
+    throw new Error(`${label} is already bound to ${String(current)} and cannot be rebound to ${expected}`);
+  }
+  return false;
+}
+
+function normalizeRoot(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim() ? value.trim().replace(/\\/g, '/') : undefined;
+}
+
+function bindIssue(value: Record<string, unknown>, record: RepositoryRecord): boolean {
+  let changed = bindOwnedField(value, 'repoId', record.repoId, 'Issue');
+  const tasks = Array.isArray(value.tasks) ? value.tasks : [];
+  for (const task of tasks) {
+    if (!task || typeof task !== 'object') continue;
+    const target = task as Record<string, unknown>;
+    changed = bindOwnedField(target, 'repoId', record.repoId, `Task ${String(target.id ?? 'unknown')}`) || changed;
+    const verification = target.verification;
+    if (verification && typeof verification === 'object') {
+      changed = bindOwnedField(verification as Record<string, unknown>, 'repoId', record.repoId, `Verification for ${String(target.id ?? 'unknown')}`) || changed;
+    }
+  }
+  return changed;
+}
+
+function inferredCheckoutId(value: Record<string, unknown>, record: RepositoryRecord, label: string): string {
+  const existing = typeof value.checkoutId === 'string' ? value.checkoutId.trim() : '';
+  if (existing) {
+    if (record.checkouts.some((checkout) => checkout.checkoutId === existing)) return existing;
+  }
+  const repoRoot = typeof value.repoRoot === 'string' ? value.repoRoot : undefined;
+  const matched = repoRoot
+    ? record.checkouts.find((checkout) => checkout.canonicalRoot === repoRoot || checkout.localRoot === repoRoot)
+    : undefined;
+  if (matched) return matched.checkoutId;
+  if (record.checkouts.length === 1) return record.checkouts[0].checkoutId;
+  throw new Error(`${label} has no checkoutId and cannot be inferred across ${record.checkouts.length} checkouts`);
+}
+
+function bindRun(value: Record<string, unknown>, record: RepositoryRecord): boolean {
+  let changed = false;
+  const currentRepoId = typeof value.repoId === 'string' ? value.repoId.trim() : '';
+  if (!currentRepoId) {
+    value.repoId = record.repoId;
+    changed = true;
+  } else if (currentRepoId !== record.repoId) {
+    const repoRoot = normalizeRoot(value.repoRoot);
+    const executionRoot = normalizeRoot(value.executionRoot);
+    const worktreePath = normalizeRoot(value.worktreePath);
+    const worktree = normalizeRoot(value.worktree);
+    const checkoutRoots = new Set(record.checkouts.flatMap((checkout) => [
+      normalizeRoot(checkout.canonicalRoot),
+      normalizeRoot(checkout.localRoot),
+    ].filter(Boolean) as string[]));
+    const safeToRebind = [repoRoot, executionRoot, worktreePath, worktree].some((root) => root && checkoutRoots.has(root));
+    if (!safeToRebind) {
+      throw new Error(`Run ${String(value.runId ?? 'unknown')} is already bound to ${currentRepoId} and cannot be rebound to ${record.repoId}`);
+    }
+    value.repoId = record.repoId;
+    changed = true;
+  }
+  const checkoutId = inferredCheckoutId(value, record, `Run ${String(value.runId ?? 'unknown')}`);
+  if (value.checkoutId !== checkoutId) {
+    value.checkoutId = checkoutId;
+    changed = true;
+  }
+  const checkout = record.checkouts.find((candidate) => candidate.checkoutId === checkoutId)!;
+  if (value.repoRoot === undefined || value.repoRoot === null || value.repoRoot === '') {
+    value.repoRoot = checkout.canonicalRoot;
+    changed = true;
+  }
+  const executionRoot = typeof value.worktree === 'string' && value.worktree
+    ? value.worktree
+    : typeof value.repoRoot === 'string' && value.repoRoot
+      ? value.repoRoot
+      : checkout.canonicalRoot;
+  if (value.executionRoot === undefined || value.executionRoot === null || value.executionRoot === '') {
+    value.executionRoot = executionRoot;
+    changed = true;
+  }
+  if (value.worktreePath === undefined || value.worktreePath === null || value.worktreePath === '') {
+    value.worktreePath = executionRoot;
+    changed = true;
+  }
+  return changed;
+}
+
+function bindEditSession(value: Record<string, unknown>, record: RepositoryRecord): boolean {
+  let changed = bindOwnedField(value, 'repoId', record.repoId, `Edit Session ${String(value.sessionId ?? 'unknown')}`);
+  const checkoutId = inferredCheckoutId(value, record, `Edit Session ${String(value.sessionId ?? 'unknown')}`);
+  if (value.checkoutId !== checkoutId) {
+    value.checkoutId = checkoutId;
+    changed = true;
+  }
+  return changed;
+}
+
+function migrateJsonFile(path: string, record: RepositoryRecord, kind: 'issue' | 'run' | 'edit'): boolean {
+  const value = JSON.parse(readFileSync(path, 'utf-8')) as Record<string, unknown>;
+  const changed = kind === 'issue'
+    ? bindIssue(value, record)
+    : kind === 'run'
+      ? bindRun(value, record)
+      : bindEditSession(value, record);
+  if (changed) atomicJson(path, value);
+  return changed;
+}
+
+function migrateJsonl(path: string, record: RepositoryRecord): boolean {
+  const raw = readFileSync(path, 'utf-8');
+  let changed = false;
+  const output = raw.split(/\r?\n/).map((line: string) => {
+    if (!line.trim()) return line;
+    const value = JSON.parse(line) as Record<string, unknown>;
+    changed = bindOwnedField(value, 'repoId', record.repoId, 'Worklog event') || changed;
+    return JSON.stringify(value);
+  }).join('\n');
+  if (changed) writeFileSync(path, output, 'utf-8');
+  return changed;
+}
+
+export function bindRepositoryEntities(record: RepositoryRecord): EntityMigrationReport {
+  const report: EntityMigrationReport = {
+    repoId: record.repoId,
+    checkoutId: record.activeCheckoutId,
+    scanned: 0,
+    updated: 0,
+    unresolved: 0,
+    files: [],
+    errors: [],
+  };
+  const roots: Array<{ root: string; kind: 'issue' | 'run' | 'edit'; predicate: (path: string) => boolean }> = [
+    { root: 'tasks/issues', kind: 'issue', predicate: (path) => path.endsWith('.issue.json') },
+    { root: '.ai/harness/ephemeral-issues', kind: 'issue', predicate: (path) => path.endsWith('.issue.json') },
+    { root: '.ai/harness/jobs', kind: 'run', predicate: (path) => path.endsWith('/meta.json') || path.endsWith('\\meta.json') },
+    { root: '.ai/harness/edit-sessions', kind: 'edit', predicate: (path) => path.endsWith('/session.json') || path.endsWith('\\session.json') },
+  ];
+  for (const entry of roots) {
+    for (const path of listFiles(record.canonicalRoot, entry.root, entry.predicate)) {
+      report.scanned += 1;
+      try {
+        if (migrateJsonFile(path, record, entry.kind)) {
+          report.updated += 1;
+          report.files.push(relative(record.canonicalRoot, path).replace(/\\/g, '/'));
+        }
+      } catch (error) {
+        report.unresolved += 1;
+        report.errors.push({ path: relative(record.canonicalRoot, path), error: error instanceof Error ? error.message : String(error) });
+      }
+    }
+  }
+  for (const root of ['.ai/harness/controller/worklog.jsonl', '.ai/harness/worklog.jsonl']) {
+    const path = join(record.canonicalRoot, root);
+    if (!existsSync(path)) continue;
+    report.scanned += 1;
+    try {
+      if (migrateJsonl(path, record)) {
+        report.updated += 1;
+        report.files.push(root);
+      }
+    } catch (error) {
+      report.unresolved += 1;
+      report.errors.push({ path: root, error: error instanceof Error ? error.message : String(error) });
+    }
+  }
+  return report;
+}

package/src/cli/repositories/ephemeral-workspace.ts

@@ -0,0 +1,62 @@
+import { createHash } from 'crypto';
+import { existsSync, realpathSync, statSync } from 'fs';
+import { isAbsolute, join } from 'path';
+import type { RepositoryRecord } from './types';
+
+export interface EphemeralWorkspaceCoordinates {
+  workspaceId: string;
+  checkoutId: string;
+  canonicalRoot: string;
+}
+
+export interface EphemeralWorkspaceTarget extends EphemeralWorkspaceCoordinates {
+  repository: RepositoryRecord;
+}
+
+export function ephemeralWorkspaceCoordinates(rootInput: string): EphemeralWorkspaceCoordinates {
+  const raw = rootInput.trim();
+  if (!raw) throw new Error('EPHEMERAL_WORKSPACE_ROOT_REQUIRED: workspace_root is required');
+  if (raw.includes('\0')) throw new Error('EPHEMERAL_WORKSPACE_ROOT_INVALID: workspace_root contains a null byte');
+  if (!isAbsolute(raw)) throw new Error('EPHEMERAL_WORKSPACE_ROOT_INVALID: workspace_root must be absolute');
+  if (!existsSync(raw)) throw new Error(`EPHEMERAL_WORKSPACE_ROOT_MISSING: ${raw}`);
+  const canonicalRoot = realpathSync(raw);
+  if (!statSync(canonicalRoot).isDirectory()) throw new Error('EPHEMERAL_WORKSPACE_ROOT_INVALID: workspace_root must be a directory');
+  const digest = createHash('sha256').update(canonicalRoot).digest('hex').slice(0, 24);
+  return {
+    workspaceId: `workspace_${digest}`,
+    checkoutId: `workspace_checkout_${digest}`,
+    canonicalRoot,
+  };
+}
+
+export function resolveEphemeralWorkspaceTarget(rootInput: string, controllerHome: string): EphemeralWorkspaceTarget {
+  const coordinates = ephemeralWorkspaceCoordinates(rootInput);
+  const now = new Date().toISOString();
+  const repository: RepositoryRecord = {
+    schemaVersion: 1,
+    repoId: coordinates.workspaceId,
+    displayName: `Ephemeral Workspace (${coordinates.canonicalRoot.split(/[\\/]/).at(-1) || 'root'})`,
+    localRoot: coordinates.canonicalRoot,
+    canonicalRoot: coordinates.canonicalRoot,
+    activeCheckoutId: coordinates.checkoutId,
+    checkouts: [{
+      checkoutId: coordinates.checkoutId,
+      localRoot: coordinates.canonicalRoot,
+      canonicalRoot: coordinates.canonicalRoot,
+      worktree: false,
+      branch: null,
+      createdAt: now,
+      updatedAt: now,
+      lastSeenAt: now,
+      lifecycle: 'active',
+    }],
+    repositoryType: 'unknown',
+    enabled: true,
+    createdAt: now,
+    updatedAt: now,
+    lastSeenAt: now,
+    configurationPath: join(controllerHome, 'ephemeral-workspaces', `${coordinates.workspaceId}.json`),
+    stateStorageStrategy: 'controller-home',
+  };
+  return { ...coordinates, repository };
+}