@moretea-labs/forge 1.6.0 → 1.7.1

package/src/cli/controller/launch-agents.ts

@@ -1,5 +1,5 @@
-import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, rmSync } from 'fs';
-import { dirname, join } from 'path';
+import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync, rmSync } from 'fs';
+import { basename, dirname, join } from 'path';
 import { homedir } from 'os';
 import { runProcess } from '../../effects/process-runner';
 import { isProcessAlive } from '../../runtime/shared/process-tree';
@@ -341,6 +341,81 @@ export interface LaunchAgentLifecycleResult {
   diagnostics: string[];
 }
 
+export interface RetiredConflictingLaunchAgent {
+  label: string;
+  plistPath: string;
+  backupPath: string;
+}
+
+function decodePlistString(value: string): string {
+  return value
+    .replaceAll('&lt;', '<')
+    .replaceAll('&gt;', '>')
+    .replaceAll('&quot;', '"')
+    .replaceAll('&apos;', "'")
+    .replaceAll('&amp;', '&');
+}
+
+function readLaunchAgentIdentity(path: string): { label: string; arguments: string[] } | undefined {
+  let content: string;
+  try { content = readFileSync(path, 'utf8'); } catch { return undefined; }
+  const label = content.match(/<key>\s*Label\s*<\/key>\s*<string>([\s\S]*?)<\/string>/)?.[1];
+  const argumentsBlock = content.match(/<key>\s*ProgramArguments\s*<\/key>\s*<array>([\s\S]*?)<\/array>/)?.[1];
+  if (!label || !argumentsBlock) return undefined;
+  const args = Array.from(argumentsBlock.matchAll(/<string>([\s\S]*?)<\/string>/g), (match) => decodePlistString(match[1] ?? ''));
+  return { label: decodePlistString(label), arguments: args };
+}
+
+/**
+ * Retire Forge-owned launchd entries that would compete for the same listener.
+ * A Controller Home hash makes labels stable, but it must not make two local
+ * lifecycle owners valid for one port after a migration or reboot.
+ */
+export async function retireConflictingForgeLaunchAgents(
+  input: {
+    accountHome?: string;
+    desiredLabel: string;
+    labelPrefix: string;
+    port: number;
+    requiredArguments: string[];
+  },
+  dependencies: {
+    bootout?: typeof bootoutLaunchAgentWithRetryV2;
+    now?: () => number;
+  } = {},
+): Promise<RetiredConflictingLaunchAgent[]> {
+  const accountHome = input.accountHome?.trim() || process.env.HOME?.trim() || homedir();
+  const launchAgentsRoot = join(accountHome, 'Library', 'LaunchAgents');
+  if (!existsSync(launchAgentsRoot)) return [];
+  const retiredRoot = join(launchAgentsRoot, '.forge-retired');
+  const bootout = dependencies.bootout ?? bootoutLaunchAgentWithRetryV2;
+  const retired: RetiredConflictingLaunchAgent[] = [];
+  const expectedPort = String(input.port);
+  const normalizedLabelPrefix = input.labelPrefix.replace(/\.+$/, '');
+
+  for (const entry of readdirSync(launchAgentsRoot).sort()) {
+    if (!entry.endsWith('.plist')) continue;
+    const plistPath = join(launchAgentsRoot, entry);
+    const identity = readLaunchAgentIdentity(plistPath);
+    const forgeOwnedLabel = identity?.label === normalizedLabelPrefix || identity?.label.startsWith(`${normalizedLabelPrefix}.`);
+    if (!identity || identity.label === input.desiredLabel || !forgeOwnedLabel) continue;
+    if (basename(plistPath, '.plist') !== identity.label) continue;
+    if (!input.requiredArguments.every((argument) => identity.arguments.includes(argument))) continue;
+    const portIndex = identity.arguments.indexOf('--port');
+    if (portIndex < 0 || identity.arguments[portIndex + 1] !== expectedPort) continue;
+
+    const stopped = await bootout({ label: identity.label, plistPath });
+    if (!stopped.ok) {
+      throw new Error(`FORGE_LAUNCH_AGENT_CONFLICT_RETIRE_FAILED: ${identity.label}: ${stopped.diagnostics.join('; ')}`);
+    }
+    mkdirSync(retiredRoot, { recursive: true, mode: 0o700 });
+    const backupPath = join(retiredRoot, `${identity.label}.${(dependencies.now ?? Date.now)()}.plist`);
+    renameSync(plistPath, backupPath);
+    retired.push({ label: identity.label, plistPath, backupPath });
+  }
+  return retired;
+}
+
 export function currentUserLaunchdDomain(): string {
   const uid = typeof process.getuid === 'function'
     ? process.getuid()

package/src/cli/controller/operational-plan.ts

@@ -195,8 +195,8 @@ export function buildControllerOperationalPlan(repoRoot: string, ledger: TaskLed
     },
     mcpToolSchemaConvergence: {
       source: "mcp-tool-schema-convergence",
-      readModels: ["controller_context", "controller_context_pack", "work_status_digest", "prepare_transfer_artifacts"],
-      commandModels: ["work_submit", "run_check", "dispatch_task", "verify_task", "accept_task", "repository_safe_patch_apply"],
+      readModels: ["controller_context", "rh_context", "work_status_digest", "prepare_transfer_artifacts"],
+      commandModels: ["rh_work", "run_check", "repository_command_execute", "plugin_action_execute", "repository_safe_patch_apply"],
       compatibilityRules: [
         "compact reads are default",
         "raw code and raw logs require explicit opt-in tools",

package/src/cli/controller/work-mode.ts

@@ -84,8 +84,8 @@ function behaviorFor(mode: EffectiveTaskMode): WorkModeAssessment['modeBehavior'
       workflow: ['verify checks and changelog', 'build immutable complete release', 'run integration and deployment gates', 'activate through Recovery', 'verify rollback evidence'],
     };
     case 'scale': return {
-      structuralContext: 'off', mutationPhase: 'benchmark', issueRequired: false, planRequired: false, worktreeRequired: true,
-      workflow: ['model concurrency and scheduling', 'run isolated large-load execution', 'measure queue, lease, and worker phases', 'publish benchmark evidence'],
+      structuralContext: 'off', mutationPhase: 'coordinate', issueRequired: false, planRequired: true, worktreeRequired: true,
+      workflow: ['decompose independent deliverables in an approved Plan', 'start bounded isolated Work per Plan step', 'run independent units concurrently when resource claims permit', 'verify deterministic conflict handling and publish coordination evidence'],
     };
     default: return {
       structuralContext: 'off', mutationPhase: 'execute', issueRequired: false, planRequired: false, worktreeRequired: false,
@@ -149,7 +149,9 @@ export function assessWorkMode(input: WorkModeAssessmentInput): WorkModeAssessme
     },
     capabilities: { requiresWorker: input.agentRequested },
     recovery: {
-      required: input.requiresRecovery || explicitMode === 'debug' || explicitMode === 'release' || explicitMode === 'scale',
+      // Debugging expands evidence through rh_context; it does not itself need
+      // durable continuation or command recovery.
+      required: input.requiresRecovery || explicitMode === 'release' || explicitMode === 'scale',
       isolationRequired: explicitMode === 'direct' ? false : input.requiresWorkerIsolation || parallelMode,
     },
   });
@@ -162,7 +164,7 @@ export function assessWorkMode(input: WorkModeAssessmentInput): WorkModeAssessme
     confidence: input.requiresInvestigation || (input.knownPaths?.length ?? 0) === 0 ? 'medium' : 'high',
     reasons: routeDecision.reasons.map((reason) => reason.message),
     nextTools: explicitMode === 'plan' || explicitMode === 'debug'
-      ? ['controller_context_pack(structural_context=required)', ...modeBehavior.workflow]
+      ? ['rh_context(search.structural_context=required)', ...modeBehavior.workflow]
       : explicitMode === 'review'
         ? ['repository_git_status', 'repository_diff', ...modeBehavior.workflow]
         : explicitMode === 'release'

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

@@ -12,6 +12,7 @@ import { tryAppendControllerWorklogEvent } from '../controller/worklog';
 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';
 
 export type EditSessionStatus =
   | 'open'
@@ -257,14 +258,27 @@ function calculateAssurance(session: EditSession, at: string): EditSessionAssura
   };
 }
 
-function assertSessionIdentity(session: EditSession, binding: EditSessionBinding | undefined): void {
+export function assertEditSessionDurableBinding(
+  session: EditSession,
+  binding: EditSessionBinding | undefined,
+  options: { requireBoundIdentity?: boolean } = {},
+): void {
+  const hasDurableIdentity = Boolean(
+    session.workId
+    || session.repoId
+    || session.checkoutId
+    || session.principalId
+    || session.routeDecisionFingerprint,
+  );
+  if (options.requireBoundIdentity === true && hasDurableIdentity && !binding) {
+    throw new Error('EDIT_SESSION_IDENTITY_MISMATCH: binding');
+  }
   if (!binding) return;
   const pairs: Array<[keyof EditSessionBinding, string | undefined, string | undefined]> = [
     ['workId', session.workId, binding.workId],
     ['repoId', session.repoId, binding.repoId],
     ['checkoutId', session.checkoutId, binding.checkoutId],
     ['principalId', session.principalId, binding.principalId],
-    ['controllerInstanceId', session.controllerInstanceId, binding.controllerInstanceId],
     ['routeDecisionFingerprint', session.routeDecisionFingerprint, binding.routeDecisionFingerprint],
   ];
   for (const [field, expected, observed] of pairs) {
@@ -272,6 +286,33 @@ function assertSessionIdentity(session: EditSession, binding: EditSessionBinding
   }
 }
 
+function bindSessionControllerInstance(repoRoot: string, session: EditSession, binding: EditSessionBinding | undefined): EditSession {
+  assertEditSessionDurableBinding(session, binding);
+  const nextInstanceId = binding?.controllerInstanceId?.trim();
+  if (!nextInstanceId || session.controllerInstanceId === nextInstanceId) return session;
+  const durableIdentity = [
+    [session.workId, binding?.workId],
+    [session.repoId, binding?.repoId],
+    [session.checkoutId, binding?.checkoutId],
+    [session.principalId, binding?.principalId],
+  ];
+  if (!durableIdentity.every(([expected, observed]) => Boolean(expected) && expected === observed)) {
+    throw new Error('EDIT_SESSION_IDENTITY_MISMATCH: controllerInstanceId');
+  }
+  const rebound = { ...session, controllerInstanceId: nextInstanceId, updatedAt: now() };
+  writeSession(repoRoot, rebound);
+  tryAppendControllerWorklogEvent(repoRoot, {
+    category: 'edit',
+    action: 'edit_session_controller_instance_rebound',
+    summary: `${session.purpose}: resumed after Controller Runtime instance change`,
+    issueId: session.issueId,
+    taskId: session.taskId,
+    editSessionId: session.sessionId,
+    details: { workId: session.workId, checkoutId: session.checkoutId },
+  });
+  return rebound;
+}
+
 function now(): string {
   return new Date().toISOString();
 }
@@ -1102,7 +1143,7 @@ export function applyEditOperations(repoRoot: string, policy: McpPolicy, session
   maxBatchOperations?: number;
   binding?: EditSessionBinding;
 } = {}): EditSession {
-  const session = getEditSession(repoRoot, sessionId);
+  let session = getEditSession(repoRoot, sessionId);
   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));
@@ -1136,7 +1177,7 @@ export function applyEditOperations(repoRoot: string, policy: McpPolicy, session
   }
   const uniquePaths = new Set(operations.map((operation) => operation.path));
   if (uniquePaths.size !== operations.length) throw new Error('each path may appear only once per patch batch');
-  assertSessionIdentity(session, options.binding);
+  session = bindSessionControllerInstance(repoRoot, session, options.binding);
   if (session.baseRevision && gitRevision(repoRoot) !== session.baseRevision) throw new Error('EDIT_SESSION_BASE_REVISION_CHANGED');
   if (session.workspaceFingerprint && workspaceFingerprint(repoRoot) !== session.workspaceFingerprint) throw new Error('EDIT_SESSION_WORKSPACE_FINGERPRINT_CHANGED');
   try {
@@ -1303,6 +1344,7 @@ export function applyEditOperations(repoRoot: string, policy: McpPolicy, session
   const firstRevision = session.operations.length === 0;
   const records: EditSessionOperationRecord[] = [];
   let appliedOperationCount = 0;
+  let mutationAttempted = false;
   try {
     prepared.forEach((item, index) => {
       const beforeMode = item.beforeMode;
@@ -1312,6 +1354,7 @@ export function applyEditOperations(repoRoot: string, policy: McpPolicy, session
         mkdirSync(dirname(join(repoRoot, backupRelative)), { recursive: true });
         writeFileSync(join(repoRoot, backupRelative), item.before, 'utf-8');
       }
+      mutationAttempted = true;
       if (item.operation.type === 'delete') rmSync(item.absolutePath);
       else atomicWriteFile(repoRoot, item.relativePath, item.after, {
         backupRoot: `${SESSION_ROOT}/${session.sessionId}/atomic-backups/r${revision}`,
@@ -1362,6 +1405,8 @@ export function applyEditOperations(repoRoot: string, policy: McpPolicy, session
         rolledBack: true,
       },
     );
+  } finally {
+    if (mutationAttempted) invalidateRepositoryReadCaches(repoRoot);
   }
 
   const absoluteRevisionPatch = revisionPatchPath(repoRoot, session.sessionId, revision);
@@ -1546,7 +1591,15 @@ export function rollbackEditSession(repoRoot: string, sessionId: string, input:
   const target = savepointRevision ?? (input.toRevision === undefined ? 0 : Math.trunc(input.toRevision));
   if (target < 0 || target >= session.currentRevision) throw new Error(`rollback target must be between 0 and ${session.currentRevision - 1}`);
   const reverted = session.operations.filter((operation) => operation.revision > target).reverse();
-  for (const operation of reverted) restoreOperation(repoRoot, operation);
+  let restoreAttempted = false;
+  try {
+    for (const operation of reverted) {
+      restoreAttempted = true;
+      restoreOperation(repoRoot, operation);
+    }
+  } finally {
+    if (restoreAttempted) invalidateRepositoryReadCaches(repoRoot);
+  }
 
   const at = now();
   session.operations = session.operations.filter((operation) => operation.revision <= target);
@@ -1588,8 +1641,8 @@ export function finalizeEditSession(repoRoot: string, sessionId: string, input:
   approvalConfirmed?: boolean;
   binding?: EditSessionBinding;
 } = {}): EditSession {
-  const session = getEditSession(repoRoot, sessionId);
-  assertSessionIdentity(session, input.binding);
+  let session = getEditSession(repoRoot, sessionId);
+  session = bindSessionControllerInstance(repoRoot, session, input.binding);
   if (session.baseRevision && gitRevision(repoRoot) !== session.baseRevision) throw new Error('EDIT_SESSION_BASE_REVISION_CHANGED');
   if (session.workspaceFingerprint && workspaceFingerprint(repoRoot) !== session.workspaceFingerprint) throw new Error('EDIT_SESSION_WORKSPACE_FINGERPRINT_CHANGED');
   if (session.assurance?.approvalRequired && input.approvalConfirmed !== true) throw new Error('EDIT_SESSION_APPROVAL_REQUIRED');

package/src/cli/github/contracts.ts

@@ -0,0 +1,16 @@
+export interface GitHubRepositoryInfo {
+  nameWithOwner: string;
+  owner: string;
+  repo: string;
+  url: string;
+  defaultBranch: string;
+}
+
+export interface GitHubStatus {
+  available: boolean;
+  authenticated: boolean;
+  version?: string;
+  repository?: GitHubRepositoryInfo;
+  agentTaskSupported: boolean;
+  errors: string[];
+}

package/src/cli/github/github.ts

@@ -7,22 +7,8 @@ import type { ControllerIssue, ControllerTask, GitHubIssueLink } from '../contro
 import { readTaskRunEvidence } from '../controller/run-evidence';
 import { resolveEffectiveTaskState, resolveIssueLifecycleStatus } from '../controller/task-status-resolver';
 
-export interface GitHubRepositoryInfo {
-  nameWithOwner: string;
-  owner: string;
-  repo: string;
-  url: string;
-  defaultBranch: string;
-}
-
-export interface GitHubStatus {
-  available: boolean;
-  authenticated: boolean;
-  version?: string;
-  repository?: GitHubRepositoryInfo;
-  agentTaskSupported: boolean;
-  errors: string[];
-}
+export type { GitHubRepositoryInfo, GitHubStatus } from './contracts';
+import type { GitHubRepositoryInfo, GitHubStatus } from './contracts';
 
 export interface PublishIssueOptions {
   repo?: string;
@@ -32,6 +18,41 @@ export interface PublishIssueOptions {
   projectNumber?: number;
 }
 
+export interface GitHubWorkflowInfo {
+  id: number;
+  name: string;
+  path: string;
+  state: string;
+}
+
+export interface GitHubWorkflowRunInfo {
+  databaseId: number;
+  workflowName: string;
+  displayTitle: string;
+  status: string;
+  conclusion?: string;
+  event: string;
+  headBranch: string;
+  headSha: string;
+  url: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface GitHubWorkflowRunQuery {
+  workflow?: string;
+  branch?: string;
+  status?: string;
+  limit?: number;
+  includeDisabled?: boolean;
+}
+
+export interface GitHubWorkflowDispatchInput {
+  workflow: string;
+  ref?: string;
+  inputs?: Record<string, string | number | boolean>;
+}
+
 function parseJson<T>(value: string, label: string): T {
   try { return JSON.parse(value) as T; } catch (error) { throw new Error(`${label} returned invalid JSON: ${error instanceof Error ? error.message : String(error)}`); }
 }
@@ -43,6 +64,63 @@ function parseRepo(value: string): { owner: string; repo: string } {
   return { owner, repo };
 }
 
+function repositoryName(value: string): string {
+  const parsed = parseRepo(value);
+  return `${parsed.owner}/${parsed.repo}`;
+}
+
+function boundedWorkflowLimit(value: number | undefined, fallback: number): number {
+  if (value === undefined) return fallback;
+  if (!Number.isInteger(value) || value < 1 || value > 100) throw new Error('GITHUB_WORKFLOW_LIMIT_INVALID: limit must be an integer between 1 and 100');
+  return value;
+}
+
+function boundedSingleLine(value: unknown, label: string, maxLength = 256): string | undefined {
+  if (value === undefined || value === null || String(value).trim() === '') return undefined;
+  const normalized = String(value).trim();
+  if (normalized.length > maxLength || /[\r\n\0]/.test(normalized)) throw new Error(`${label} must be a bounded single-line value`);
+  return normalized;
+}
+
+export function buildGitHubWorkflowListArgs(repository: string, input: { limit?: number; includeDisabled?: boolean } = {}): string[] {
+  const args = ['workflow', 'list', '--repo', repositoryName(repository), '--json', 'id,name,path,state', '--limit', String(boundedWorkflowLimit(input.limit, 50))];
+  if (input.includeDisabled === true) args.push('--all');
+  return args;
+}
+
+export function buildGitHubWorkflowRunListArgs(repository: string, input: GitHubWorkflowRunQuery = {}): string[] {
+  const args = [
+    'run', 'list', '--repo', repositoryName(repository),
+    '--json', 'databaseId,workflowName,displayTitle,status,conclusion,event,headBranch,headSha,url,createdAt,updatedAt',
+    '--limit', String(boundedWorkflowLimit(input.limit, 20)),
+  ];
+  const workflow = boundedSingleLine(input.workflow, 'workflow');
+  const branch = boundedSingleLine(input.branch, 'branch');
+  const status = boundedSingleLine(input.status, 'status');
+  if (workflow) args.push('--workflow', workflow);
+  if (branch) args.push('--branch', branch);
+  if (status) args.push('--status', status);
+  if (input.includeDisabled === true) args.push('--all');
+  return args;
+}
+
+export function buildGitHubWorkflowDispatchArgs(repository: string, input: GitHubWorkflowDispatchInput): string[] {
+  const workflow = boundedSingleLine(input.workflow, 'workflow');
+  if (!workflow) throw new Error('GITHUB_WORKFLOW_REQUIRED: workflow is required');
+  const args = ['workflow', 'run', workflow, '--repo', repositoryName(repository)];
+  const ref = boundedSingleLine(input.ref, 'ref');
+  if (ref) args.push('--ref', ref);
+  const entries = Object.entries(input.inputs ?? {}).sort(([left], [right]) => left.localeCompare(right));
+  if (entries.length > 20) throw new Error('GITHUB_WORKFLOW_INPUTS_INVALID: at most 20 inputs are allowed');
+  for (const [key, rawValue] of entries) {
+    if (!/^[A-Za-z0-9_.-]{1,80}$/.test(key)) throw new Error(`GITHUB_WORKFLOW_INPUT_KEY_INVALID: ${key}`);
+    const value = boundedSingleLine(rawValue, `workflow input ${key}`, 8192);
+    if (value === undefined) throw new Error(`GITHUB_WORKFLOW_INPUT_VALUE_INVALID: ${key}`);
+    args.push('--raw-field', `${key}=${value}`);
+  }
+  return args;
+}
+
 function gh(repoRoot: string, args: string[], input?: string, maxOutputBytes = 512 * 1024) {
   return runProcess('gh', args, {
     cwd: repoRoot,
@@ -81,6 +159,47 @@ function versionAtLeast(version: string, minimum: [number, number, number]): boo
   return true;
 }
 
+export function listGitHubWorkflows(
+  repoRoot: string,
+  explicitRepo?: string,
+  input: { limit?: number; includeDisabled?: boolean } = {},
+): GitHubWorkflowInfo[] {
+  const repository = explicitRepo?.trim() ? repositoryName(explicitRepo) : resolveGitHubRepository(repoRoot).nameWithOwner;
+  const result = gh(repoRoot, buildGitHubWorkflowListArgs(repository, input));
+  if (!result.ok) throw new Error(`failed to list GitHub workflows: ${result.error || result.stderr}`);
+  return parseJson<GitHubWorkflowInfo[]>(result.stdout, 'gh workflow list');
+}
+
+export function listGitHubWorkflowRuns(
+  repoRoot: string,
+  explicitRepo?: string,
+  input: GitHubWorkflowRunQuery = {},
+): GitHubWorkflowRunInfo[] {
+  const repository = explicitRepo?.trim() ? repositoryName(explicitRepo) : resolveGitHubRepository(repoRoot).nameWithOwner;
+  const result = gh(repoRoot, buildGitHubWorkflowRunListArgs(repository, input));
+  if (!result.ok) throw new Error(`failed to list GitHub workflow runs: ${result.error || result.stderr}`);
+  return parseJson<GitHubWorkflowRunInfo[]>(result.stdout, 'gh run list');
+}
+
+export function dispatchGitHubWorkflow(
+  repoRoot: string,
+  explicitRepo: string | undefined,
+  input: GitHubWorkflowDispatchInput,
+): Record<string, unknown> {
+  const repository = explicitRepo?.trim() ? repositoryName(explicitRepo) : resolveGitHubRepository(repoRoot).nameWithOwner;
+  const result = gh(repoRoot, buildGitHubWorkflowDispatchArgs(repository, input), undefined, 128 * 1024);
+  if (!result.ok) throw new Error(`failed to dispatch GitHub workflow: ${result.error || result.stderr}`);
+  const output = result.stdout.trim();
+  return {
+    repository,
+    workflow: input.workflow,
+    ...(input.ref?.trim() ? { ref: input.ref.trim() } : {}),
+    inputs: input.inputs ?? {},
+    ...(output ? { output } : {}),
+    ...(/^https:\/\//i.test(output) ? { runUrl: output } : {}),
+  };
+}
+
 export function getGitHubStatus(repoRoot: string, explicitRepo?: string): GitHubStatus {
   const errors: string[] = [];
   const versionResult = gh(repoRoot, ['--version'], undefined, 16 * 1024);

package/src/cli/github/session.ts

@@ -6,7 +6,8 @@ import {
   classifyGitHubCopilotPreflight,
   executorHealthCode,
 } from '../agent-jobs/executor-health';
-import { getGitHubStatus, resolveGitHubRepository, type GitHubRepositoryInfo } from './github';
+import { getGitHubStatus, resolveGitHubRepository } from './github';
+import type { GitHubRepositoryInfo } from './contracts';
 
 export interface GitHubAgentSession {
   id: string;

package/src/cli/installer/managed-entries.ts

@@ -18,6 +18,7 @@
 import { ROUTES, type Route } from '../hook/route-registry';
 
 export const MANAGED_TAG = 'forge hook';
+const LEGACY_REPO_HARNESS_TAGS = ['repo-harness-hook', 'repo-harness hook'] as const;
 
 export interface HookCommand {
   type: 'command';
@@ -50,6 +51,19 @@ export function isManagedEntry(entry: HookEntry): boolean {
   return entry.hooks.some((h) => typeof h?.command === 'string' && h.command.includes(MANAGED_TAG));
 }
 
+/** Legacy adapters are installer-owned migration input, never user hooks. */
+export function isLegacyRepoHarnessEntry(entry: HookEntry): boolean {
+  if (!entry || !Array.isArray(entry.hooks)) return false;
+  return entry.hooks.some((hook) => (
+    typeof hook?.command === 'string'
+    && LEGACY_REPO_HARNESS_TAGS.some((tag) => hook.command.includes(tag))
+  ));
+}
+
+export function isLegacyRepoHarnessCommand(command: string): boolean {
+  return LEGACY_REPO_HARNESS_TAGS.some((tag) => command.includes(tag));
+}
+
 export function buildManagedHooks(host: HookHost): HooksByEvent {
   const out: HooksByEvent = {};
   for (const route of ROUTES) {
@@ -63,7 +77,7 @@ export function stripManagedEntries(existing: HooksByEvent | undefined): HooksBy
   if (!existing) return {};
   const out: HooksByEvent = {};
   for (const [event, entries] of Object.entries(existing)) {
-    const kept = (entries ?? []).filter((e) => !isManagedEntry(e));
+    const kept = (entries ?? []).filter((e) => !isManagedEntry(e) && !isLegacyRepoHarnessEntry(e));
     if (kept.length > 0) out[event] = kept;
   }
   return out;