@moretea-labs/forge 1.7.2 → 1.8.1

package/src/cli/editing/edit-session.ts

@@ -1,5 +1,5 @@
 import { createHash, randomBytes } from 'crypto';
-import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'fs';
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'fs';
 import { dirname, join, relative } from 'path';
 import { atomicWriteFile } from '../../effects/fs-transaction';
 import { runProcess } from '../../effects/process-runner';
@@ -13,6 +13,8 @@ import { globMatches, resolveMcpPath } from '../mcp/paths';
 import type { McpPolicy } from '../mcp/types';
 import type { ProcessCheckCompletionReceipt, ProcessCheckReceiptStatus } from '../../runtime/execution/process-runtime/check-receipt';
 import { invalidateRepositoryReadCaches } from '../repository/inspector';
+import type { EditOperation } from './edit-operation-contract';
+export type { EditOperation } from './edit-operation-contract';
 
 export type EditSessionStatus =
   | 'open'
@@ -84,7 +86,6 @@ export interface EditSessionBinding {
   checkoutId?: string;
   principalId?: string;
   controllerInstanceId?: string;
-  routeDecisionFingerprint?: string;
 }
 
 export interface EditSession {
@@ -97,7 +98,6 @@ export interface EditSession {
   checkoutId?: string;
   principalId?: string;
   controllerInstanceId?: string;
-  routeDecisionFingerprint?: string;
   workspaceFingerprint?: string;
   assurance?: EditSessionAssurance;
   purpose: string;
@@ -129,6 +129,8 @@ export interface EditSession {
 export interface EditSessionSummary {
   sessionId: string;
   purpose: string;
+  /** Derived ownership identity for cheap lifecycle inventory; never a second Work authority. */
+  workId?: string;
   status: EditSessionStatus;
   issueId?: string;
   taskId?: string;
@@ -197,17 +199,39 @@ export class EditSessionPatchError extends Error {
   }
 }
 
-export type EditOperation =
-  | { type: 'create'; path: string; content: string }
-  | { type: 'write'; path: string; expectedSha256: string; content: string }
-  | { type: 'replace'; path: string; expectedSha256: string; replacements: Array<{ oldText: string; newText: string; replaceAll?: boolean }> }
-  | { type: 'insert_before' | 'insert_after'; path: string; expectedSha256: string; anchor: string; content: string; occurrence?: number }
-  | { type: 'prepend' | 'append'; path: string; expectedSha256: string; content: string }
-  | { type: 'delete'; path: string; expectedSha256: string };
-
 const SESSION_ROOT = '.ai/harness/edit-sessions';
+const SESSION_OWNER_MARKER = '.forge-owner.json';
+
+function hasDurableEditSessionStorageBinding(repoRoot: string, repoId: string): boolean {
+  const root = join(repoRoot, SESSION_ROOT);
+  try {
+    if (!lstatSync(root).isSymbolicLink()) return false;
+    const marker = JSON.parse(readFileSync(join(root, SESSION_OWNER_MARKER), 'utf-8')) as {
+      schemaVersion?: unknown;
+      repoId?: unknown;
+      binding?: unknown;
+      managedBy?: unknown;
+    };
+    return marker.schemaVersion === 1
+      && marker.repoId === repoId
+      && marker.binding === 'edit-sessions'
+      && marker.managedBy === 'forge';
+  } catch (_error) {
+    return false;
+  }
+}
+
+function assertDurableEditSessionStorageBound(repoRoot: string, repoId: string | undefined): void {
+  const normalizedRepoId = repoId?.trim();
+  if (!normalizedRepoId) return;
+  if (hasDurableEditSessionStorageBinding(repoRoot, normalizedRepoId)) return;
+  throw new Error(`EDIT_SESSION_STORAGE_NOT_BOUND: ${normalizedRepoId} requires Controller Home edit-sessions binding`);
+}
+
 export const MAX_EDIT_PATCH_BATCH_OPERATIONS = 500;
 export const PREFERRED_EDIT_PATCH_BATCH_OPERATIONS = 100;
+export const EDIT_SESSION_TERMINAL_RETENTION_MS = 7 * 24 * 60 * 60_000;
+export const EDIT_SESSION_TERMINAL_MAX_RETAINED = 200;
 
 function hash(content: string): string {
   return createHash('sha256').update(content).digest('hex');
@@ -267,8 +291,7 @@ export function assertEditSessionDurableBinding(
     session.workId
     || session.repoId
     || session.checkoutId
-    || session.principalId
-    || session.routeDecisionFingerprint,
+    || session.principalId,
   );
   if (options.requireBoundIdentity === true && hasDurableIdentity && !binding) {
     throw new Error('EDIT_SESSION_IDENTITY_MISMATCH: binding');
@@ -279,7 +302,6 @@ export function assertEditSessionDurableBinding(
     ['repoId', session.repoId, binding.repoId],
     ['checkoutId', session.checkoutId, binding.checkoutId],
     ['principalId', session.principalId, binding.principalId],
-    ['routeDecisionFingerprint', session.routeDecisionFingerprint, binding.routeDecisionFingerprint],
   ];
   for (const [field, expected, observed] of pairs) {
     if (expected && expected !== observed) throw new Error(`EDIT_SESSION_IDENTITY_MISMATCH: ${String(field)}`);
@@ -334,6 +356,7 @@ function revisionPatchPath(repoRoot: string, sessionId: string, revision: number
 }
 
 function writeSession(repoRoot: string, session: EditSession): void {
+  assertDurableEditSessionStorageBound(repoRoot, session.repoId);
   const path = sessionPath(repoRoot, session.sessionId);
   mkdirSync(dirname(path), { recursive: true });
   writeFileSync(path, `${JSON.stringify(session, null, 2)}\n`, 'utf-8');
@@ -377,7 +400,6 @@ function normalizeStoredSession(value: Partial<EditSession> & { sessionId: strin
     checkoutId: value.checkoutId,
     principalId: value.principalId,
     controllerInstanceId: value.controllerInstanceId,
-    routeDecisionFingerprint: value.routeDecisionFingerprint,
     workspaceFingerprint: value.workspaceFingerprint,
     assurance: value.assurance,
     purpose: value.purpose ?? 'Direct edit',
@@ -617,6 +639,112 @@ function assertCurrentHashes(repoRoot: string, session: EditSession): void {
   if (path) throw new Error(`edited file changed outside the session after revision ${latestOperations(session).get(path)?.revision ?? session.currentRevision}: ${path}`);
 }
 
+function committedChangedPathsBetween(repoRoot: string, baseRevision: string, targetRevision: string): string[] {
+  const ancestor = runProcess('git', ['merge-base', '--is-ancestor', baseRevision, targetRevision], {
+    cwd: repoRoot,
+    timeoutMs: 10_000,
+    maxOutputBytes: 64 * 1024,
+  });
+  if (!ancestor.ok) throw new Error('EDIT_SESSION_SUCCESSOR_HEAD_NOT_DESCENDANT');
+  const diff = runProcess('git', ['diff', '--name-status', '-z', '--find-renames', baseRevision, targetRevision, '--'], {
+    cwd: repoRoot,
+    timeoutMs: 10_000,
+    maxOutputBytes: 4 * 1024 * 1024,
+  });
+  if (!diff.ok) throw new Error(`EDIT_SESSION_SUCCESSOR_HEAD_DIFF_FAILED: ${diff.error || diff.stderr}`);
+  const tokens = diff.stdout.split('\0').filter(Boolean);
+  const paths = new Set<string>();
+  for (let index = 0; index < tokens.length;) {
+    const status = tokens[index++] ?? '';
+    const first = tokens[index++];
+    if (!first) break;
+    paths.add(first);
+    if (status.startsWith('R') || status.startsWith('C')) {
+      const second = tokens[index++];
+      if (second) paths.add(second);
+    }
+  }
+  return [...paths].sort((left, right) => left.localeCompare(right));
+}
+
+export function adoptEditSessionSuccessorHead(repoRoot: string, sessionId: string, input: {
+  binding?: EditSessionBinding;
+  reviewer?: string;
+  note?: string;
+} = {}): EditSession {
+  let session = getEditSession(repoRoot, sessionId);
+  assertDurableEditSessionStorageBound(repoRoot, session.repoId);
+  if (!['dirty', 'checked', 'check_failed'].includes(session.status) || session.operations.length === 0) {
+    throw new Error(`EDIT_SESSION_SUCCESSOR_HEAD_NOT_ELIGIBLE: ${session.status}`);
+  }
+  assertEditSessionDurableBinding(session, input.binding, { requireBoundIdentity: true });
+  if (!session.workId || !session.repoId || !session.checkoutId || !session.principalId) {
+    throw new Error('EDIT_SESSION_SUCCESSOR_HEAD_WORK_BINDING_REQUIRED');
+  }
+  const previousBaseRevision = session.baseRevision?.trim();
+  const successorRevision = gitRevision(repoRoot)?.trim();
+  if (!previousBaseRevision || !successorRevision) throw new Error('EDIT_SESSION_SUCCESSOR_HEAD_REVISION_REQUIRED');
+  if (previousBaseRevision === successorRevision) return bindSessionControllerInstance(repoRoot, session, input.binding);
+
+  const committedPaths = committedChangedPathsBetween(repoRoot, previousBaseRevision, successorRevision);
+  const tracked = new Set(sessionTrackedPaths(session));
+  const overlaps = committedPaths.filter((path) => tracked.has(path));
+  if (overlaps.length > 0) {
+    throw new Error(`EDIT_SESSION_SUCCESSOR_HEAD_PATH_OVERLAP: ${overlaps.join(',')}`);
+  }
+  const mismatches = currentHashMismatches(repoRoot, session);
+  if (mismatches.length > 0) {
+    throw new Error(`EDIT_SESSION_SUCCESSOR_HEAD_CONTENT_DRIFT: ${mismatches.join(',')}`);
+  }
+
+  session = bindSessionControllerInstance(repoRoot, session, input.binding);
+  const revision = session.currentRevision + 1;
+  const revisionPatch = '';
+  const absoluteRevisionPatch = revisionPatchPath(repoRoot, session.sessionId, revision);
+  mkdirSync(dirname(absoluteRevisionPatch), { recursive: true });
+  writeFileSync(absoluteRevisionPatch, revisionPatch, 'utf-8');
+  const at = now();
+  session.revisions.push({
+    revision,
+    operations: [],
+    changedFiles: 0,
+    changedLines: 0,
+    patchPath: relative(repoRoot, absoluteRevisionPatch).replace(/\\/g, '/'),
+    patchSha256: hash(revisionPatch),
+    createdAt: at,
+  });
+  session.currentRevision = revision;
+  session.baseRevision = successorRevision;
+  session.status = 'dirty';
+  session.verifiedAt = undefined;
+  session.checkResults = [];
+  session.reviewer = undefined;
+  session.reviewNote = undefined;
+  session.assurance = calculateAssurance(session, at);
+  session.requestedChecks = session.assurance.requiredChecks;
+  session.workspaceFingerprint = workspaceFingerprint(repoRoot);
+  session.updatedAt = at;
+  writeSession(repoRoot, session);
+  tryAppendControllerWorklogEvent(repoRoot, {
+    category: 'edit',
+    action: 'edit_session_successor_head_adopted',
+    summary: `${session.purpose}: adopted non-overlapping successor HEAD`,
+    actor: input.reviewer?.trim() || undefined,
+    issueId: session.issueId,
+    taskId: session.taskId,
+    editSessionId: session.sessionId,
+    details: {
+      workId: session.workId,
+      previousBaseRevision,
+      successorRevision,
+      committedPaths,
+      revision,
+      note: input.note?.trim() || undefined,
+    },
+  });
+  return session;
+}
+
 function markEditSessionSuperseded(repoRoot: string, session: EditSession, paths: string[], input: {
   reviewer?: string;
   note?: string;
@@ -999,6 +1127,7 @@ function sessionSummary(session: EditSession): EditSessionSummary {
   return {
     sessionId: session.sessionId,
     purpose: session.purpose,
+    workId: session.workId,
     status: session.status,
     issueId: session.issueId,
     taskId: session.taskId,
@@ -1060,6 +1189,7 @@ export function beginEditSession(repoRoot: string, input: {
 }): EditSession {
   const purpose = input.purpose.trim();
   if (!purpose) throw new Error('edit session purpose is required');
+  assertDurableEditSessionStorageBound(repoRoot, input.binding?.repoId);
   const at = now();
   const session: EditSession = {
     schemaVersion: 3,
@@ -1071,7 +1201,6 @@ export function beginEditSession(repoRoot: string, input: {
     checkoutId: input.binding?.checkoutId?.trim() || undefined,
     principalId: input.binding?.principalId?.trim() || undefined,
     controllerInstanceId: input.binding?.controllerInstanceId?.trim() || undefined,
-    routeDecisionFingerprint: input.binding?.routeDecisionFingerprint?.trim() || undefined,
     workspaceFingerprint: workspaceFingerprint(repoRoot),
     purpose,
     status: 'open',
@@ -1125,6 +1254,135 @@ export function listEditSessions(repoRoot: string, limit = 100): EditSessionSumm
     .sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
 }
 
+
+export interface EditSessionRetentionResult {
+  removedSessionIds: string[];
+  reclaimedBytes: number;
+  unknownReclaimedByteCount: number;
+  inspected: number;
+  eligible: number;
+  attempted: number;
+  retained: number;
+  budgetExhausted: boolean;
+  skippedByReason: Record<string, number>;
+  errors: string[];
+}
+
+function editSessionDirectoryBytes(path: string): { bytes: number; complete: boolean } {
+  let bytes = 0;
+  try {
+    for (const entry of readdirSync(path, { withFileTypes: true })) {
+      const entryPath = join(path, entry.name);
+      if (entry.isDirectory()) {
+        const nested = editSessionDirectoryBytes(entryPath);
+        bytes += nested.bytes;
+        if (!nested.complete) return { bytes, complete: false };
+      } else if (entry.isFile()) {
+        bytes += statSync(entryPath).size;
+      }
+    }
+    return { bytes, complete: true };
+  } catch {
+    return { bytes, complete: false };
+  }
+}
+
+/**
+ * Physically reclaim terminal EditSession artifacts after their Work no longer
+ * owns live review/delivery authority. The repository-relative path may be the
+ * runtime-storage compatibility link; deletion therefore follows the existing
+ * Controller Home binding instead of creating a second persistence root.
+ */
+export function cleanupTerminalEditSessionRecords(repoRoot: string, input: {
+  nowMs?: number;
+  retentionMs?: number;
+  maxRetained?: number;
+  maxEntries?: number;
+  maxRemovals?: number;
+  sequence?: number;
+  protectedWorkIds?: Iterable<string>;
+} = {}): EditSessionRetentionResult {
+  const root = join(repoRoot, SESSION_ROOT);
+  const result: EditSessionRetentionResult = {
+    removedSessionIds: [], reclaimedBytes: 0, unknownReclaimedByteCount: 0,
+    inspected: 0, eligible: 0, attempted: 0, retained: 0, budgetExhausted: false,
+    skippedByReason: {}, errors: [],
+  };
+  if (!existsSync(root)) return result;
+  const nowMs = input.nowMs ?? Date.now();
+  const retentionMs = Math.max(60_000, Math.trunc(input.retentionMs ?? EDIT_SESSION_TERMINAL_RETENTION_MS));
+  const maxRetained = Math.max(0, Math.trunc(input.maxRetained ?? EDIT_SESSION_TERMINAL_MAX_RETAINED));
+  const maxEntries = Math.max(1, Math.trunc(input.maxEntries ?? 2_000));
+  const maxRemovals = Math.max(0, Math.trunc(input.maxRemovals ?? 50));
+  const protectedWorkIds = new Set(Array.from(input.protectedWorkIds ?? [], (value) => String(value).trim()).filter(Boolean));
+  const skip = (reason: string) => {
+    result.retained += 1;
+    result.skippedByReason[reason] = (result.skippedByReason[reason] ?? 0) + 1;
+  };
+  let entries;
+  try {
+    entries = readdirSync(root, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory() && existsSync(join(root, entry.name, 'session.json')))
+      .sort((left, right) => right.name.localeCompare(left.name));
+  } catch (error) {
+    result.errors.push(`edit_session_root_unreadable:${error instanceof Error ? error.message : String(error)}`);
+    return result;
+  }
+  if (entries.length === 0) return result;
+  const rank = new Map(entries.map((entry, index) => [entry.name, index]));
+  const start = (Math.max(0, Math.trunc(input.sequence ?? 0)) * maxEntries) % entries.length;
+  const window = [...entries.slice(start), ...entries.slice(0, start)].slice(0, Math.min(maxEntries, entries.length));
+  if (entries.length > window.length) result.budgetExhausted = true;
+  for (const entry of window) {
+    result.inspected += 1;
+    let session: EditSession;
+    try { session = getEditSession(repoRoot, entry.name); }
+    catch (error) {
+      result.errors.push(`edit_session_unreadable:${entry.name}:${error instanceof Error ? error.message : String(error)}`);
+      skip('session_unreadable');
+      continue;
+    }
+    if (!['finalized', 'superseded', 'rolled_back'].includes(session.status)) {
+      skip('active_session');
+      continue;
+    }
+    if (session.workId && protectedWorkIds.has(session.workId)) {
+      skip('active_work');
+      continue;
+    }
+    const updatedMs = Date.parse(session.updatedAt);
+    if (!Number.isFinite(updatedMs)) {
+      skip('terminal_timestamp_unknown');
+      continue;
+    }
+    const beyondAge = nowMs - updatedMs >= retentionMs;
+    const beyondCount = (rank.get(entry.name) ?? 0) >= maxRetained;
+    if (!beyondAge && !beyondCount) {
+      skip('within_retention');
+      continue;
+    }
+    result.eligible += 1;
+    if (result.attempted >= maxRemovals) {
+      result.budgetExhausted = true;
+      skip('cleanup_budget_exhausted');
+      continue;
+    }
+    result.attempted += 1;
+    const path = sessionDir(repoRoot, session.sessionId);
+    const measurement = editSessionDirectoryBytes(path);
+    if (measurement.complete) result.reclaimedBytes += measurement.bytes;
+    else result.unknownReclaimedByteCount += 1;
+    try {
+      rmSync(path, { recursive: true, force: true });
+      result.removedSessionIds.push(session.sessionId);
+    } catch (error) {
+      result.errors.push(`edit_session_remove_failed:${session.sessionId}:${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  result.removedSessionIds.sort();
+  return result;
+}
+
 export function getEditSessionDiff(repoRoot: string, sessionId: string): {
   sessionId: string;
   path?: string;
@@ -1144,6 +1402,7 @@ export function applyEditOperations(repoRoot: string, policy: McpPolicy, session
   binding?: EditSessionBinding;
 } = {}): EditSession {
   let session = getEditSession(repoRoot, sessionId);
+  assertDurableEditSessionStorageBound(repoRoot, session.repoId);
   if (['finalized', 'rolled_back'].includes(session.status)) throw new Error(`edit session is closed: ${session.status}`);
   if (operations.length === 0) throw new Error('at least one edit operation is required');
   const maxBatchOperations = Math.max(1, Math.trunc(options.maxBatchOperations ?? MAX_EDIT_PATCH_BATCH_OPERATIONS));
@@ -1382,7 +1641,10 @@ export function applyEditOperations(repoRoot: string, policy: McpPolicy, session
         repoRoot,
         record.path,
         readFileSync(join(repoRoot, record.backupPath), 'utf-8'),
-        record.beforeMode === undefined ? {} : { mode: record.beforeMode },
+        {
+          backupRoot: `${SESSION_ROOT}/${session.sessionId}/atomic-backups/apply-rollback-r${revision}`,
+          ...(record.beforeMode === undefined ? {} : { mode: record.beforeMode }),
+        },
       );
     }
     const message = error instanceof Error ? error.message : String(error);
@@ -1531,7 +1793,7 @@ export async function verifyEditSessionAsync(repoRoot: string, sessionId: string
   });
 }
 
-function restoreOperation(repoRoot: string, operation: EditSessionOperationRecord): void {
+function restoreOperation(repoRoot: string, operation: EditSessionOperationRecord, backupRoot: string): void {
   const absolute = join(repoRoot, operation.path);
   if (operation.type === 'create') {
     if (existsSync(absolute)) {
@@ -1554,7 +1816,10 @@ function restoreOperation(repoRoot: string, operation: EditSessionOperationRecor
     repoRoot,
     operation.path,
     readFileSync(join(repoRoot, operation.backupPath), 'utf-8'),
-    operation.beforeMode === undefined ? {} : { mode: operation.beforeMode },
+    {
+      backupRoot,
+      ...(operation.beforeMode === undefined ? {} : { mode: operation.beforeMode }),
+    },
   );
 }
 
@@ -1564,6 +1829,7 @@ export function rollbackEditSession(repoRoot: string, sessionId: string, input:
   allowFinalized?: boolean;
 } = {}): EditSession {
   const session = getEditSession(repoRoot, sessionId);
+  assertDurableEditSessionStorageBound(repoRoot, session.repoId);
   if ((session.status === 'open' || (session.status === 'finalized' && input.allowFinalized)) && session.operations.length === 0) {
     const at = now();
     session.status = 'rolled_back';
@@ -1595,7 +1861,11 @@ export function rollbackEditSession(repoRoot: string, sessionId: string, input:
   try {
     for (const operation of reverted) {
       restoreAttempted = true;
-      restoreOperation(repoRoot, operation);
+      restoreOperation(
+        repoRoot,
+        operation,
+        `${SESSION_ROOT}/${session.sessionId}/atomic-backups/rollback-to-r${target}`,
+      );
     }
   } finally {
     if (restoreAttempted) invalidateRepositoryReadCaches(repoRoot);

package/src/cli/github/plugin.ts

@@ -1,5 +1,5 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
-import { dirname, join } from "path";
+import { existsSync, readFileSync, rmSync } from "fs";
+import { join } from "path";
 import { getGitHubStatus, publishIssueToGitHub, refreshGitHubIssue, closeGitHubIssue } from "./github";
 import type { ControllerIssue } from "../controller/types";
 import { tryAppendControllerWorklogEvent } from "../controller/worklog";
@@ -104,6 +104,10 @@ function loadLegacyGitHubPluginConfig(repoRoot: string): GitHubPluginConfig | un
   }
 }
 
+function retireLegacyGitHubPluginConfig(repoRoot: string): void {
+  rmSync(join(repoRoot, CONFIG_PATH), { force: true });
+}
+
 function findRepositoryRecord(repoRoot: string): RepositoryRecord | undefined {
   const controllerHome = resolveRepoPreferredControllerHome(repoRoot);
   return listRepositories(controllerHome).find((record) =>
@@ -127,18 +131,18 @@ function configFromRepository(record: RepositoryRecord | undefined): GitHubPlugi
   });
 }
 
-function syncRepositoryGitHubConfig(repoRoot: string, config: GitHubPluginConfig): void {
+function syncRepositoryGitHubConfig(repoRoot: string, config: GitHubPluginConfig): boolean {
   const record = findRepositoryRecord(repoRoot);
-  if (!record) return;
+  if (!record) return false;
   const controllerHome = resolveRepoPreferredControllerHome(repoRoot);
   const current = record.github;
   const repository = config.repository?.trim();
   const effectiveRepository = repository
     || current?.repository
     || (current?.owner && current?.repo ? `${current.owner}/${current.repo}` : undefined);
-  if (!effectiveRepository) return;
+  if (!effectiveRepository) return false;
   const [owner, repo] = effectiveRepository.includes("/") ? effectiveRepository.split("/", 2) : [current?.owner, current?.repo];
-  if (!owner || !repo) return;
+  if (!owner || !repo) return false;
   updateRepository(record.repoId, {
     github: {
       owner,
@@ -156,6 +160,7 @@ function syncRepositoryGitHubConfig(repoRoot: string, config: GitHubPluginConfig
       authenticationCapability: current?.authenticationCapability ?? "unknown",
     },
   }, controllerHome);
+  return true;
 }
 
 export function loadGitHubPluginConfig(repoRoot: string): GitHubPluginConfig {
@@ -173,12 +178,12 @@ export function loadGitHubPluginConfig(repoRoot: string): GitHubPluginConfig {
       projectNumber: legacyConfig.projectNumber ?? registryConfig.projectNumber,
       statusField: legacyConfig.statusField ?? registryConfig.statusField,
     });
-    syncRepositoryGitHubConfig(repoRoot, merged);
+    if (syncRepositoryGitHubConfig(repoRoot, merged)) retireLegacyGitHubPluginConfig(repoRoot);
     return merged;
   }
   if (registryConfig) return registryConfig;
   if (legacyConfig) {
-    syncRepositoryGitHubConfig(repoRoot, legacyConfig);
+    if (syncRepositoryGitHubConfig(repoRoot, legacyConfig)) retireLegacyGitHubPluginConfig(repoRoot);
     return legacyConfig;
   }
   return defaultGitHubPluginConfig();
@@ -224,10 +229,10 @@ export function saveGitHubPluginConfig(
     projectNumber,
     statusField,
   };
-  syncRepositoryGitHubConfig(repoRoot, config);
-  const path = join(repoRoot, CONFIG_PATH);
-  mkdirSync(dirname(path), { recursive: true });
-  writeFileSync(path, `${JSON.stringify(config, null, 2)}\n`, "utf-8");
+  if (!syncRepositoryGitHubConfig(repoRoot, config)) {
+    throw new Error("GITHUB_PLUGIN_REPOSITORY_REGISTRATION_REQUIRED: configure GitHub only after the repository is registered in Controller Home");
+  }
+  retireLegacyGitHubPluginConfig(repoRoot);
   statusCache.set(repoRoot, {
     at: Date.now() - STATUS_CACHE_TTL_MS + CONFIG_STATUS_CACHE_TTL_MS,
     fingerprint: JSON.stringify(config),

package/src/cli/hook/route-registry.ts

@@ -6,11 +6,9 @@
  * names are an internal implementation detail — Phase 2 sealed hooks will
  * replace them with bundled implementations without changing the tuple.
  *
- * Derived from `.codex/hooks.json` reality verified Phase 0 canary
- * 2026-05-28 (see docs/architecture/global-hook-runtime.md and Codex consult
- * session 019e6df7-e7c9-70e2-8872-db9869420bd0). The matcher dimension was
- * the missing piece in the X (event-only) design — see
- * tasks/notes/hook-global-runtime.notes.md § Phase 1B Design Pivot.
+ * Derived from `.codex/hooks.json` reality verified by the Phase 0 canary on
+ * 2026-05-28. Historical rationale and verification evidence are preserved in
+ * Git history; the matcher-aware registry and its tests are the current contract.
  *
  * Order matters: it is the stable adapter entry order. Codex hashes adapter
  * entries by `(absolute-path, event-snake, i, j)`, so any reordering re-prompts

package/src/cli/hook/runtime.ts

@@ -1,10 +1,14 @@
 import * as fs from 'fs';
+import * as os from 'os';
 import * as path from 'path';
 import { fileURLToPath } from 'url';
 import { execFileSync, spawnSync, type StdioOptions } from 'child_process';
+import { repositoryControllerRoot, resolveControllerHome } from '../repositories/controller-home';
+import { findRegisteredRepositoryByCheckoutRoot } from '../repositories/registry';
 import { getRoute, type HookEvent, type RouteId } from './route-registry';
 
-const OPT_IN_MARKER = '.ai/harness/workflow-contract.json';
+const OPT_IN_MARKER = 'forge.config.json';
+const LEGACY_OPT_IN_MARKER = '.ai/harness/workflow-contract.json';
 const POLICY_FILE = '.ai/harness/policy.json';
 const PACKAGE_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
 
@@ -83,7 +87,7 @@ export function resolveRepoRoot(cwd: string): string | null {
 }
 
 export function isOptIn(repoRoot: string): boolean {
-  return fs.existsSync(path.join(repoRoot, OPT_IN_MARKER));
+  return fs.existsSync(path.join(repoRoot, OPT_IN_MARKER)) || fs.existsSync(path.join(repoRoot, LEGACY_OPT_IN_MARKER));
 }
 
 /**
@@ -108,6 +112,36 @@ export interface ResolvedHooksDir {
   source: HookSource;
 }
 
+export interface ResolvedHookStateRoot {
+  root: string;
+  source: 'env' | 'controller-home' | 'ephemeral';
+  repoId?: string;
+}
+
+export function resolveHookStateRoot(
+  repoRoot: string,
+  env: NodeJS.ProcessEnv = process.env,
+): ResolvedHookStateRoot {
+  const explicit = env.FORGE_HOOK_STATE_ROOT?.trim();
+  if (explicit && path.isAbsolute(explicit)) {
+    fs.mkdirSync(explicit, { recursive: true });
+    return { root: explicit, source: 'env' };
+  }
+
+  const controllerHome = resolveControllerHome(env.FORGE_CONTROLLER_HOME);
+  const repository = findRegisteredRepositoryByCheckoutRoot(repoRoot, controllerHome);
+  if (repository) {
+    const root = path.join(repositoryControllerRoot(controllerHome, repository.repoId), 'hook-state');
+    fs.mkdirSync(root, { recursive: true });
+    return { root, source: 'controller-home', repoId: repository.repoId };
+  }
+
+  return {
+    root: fs.mkdtempSync(path.join(os.tmpdir(), 'forge-hook-state-')),
+    source: 'ephemeral',
+  };
+}
+
 function repoPinsHookSource(repoRoot: string): boolean {
   try {
     const raw = fs.readFileSync(path.join(repoRoot, POLICY_FILE), 'utf-8');
@@ -173,6 +207,7 @@ export function runHook(opts: RunHookOptions): RunHookResult {
     return { exitCode: 2, reason: 'unknown-route', repoRoot, scriptsRun, skippedScripts };
   }
 
+  const hookState = resolveHookStateRoot(repoRoot);
   const resolved: ResolvedHooksDir = opts.hooksDir
     ? { dir: opts.hooksDir, source: 'env' }
     : resolveHooksDir(repoRoot);
@@ -202,6 +237,7 @@ export function runHook(opts: RunHookOptions): RunHookResult {
     ? ['inherit', 'pipe', 'inherit']
     : (opts.stdio ?? 'inherit');
 
+  try {
   for (const script of route.scripts) {
     const scriptPath = path.join(hooksDir, script);
     if (!fs.existsSync(scriptPath)) {
@@ -230,7 +266,12 @@ export function runHook(opts: RunHookOptions): RunHookResult {
     const child = spawnSync('bash', [scriptPath, ...(opts.args ?? [])], {
       cwd: repoRoot,
       stdio,
-      env: { ...process.env, HOOK_REPO_ROOT: repoRoot },
+      env: {
+        ...process.env,
+        HOOK_REPO_ROOT: repoRoot,
+        FORGE_HOOK_STATE_ROOT: hookState.root,
+        FORGE_REPO_ID: hookState.repoId ?? '',
+      },
     });
 
     if (child.error) {
@@ -300,4 +341,9 @@ export function runHook(opts: RunHookOptions): RunHookResult {
   }
 
   return { exitCode: 0, reason: 'ok', repoRoot, scriptsRun, skippedScripts };
+  } finally {
+    if (hookState.source === 'ephemeral') {
+      fs.rmSync(hookState.root, { recursive: true, force: true });
+    }
+  }
 }

package/src/cli/index.ts

@@ -17,6 +17,7 @@ import { buildSetupCommand, formatInitHook, runInitHook } from './commands/init-
 import { formatMigratePlan, runMigrate } from './commands/migrate';
 import { buildToolsCommand } from './commands/tools';
 import { buildPluginCommand } from './commands/plugin';
+import { buildComputerCommand } from './commands/computer';
 import { buildBrainCommand } from './commands/brain';
 import { buildCapabilityContextCommand } from './commands/capability-context';
 import { buildDocsCommand } from './commands/docs';
@@ -53,6 +54,7 @@ export const SUBCOMMANDS = [
   'setup',
   'tools',
   'plugin',
+  'computer',
   'brain',
   'capability-context',
   'docs',
@@ -509,6 +511,7 @@ export function buildProgram(): Command {
 
   program.addCommand(buildToolsCommand());
   program.addCommand(buildPluginCommand());
+  program.addCommand(buildComputerCommand());
   program.addCommand(buildBrainCommand(), { hidden: true });
   program.addCommand(buildCapabilityContextCommand(), { hidden: true });
   program.addCommand(buildDocsCommand());

package/src/cli/local-bridge/connector-freshness.ts

@@ -18,8 +18,8 @@ import {
 import {
   loadMcpLocalConfig,
   loadMcpServiceLocalConfig,
-} from '../mcp/auth';
-import { PREFERRED_FACADE_TOOL_NAMES, DEFAULT_CONTROLLER_TOOL_NAMES } from '../mcp/toolset-names';
+} from '../../../adapters/mcp/auth';
+import { PREFERRED_FACADE_TOOL_NAMES, DEFAULT_CONTROLLER_TOOL_NAMES } from '../../../adapters/mcp/toolset-names';
 import { resolveRepoPreferredControllerHome } from '../repositories/controller-home';
 import type { PlainStatusTone } from './console-view-models';