@moretea-labs/forge 1.7.2 → 1.8.0

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

@@ -1,7 +1,7 @@
 import { createHash } from 'crypto';
 import { spawnSync } from 'child_process';
-import { appendFileSync, mkdirSync } from 'fs';
-import { dirname, join } from 'path';
+import { appendFileSync, existsSync, lstatSync, mkdirSync } from 'fs';
+import { dirname, join, relative, resolve } from 'path';
 import { capProcessOutput, redactProcessOutput } from '../../effects/process-runner';
 import { MAX_AGENT_TIMEOUT_MS, MIN_AGENT_TIMEOUT_MS } from '../controller/runtime-config';
 import { repositoryControllerRoot } from './controller-home';
@@ -27,6 +27,7 @@ import { commandEnvironment, runCanonicalCommand, type RepositoryCommandAsyncHoo
 import {
   changedSnapshotPaths,
   emptyWorkspaceSnapshot,
+  readonlyUnobservedRepositorySnapshot,
   repositorySnapshot,
   repositorySnapshotAsync,
   snapshotChanged,
@@ -138,6 +139,36 @@ function boundedInteger(value: number | undefined, fallback: number, minimum: nu
   return normalized;
 }
 
+function boundedSnapshotFingerprintPaths(
+  root: string,
+  cwd: string,
+  command: CanonicalRepositoryCommand,
+): string[] | undefined {
+  if (command.kind !== 'argv') return undefined;
+  const program = (command.executable ?? '').split(/[\\/]/).at(-1)?.toLowerCase().replace(/\.exe$/, '');
+  const args = [...(command.args ?? [])];
+  if (program !== 'git' || args[0]?.toLowerCase() !== 'add') return undefined;
+  const separator = args.indexOf('--');
+  if (separator < 0 || separator === args.length - 1) return undefined;
+  const operands = args.slice(separator + 1);
+  if (operands.length > 32) return undefined;
+
+  const paths: string[] = [];
+  for (const operand of operands) {
+    if (!operand || operand.includes('\0') || operand.startsWith(':') || /[*?\[\]]/.test(operand)) return undefined;
+    const absolute = resolve(cwd, operand);
+    const path = relative(root, absolute).replace(/\\/g, '/');
+    if (!path || path === '..' || path.startsWith('../')) return undefined;
+    try {
+      if (existsSync(absolute) && lstatSync(absolute).isDirectory()) return undefined;
+    } catch {
+      return undefined;
+    }
+    paths.push(path);
+  }
+  return [...new Set(paths)].sort();
+}
+
 function approvalToken(
   repository: RepositoryRecord,
   relativeCwd: string,
@@ -265,7 +296,10 @@ function prepareRepositoryCommandExecution(
     allowOpaqueLocalScript: input.allowOpaqueLocalScript,
   });
   const externalGrants = loadExternalFilesystemGrants(root).grants;
-  const externalPathUsages = assertCommandPathOperandsStayInRepository(command, cwd, root, externalGrants);
+  const externalPathUsages = assertCommandPathOperandsStayInRepository(command, cwd, root, externalGrants, {
+    controllerHome,
+    repositoryId: repository.repoId,
+  });
   const classification = classifyRepositoryCommand(command, repository.defaultBranch);
   const before = input.reuseSnapshot ?? (input.allowNonGitWorkspace ? emptyWorkspaceSnapshot() : repositorySnapshot(root));
   return finalizePreparedExecution(
@@ -286,6 +320,7 @@ async function prepareRepositoryCommandExecutionAsync(
   repository: RepositoryRecord,
   input: ExecuteRepositoryCommandInput,
   controllerHome?: string,
+  mode: 'standard' | 'readonly_direct' = 'standard',
 ): Promise<{
   root: string;
   cwd: string;
@@ -302,17 +337,27 @@ async function prepareRepositoryCommandExecutionAsync(
     allowOpaqueLocalScript: input.allowOpaqueLocalScript,
   });
   const externalGrants = loadExternalFilesystemGrants(root).grants;
-  const externalPathUsages = assertCommandPathOperandsStayInRepository(command, cwd, root, externalGrants);
+  const externalPathUsages = assertCommandPathOperandsStayInRepository(command, cwd, root, externalGrants, {
+    controllerHome,
+    repositoryId: repository.repoId,
+  });
   const classification = classifyRepositoryCommand(command, repository.defaultBranch);
-  // A proven readonly direct/preview lane never compares before/after mutation.
-  // Skip per-path fingerprints there so a large dirty worktree cannot block a
-  // harmless read; write-capable lanes keep the strict fingerprint cap.
+  if (mode === 'readonly_direct' && classification.risk !== 'readonly') {
+    throw new Error(`READONLY_DIRECT_ROUTE_REQUIRED: received ${classification.risk}`);
+  }
+  // The readonly-direct lane has already resolved repository identity, cwd/path
+  // scope, command input and readonly classification. Mutation snapshots are not
+  // authorization authority, so do not launch rev-parse/branch/status/show-ref
+  // merely to prove that a command selected for this lane did not mutate state.
+  // Write-capable lanes keep their complete observed snapshot semantics.
   const before = input.reuseSnapshot ?? (input.allowNonGitWorkspace
     ? emptyWorkspaceSnapshot()
-    : await repositorySnapshotAsync(root, input.signal, {
-        pathFingerprints: !(classification.risk === 'readonly' && controllerHome === undefined),
-        fingerprintTimeoutMs: input.snapshotFingerprintTimeoutMs,
-      }));
+    : mode === 'readonly_direct'
+      ? readonlyUnobservedRepositorySnapshot()
+      : await repositorySnapshotAsync(root, input.signal, {
+          fingerprintTimeoutMs: input.snapshotFingerprintTimeoutMs,
+          fingerprintPaths: boundedSnapshotFingerprintPaths(root, cwd, command),
+        }));
   return finalizePreparedExecution(
     repository,
     input,
@@ -449,9 +494,9 @@ export function executeRepositoryCommand(
  *
  * This path exists for short repository reads that must remain available while
  * Runtime writer authority is fenced or rotating. It reuses the exact command
- * input/scope classifier, repository snapshots, bounded async process runner,
- * cancellation, environment allowlist, output caps and redaction, but it never
- * writes command audit state, Process records, Leases, Jobs or receipts.
+ * input/scope classifier, bounded async process runner, cancellation,
+ * environment allowlist, output caps and redaction. It deliberately owns no
+ * mutation snapshot or Controller write state, Process records, Leases, Jobs or receipts.
  */
 export async function executeRepositoryReadOnlyCommandDirect(
   repository: RepositoryRecord,
@@ -461,6 +506,7 @@ export async function executeRepositoryReadOnlyCommandDirect(
     repository,
     { ...input, dryRun: false },
     undefined,
+    'readonly_direct',
   );
   const { root, cwd, command, timeoutMs, maxOutputBytes, before, execution: base, externalPathUsages } = prepared;
   if (base.classification.risk !== 'readonly') {
@@ -490,10 +536,9 @@ export async function executeRepositoryReadOnlyCommandDirect(
 
   const result = await runCanonicalCommand(command, cwd, timeoutMs, maxOutputBytes, { signal });
   // This entry point is reachable only after the bounded classifier has proven
-  // the command readonly. A second full repository snapshot would start four
-  // extra Git processes merely to rediscover the invariant we already used to
-  // select this lane. Keep the captured pre-execution snapshot as both sides of
-  // the receipt; write-capable lanes still take independent before/after snapshots.
+  // the command readonly. Mutation evidence is explicitly unobserved rather than
+  // fabricated: no before/after Git snapshot is taken, while write-capable lanes
+  // still take independent observed before/after snapshots.
   const after = before;
   return {
     ...base,
@@ -576,6 +621,7 @@ export async function executeRepositoryCommandAsync(
     try {
       after = await repositorySnapshotAsync(root, signal?.aborted ? undefined : signal, {
         fingerprintTimeoutMs: input.snapshotFingerprintTimeoutMs,
+        fingerprintPaths: boundedSnapshotFingerprintPaths(root, cwd, command),
       });
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);

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

@@ -7,7 +7,7 @@ import { normalizeRepositoryCommand, type CanonicalRepositoryCommand } from './c
 
 const MAX_COMMAND_LENGTH = 32 * 1024;
 
-export type RepositoryCommandExternalPathOperation = 'external_read' | 'external_copy_into_workspace';
+export type RepositoryCommandExternalPathOperation = 'external_read' | 'external_copy_into_workspace' | 'controller_local_effect';
 
 export interface RepositoryCommandExternalPathUsage {
   token: string;
@@ -154,11 +154,30 @@ export function assertRepositoryCommandStableHostIdentity(input: unknown): Canon
   return command;
 }
 
+function assertNoUnmanagedControllerWorktreeLifecycle(command: CanonicalRepositoryCommand): void {
+  const isGitWorktreeAdd = (words: string[]) => {
+    const executable = words[0]?.split(/[\\/]/).at(-1)?.toLowerCase();
+    return executable === 'git' && words[1]?.toLowerCase() === 'worktree' && words[2]?.toLowerCase() === 'add';
+  };
+  if (command.kind === 'argv') {
+    if (isGitWorktreeAdd([command.executable!, ...(command.args ?? [])])) {
+      throw new Error('MANAGED_WORKSPACE_REQUIRED: repository_command_execute must not create an unmanaged temporary git worktree; use rh_work so Forge persists checkout/worktree ownership and terminal cleanup authority');
+    }
+    return;
+  }
+  for (const segment of shellSegments(command.shellCommand ?? '')) {
+    if (isGitWorktreeAdd(shellWords(segment))) {
+      throw new Error('MANAGED_WORKSPACE_REQUIRED: repository_command_execute must not create an unmanaged temporary git worktree; use rh_work so Forge persists checkout/worktree ownership and terminal cleanup authority');
+    }
+  }
+}
+
 export function assertRepositoryCommandInputAllowed(
   input: unknown,
   options: RepositoryCommandInputPolicyOptions = {},
 ): CanonicalRepositoryCommand {
   const command = assertRepositoryCommandStableHostIdentity(input);
+  assertNoUnmanagedControllerWorktreeLifecycle(command);
   if (command.kind === 'shell') {
     assertRepositoryCommandAllowed(command.shellCommand!, options);
   }
@@ -233,7 +252,74 @@ function readOnlyProgram(program: string | undefined): boolean {
   ].includes(program.toLowerCase()));
 }
 
+interface RepositoryCommandPathPolicyOptions {
+  controllerHome?: string;
+  repositoryId?: string;
+}
+
+interface SourceControllerRoundCompatibilityScope {
+  operation: 'round-continue' | 'round-close';
+  controllerHome: string;
+  workId: string;
+  controllerAuthorityId: string;
+  relayScopeId: string;
+}
+
+function sourceControllerRoundCompatibilityScope(
+  command: CanonicalRepositoryCommand,
+  options: RepositoryCommandPathPolicyOptions,
+): SourceControllerRoundCompatibilityScope | undefined {
+  if (command.kind !== 'argv' || !options.controllerHome || !options.repositoryId) return undefined;
+  const executable = command.executable?.split(/[\\/]/).at(-1)?.toLowerCase();
+  const args = command.args ?? [];
+  if (executable !== 'bun' || args[0] !== 'src/cli/index.ts' || args[1] !== 'chatgpt') return undefined;
+  const operation = args[2];
+  if (operation !== 'round-continue' && operation !== 'round-close') return undefined;
+
+  const allowedFlags = operation === 'round-continue'
+    ? new Set(['--controller-home', '--repo-id', '--work-id', '--controller-authority-id', '--relay-scope-id', '--reason', '--timeout-ms'])
+    : new Set(['--controller-home', '--repo-id', '--work-id', '--controller-authority-id', '--relay-scope-id', '--disposition', '--handoff-id', '--reason']);
+  const values = new Map<string, string>();
+  for (let index = 3; index < args.length; index += 2) {
+    const flag = args[index];
+    const value = args[index + 1];
+    if (!flag || !allowedFlags.has(flag) || !value || value.startsWith('--') || values.has(flag)) {
+      throw new Error(`SOURCE_CONTROLLER_ROUND_COMMAND_CONTRACT_INVALID:${operation}:${flag ?? 'missing'}`);
+    }
+    values.set(flag, value);
+  }
+  const required = ['--controller-home', '--repo-id', '--work-id', '--controller-authority-id', '--relay-scope-id'];
+  for (const flag of required) {
+    if (!values.get(flag)?.trim()) throw new Error(`SOURCE_CONTROLLER_ROUND_COMMAND_CONTRACT_INVALID:${operation}:${flag}`);
+  }
+  if (values.get('--repo-id') !== options.repositoryId) {
+    throw new Error(`SOURCE_CONTROLLER_ROUND_COMMAND_REPOSITORY_MISMATCH:${values.get('--repo-id')}`);
+  }
+  const configuredControllerHome = realpathSync(options.controllerHome);
+  const requestedControllerHome = realpathSync(resolve(values.get('--controller-home')!));
+  if (requestedControllerHome !== configuredControllerHome) {
+    throw new Error(`SOURCE_CONTROLLER_ROUND_COMMAND_CONTROLLER_HOME_MISMATCH:${requestedControllerHome}`);
+  }
+  if (operation === 'round-close') {
+    const disposition = values.get('--disposition');
+    if (!disposition || !['wait', 'wait_for_user', 'goal_complete'].includes(disposition)) {
+      throw new Error(`SOURCE_CONTROLLER_ROUND_COMMAND_DISPOSITION_INVALID:${disposition ?? 'missing'}`);
+    }
+    if (disposition === 'wait_for_user' && !values.get('--handoff-id')?.trim()) {
+      throw new Error('SOURCE_CONTROLLER_ROUND_COMMAND_HANDOFF_REQUIRED');
+    }
+  }
+  return {
+    operation,
+    controllerHome: configuredControllerHome,
+    workId: values.get('--work-id')!,
+    controllerAuthorityId: values.get('--controller-authority-id')!,
+    relayScopeId: values.get('--relay-scope-id')!,
+  };
+}
+
 function grantCoversPath(grant: ExternalFilesystemGrant, canonicalPath: string, operation: RepositoryCommandExternalPathOperation): boolean {
+  if (operation === 'controller_local_effect') return false;
   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;
@@ -262,13 +348,27 @@ function operationForToken(words: string[], index: number, external: string, cwd
   return 'external_write';
 }
 
+function gitIndexOnlyRepositoryOperand(words: string[], index: number, candidateToken: string, cwd: string, root: string): boolean {
+  const executable = words[0]?.split(/[\\/]/).at(-1)?.toLowerCase();
+  if (executable !== 'git') return false;
+  const subcommand = words[1];
+  const indexOnly = subcommand === 'update-index'
+    || (subcommand === 'rm' && words.includes('--cached'))
+    || (subcommand === 'restore' && words.includes('--staged') && !words.includes('--worktree'));
+  if (!indexOnly || index < 2) return false;
+  const lexical = candidateToken.startsWith('/') ? resolve(candidateToken) : resolve(cwd, candidateToken);
+  return pathInside(root, lexical);
+}
+
 export function assertCommandPathOperandsStayInRepository(
   command: string | CanonicalRepositoryCommand,
   cwd: string,
   root: string,
   externalGrants: ExternalFilesystemGrant[] = [],
+  options: RepositoryCommandPathPolicyOptions = {},
 ): RepositoryCommandExternalPathUsage[] {
   const usages: RepositoryCommandExternalPathUsage[] = [];
+  const controllerRoundScope = typeof command === 'string' ? undefined : sourceControllerRoundCompatibilityScope(command, options);
   const segments = typeof command === 'string'
     ? shellSegments(command).map((segment) => ({ raw: segment, words: shellWords(segment) }))
     : command.kind === 'shell'
@@ -288,6 +388,10 @@ export function assertCommandPathOperandsStayInRepository(
       const absoluteInput = candidateToken.startsWith('/');
       if (!absoluteInput && !/[./\\*?]/.test(candidateToken) && !existsSync(join(cwd, candidateToken))) continue;
       const candidate = absoluteInput ? resolve(candidateToken) : resolve(cwd, candidateToken);
+      // Git index-only operations address the repository entry itself and do not
+      // dereference its symlink target. Fence them lexically to the repository;
+      // all filesystem-affecting operations still use realpath below.
+      if (gitIndexOnlyRepositoryOperand(words, index, candidateToken, cwd, root)) continue;
       const existing = nearestExistingPath(candidate);
       if (!existing) continue;
       const resolved = realpathSync(existing);
@@ -295,6 +399,18 @@ export function assertCommandPathOperandsStayInRepository(
       if (!absoluteInput) {
         throw new Error(`COMMAND_SCOPE_DENIED: command operand escapes repository root through a symlink or parent path: ${token}`);
       }
+      if (controllerRoundScope
+        && words[index - 1] === '--controller-home'
+        && resolved === controllerRoundScope.controllerHome) {
+        usages.push({
+          token,
+          canonicalPath: resolved,
+          operation: 'controller_local_effect',
+          grantKey: `tool-contract-abi:${controllerRoundScope.operation}:${controllerRoundScope.workId}`,
+          grantRoot: controllerRoundScope.controllerHome,
+        });
+        continue;
+      }
       if (sensitivePathDenied(resolved)) {
         throw new Error(`COMMAND_SCOPE_DENIED: sensitive external path is never allowed in repository commands: ${token}`);
       }

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

@@ -135,9 +135,115 @@ export function rollbackStoppedRepoLocalControllerHomeStorage(migration: Control
   renameSync(physicalHome, logicalHome);
 }
 
+
+export interface StoppedControllerHomeAuthorityRelocation {
+  migrated: boolean;
+  sourceHome: string;
+  destinationHome: string;
+  archivedDestinationHome?: string;
+}
+
+function directoryEntryExists(path: string): boolean {
+  try { lstatSync(path); return true; } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return false;
+    throw error;
+  }
+}
+
+/**
+ * Atomically relocate one fully stopped Controller Home to a new durable path.
+ * The caller owns liveness fencing and must prove Runtime, Connector, Recovery
+ * Gateway, Recovery Watchdog, and any other writers are stopped before calling.
+ *
+ * Existing destination contents are never merged. A caller that has already
+ * proven the destination is an authority-free shell may request archival; the
+ * entire shell is renamed aside so rollback can restore it byte-for-byte.
+ */
+export function relocateStoppedControllerHomeAuthority(input: {
+  sourceHome: string;
+  destinationHome: string;
+  archiveExistingDestination?: boolean;
+  archiveSuffix?: string;
+}): StoppedControllerHomeAuthorityRelocation {
+  const sourceHome = resolve(input.sourceHome);
+  const destinationHome = resolve(input.destinationHome);
+  if (sourceHome === destinationHome) throw new Error('CONTROLLER_HOME_RELOCATION_SAME_HOME');
+  if (!directoryEntryExists(sourceHome)) throw new Error(`CONTROLLER_HOME_RELOCATION_SOURCE_MISSING: ${sourceHome}`);
+  const sourceStat = lstatSync(sourceHome);
+  if (!sourceStat.isDirectory() || sourceStat.isSymbolicLink()) {
+    throw new Error(`CONTROLLER_HOME_RELOCATION_SOURCE_UNSUPPORTED: ${sourceHome}`);
+  }
+  mkdirSync(dirname(destinationHome), { recursive: true });
+
+  let archivedDestinationHome: string | undefined;
+  if (directoryEntryExists(destinationHome)) {
+    const destinationStat = lstatSync(destinationHome);
+    if (!destinationStat.isDirectory() || destinationStat.isSymbolicLink()) {
+      throw new Error(`CONTROLLER_HOME_RELOCATION_DESTINATION_UNSUPPORTED: ${destinationHome}`);
+    }
+    if (!input.archiveExistingDestination) {
+      throw new Error(`CONTROLLER_HOME_RELOCATION_DESTINATION_EXISTS: ${destinationHome}`);
+    }
+    const suffix = input.archiveSuffix?.trim() || `${Date.now()}-${process.pid}`;
+    if (!/^[A-Za-z0-9._-]{1,120}$/.test(suffix)) throw new Error('CONTROLLER_HOME_RELOCATION_ARCHIVE_SUFFIX_INVALID');
+    archivedDestinationHome = `${destinationHome}.pre-migration-${suffix}`;
+    if (directoryEntryExists(archivedDestinationHome)) {
+      throw new Error(`CONTROLLER_HOME_RELOCATION_ARCHIVE_EXISTS: ${archivedDestinationHome}`);
+    }
+    renameSync(destinationHome, archivedDestinationHome);
+  }
+
+  try {
+    renameSync(sourceHome, destinationHome);
+    if (directoryEntryExists(sourceHome) || !lstatSync(destinationHome).isDirectory()) {
+      throw new Error('CONTROLLER_HOME_RELOCATION_POSTCHECK_FAILED');
+    }
+    return {
+      migrated: true,
+      sourceHome,
+      destinationHome,
+      ...(archivedDestinationHome ? { archivedDestinationHome } : {}),
+    };
+  } catch (error) {
+    try {
+      if (!directoryEntryExists(sourceHome) && directoryEntryExists(destinationHome)) renameSync(destinationHome, sourceHome);
+      if (archivedDestinationHome && !directoryEntryExists(destinationHome) && directoryEntryExists(archivedDestinationHome)) {
+        renameSync(archivedDestinationHome, destinationHome);
+      }
+    } catch {
+      throw new Error(`CONTROLLER_HOME_RELOCATION_ROLLBACK_FAILED: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    throw error;
+  }
+}
+
+/** Caller must keep all Controller Home writers stopped until rollback completes. */
+export function rollbackStoppedControllerHomeAuthorityRelocation(
+  relocation: StoppedControllerHomeAuthorityRelocation,
+): void {
+  if (!relocation.migrated) return;
+  const sourceHome = resolve(relocation.sourceHome);
+  const destinationHome = resolve(relocation.destinationHome);
+  const archivedDestinationHome = relocation.archivedDestinationHome ? resolve(relocation.archivedDestinationHome) : undefined;
+  if (directoryEntryExists(sourceHome)) throw new Error(`CONTROLLER_HOME_RELOCATION_ROLLBACK_SOURCE_EXISTS: ${sourceHome}`);
+  if (!directoryEntryExists(destinationHome) || !lstatSync(destinationHome).isDirectory()) {
+    throw new Error(`CONTROLLER_HOME_RELOCATION_ROLLBACK_DESTINATION_MISSING: ${destinationHome}`);
+  }
+  if (archivedDestinationHome && !directoryEntryExists(archivedDestinationHome)) {
+    throw new Error(`CONTROLLER_HOME_RELOCATION_ROLLBACK_ARCHIVE_MISSING: ${archivedDestinationHome}`);
+  }
+  renameSync(destinationHome, sourceHome);
+  try {
+    if (archivedDestinationHome) renameSync(archivedDestinationHome, destinationHome);
+  } catch (error) {
+    try { if (!directoryEntryExists(destinationHome) && directoryEntryExists(sourceHome)) renameSync(sourceHome, destinationHome); } catch { /* best effort */ }
+    throw new Error(`CONTROLLER_HOME_RELOCATION_ROLLBACK_RESTORE_FAILED: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
 export function ensureControllerHome(explicit?: string): string {
   const home = ensureControllerHomeStorage(resolveControllerHome(explicit));
-  for (const child of ['', 'repositories', 'system', 'locks', 'indexes', 'audit', 'mcp', 'sessions', 'work-handles']) {
+  for (const child of ['', 'repositories', 'system', 'locks', 'indexes', 'audit', 'mcp', 'sessions', 'work-handles', 'workflows']) {
     mkdirSync(join(home, child), { recursive: true });
   }
   return home;
@@ -149,6 +255,17 @@ export function ensureRepoPreferredControllerHome(repoRoot?: string, explicit?:
 
 export const CONTROLLER_SCOPE_REPO_ID = '__controller__';
 
+/** Human-editable user Workflow Asset content. Machine workflow state stays in control-plane persistence. */
+export function controllerWorkflowContentRoot(controllerHome: string): string {
+  return join(resolveControllerHome(controllerHome), 'workflows');
+}
+
+export function ensureControllerWorkflowContentRoot(controllerHome: string): string {
+  const root = controllerWorkflowContentRoot(ensureControllerHome(controllerHome));
+  mkdirSync(root, { recursive: true });
+  return root;
+}
+
 export function controllerSystemRoot(controllerHome: string): string {
   return join(resolveControllerHome(controllerHome), 'system');
 }
@@ -178,6 +295,7 @@ export function ensureRepositoryControllerLayout(controllerHome: string, repoId:
     'indexes',
     'edit-sessions',
     'controller',
+    'hook-state',
     'local-bridge',
     'ephemeral-issues',
     'work-handles',

package/src/cli/repositories/identity.ts

@@ -39,6 +39,19 @@ export function stableRemoteRepoId(canonicalRemote: string): string {
   return `repo_${digest(`remote\0${canonicalRemote}`).slice(0, 24)}`;
 }
 
+/** Portable Project identity: stable across ForgeInstance/repository registrations for the same canonical remote. */
+export function stablePortableProjectId(canonicalRemote: string): string {
+  const normalized = normalizeRemoteUrl(canonicalRemote);
+  if (!normalized) throw new Error('PROJECT_REMOTE_IDENTITY_REQUIRED');
+  return `project_${digest(`project\0${normalized}`).slice(0, 24)}`;
+}
+
+export function portableProjectSourceFingerprint(canonicalRemote: string): string {
+  const normalized = normalizeRemoteUrl(canonicalRemote);
+  if (!normalized) throw new Error('PROJECT_REMOTE_IDENTITY_REQUIRED');
+  return digest(`project-source\0${normalized}`);
+}
+
 export function newLocalRepoId(): string {
   return `repo_local_${randomUUID().replace(/-/g, '')}`;
 }