@moretea-labs/forge 1.6.0 → 1.7.0

package/scripts/verify-sprint.sh

@@ -20,54 +20,6 @@ json_escape() {
   printf '%s' "$value"
 }
 
-review_card_field() {
-  local file="$1"
-  local label="$2"
-  [[ -n "$file" && -f "$file" ]] || return 1
-  awk -v wanted="$label" '
-    function trim(s) {
-      gsub(/^[[:space:]]+/, "", s)
-      gsub(/[[:space:]]+$/, "", s)
-      return s
-    }
-    BEGIN { wanted = tolower(wanted) }
-    /^##[[:space:]]+Human Review Card[[:space:]]*$/ { in_section = 1; next }
-    in_section && /^##[[:space:]]+/ { exit }
-    !in_section { next }
-    /^[[:space:]]*-[[:space:]]*/ {
-      line = $0
-      sub(/^[[:space:]]*-[[:space:]]*/, "", line)
-      key = line
-      sub(/:.*/, "", key)
-      key = tolower(trim(key))
-      if (key == wanted) {
-        sub(/^[^:]*:[[:space:]]*/, "", line)
-        print trim(line)
-        exit
-      }
-    }
-  ' "$file"
-}
-
-normalize_status_token() {
-  local value="$1"
-  value="$(printf '%s' "$value" | sed -E 's/[;,].*$//; s/[[:space:]].*$//; s/^[[:space:]]+//; s/[[:space:]]+$//' | tr '[:upper:]' '[:lower:]')"
-  printf '%s' "$value"
-}
-
-field_has_concrete_value() {
-  local value="$1"
-  local token
-  token="$(normalize_status_token "$value")"
-  [[ -n "$token" ]] || return 1
-  case "$token" in
-    tbd|todo|n/a|na|none|unknown|unavailable|pending|...)
-      return 1
-      ;;
-  esac
-  return 0
-}
-
 read_contract_task_profile() {
   local file="$1"
   awk '/^> \*\*Task Profile\*\*:/ {sub(/^.*> \*\*Task Profile\*\*:[[:space:]]*/, ""); gsub(/\r/, ""); print; exit}' "$file" | xargs
@@ -304,25 +256,14 @@ if [[ -f ".ai/hooks/lib/workflow-state.sh" ]]; then
   # shellcheck source=/dev/null
   . ".ai/hooks/lib/workflow-state.sh"
   contract_file="$(workflow_active_contract || true)"
-  review_file="$(workflow_active_review || true)"
   checks_file="$(workflow_checks_file)"
 else
   contract_file="$(find tasks/contracts -maxdepth 1 -name '*.contract.md' -type f 2>/dev/null | sort | head -n 1)"
-  if [[ -n "$contract_file" ]]; then
-    contract_slug="$(basename "$contract_file" | sed -E 's/\.contract\.md$//')"
-    review_file="tasks/reviews/${contract_slug}.review.md"
-  else
-    review_file=""
-  fi
   checks_file=".ai/harness/checks/latest.json"
 fi
 if [[ -z "$contract_file" || ! -f "$contract_file" ]]; then
   contract_file="$(active_plan_declared_path "Task Contract" || active_plan_declared_path "Sprint Contract" || true)"
 fi
-if [[ -z "$review_file" || ! -f "$review_file" ]]; then
-  review_file="$(active_plan_declared_path "Task Review" || active_plan_declared_path "Sprint Review" || true)"
-fi
-
 [[ -n "$contract_file" && -f "$contract_file" ]] || { echo "No active sprint contract found" >&2; exit 1; }
 
 generated_at="$(date '+%Y-%m-%dT%H:%M:%S%z')"
@@ -378,74 +319,9 @@ if [[ -n "$contract_output" ]]; then
   printf '%s\n' "$contract_output"
 fi
 
-review_status="fail"
-review_message="Task review recommends pass and Human Review Card verdict is pass."
-review_card_verdict=""
-review_card_external=""
-review_card_change_type=""
-review_card_rollback=""
-if [[ -z "$review_file" || ! -f "$review_file" ]]; then
-  review_message="Missing task review file."
-  echo "Missing task review file" >&2
-else
-  review_card_verdict="$(normalize_status_token "$(review_card_field "$review_file" "Verdict" || true)")"
-  review_card_external="$(review_card_field "$review_file" "External acceptance" || true)"
-  review_card_change_type="$(normalize_status_token "$(review_card_field "$review_file" "Change type" || true)")"
-  review_card_rollback="$(review_card_field "$review_file" "Rollback" || true)"
-fi
-
-if [[ -n "$review_file" && -f "$review_file" ]]; then
-  if ! grep -Eq '^> \*\*Recommendation\*\*:[[:space:]]*pass([[:space:]]*)$' "$review_file"; then
-    review_message="Task review does not recommend pass."
-    echo "Task review does not recommend pass" >&2
-  elif [[ -z "$review_card_verdict" ]]; then
-    review_message="Task review is missing Human Review Card verdict."
-    echo "Task review is missing Human Review Card verdict" >&2
-  elif [[ "$review_card_verdict" != "pass" ]]; then
-    review_message="Human Review Card verdict is not pass: $review_card_verdict"
-    echo "Human Review Card verdict is not pass: $review_card_verdict" >&2
-  elif [[ -n "$task_profile" && "$review_card_change_type" != "$task_profile" ]]; then
-    review_message="Human Review Card change type does not match task_profile: ${review_card_change_type:-missing} != $task_profile"
-    echo "$review_message" >&2
-  elif ! field_has_concrete_value "$review_card_rollback"; then
-    review_message="Human Review Card rollback is missing or not concrete."
-    echo "$review_message" >&2
-  else
-    review_status="pass"
-  fi
-fi
-
-external_status="missing"
-external_reviewer=""
-external_source=""
-external_message="External acceptance status is unavailable."
-if declare -F workflow_external_acceptance_status >/dev/null 2>&1; then
-  external_row="$(workflow_external_acceptance_status "$review_file")"
-  IFS=$'\t' read -r external_status external_reviewer external_source external_message <<< "$external_row"
-fi
-card_external_status="$(normalize_status_token "$review_card_external")"
-case "$external_status" in
-  missing|unavailable|"")
-    case "$card_external_status" in
-      pass|manual_override|not_required)
-        external_status="$card_external_status"
-        external_message="Human Review Card external acceptance: $review_card_external"
-        ;;
-    esac
-    ;;
-esac
-
 status="fail"
 exit_code=1
-case "$external_status" in
-  pass|manual_override|not_required)
-    external_gate="pass"
-    ;;
-  *)
-    external_gate="fail"
-    ;;
-esac
-if [[ "$contract_exit" -eq 0 && "$review_status" == "pass" && "$external_gate" == "pass" && "$allowed_paths_status" == "pass" ]]; then
+if [[ "$contract_exit" -eq 0 && "$allowed_paths_status" == "pass" ]]; then
   status="pass"
   exit_code=0
 fi
@@ -456,10 +332,6 @@ fi
 if [[ -z "$failure_class" && "$status" != "pass" ]]; then
   if [[ "$contract_exit" -ne 0 ]]; then
     failure_class="contract"
-  elif [[ "$review_status" != "pass" ]]; then
-    failure_class="review"
-  elif [[ "$external_gate" != "pass" ]]; then
-    failure_class="external_acceptance"
   elif [[ "$allowed_paths_status" != "pass" ]]; then
     failure_class="allowed_paths"
   else
@@ -467,9 +339,9 @@ if [[ -z "$failure_class" && "$status" != "pass" ]]; then
   fi
 fi
 if [[ "$status" == "pass" ]]; then
-  next_step="finish contract worktree or archive completed task"
+  next_step="perform a fresh semantic impact review, then finish contract worktree or archive completed task"
 else
-  next_step="resolve failing contract, review, external acceptance, or allowed_paths gate"
+  next_step="resolve failing contract or allowed_paths evidence"
 fi
 handoff_current_exists=false
 handoff_resume_exists=false
@@ -492,17 +364,6 @@ if command -v jq >/dev/null 2>&1 && jq -e . "$contract_report" >/dev/null 2>&1;
     --arg contract_status "$([[ "$contract_exit" -eq 0 ]] && printf pass || printf fail)" \
     --arg contract_command "$contract_command" \
     --argjson contract_exit "$contract_exit" \
-    --arg review_file "${review_file:-}" \
-    --arg review_status "$review_status" \
-    --arg review_message "$review_message" \
-    --arg review_card_verdict "$review_card_verdict" \
-    --arg review_card_change_type "$review_card_change_type" \
-    --arg review_card_external "$review_card_external" \
-    --arg review_card_rollback "$review_card_rollback" \
-    --arg external_status "$external_status" \
-    --arg external_reviewer "$external_reviewer" \
-    --arg external_source "$external_source" \
-    --arg external_message "$external_message" \
     --arg worktree "$worktree_path" \
     --arg branch "$branch_name" \
     --arg diff_base_ref "$diff_base_ref" \
@@ -538,8 +399,6 @@ if command -v jq >/dev/null 2>&1 && jq -e . "$contract_report" >/dev/null 2>&1;
       ],
       guards: [
         {name: "contract", status: $contract_status},
-        {name: "review", status: $review_status},
-        {name: "external_acceptance", status: $external_status},
         {name: "allowed_paths", status: ($allowed_paths_check.status // "unavailable")}
       ],
       handoffs: [
@@ -563,23 +422,6 @@ if command -v jq >/dev/null 2>&1 && jq -e . "$contract_report" >/dev/null 2>&1;
         report: ($contract_report[0] // {}),
         task_profile: $task_profile,
         allowed_paths: $allowed_paths
-      },
-      review: {
-        file: $review_file,
-        status: $review_status,
-        message: $review_message,
-        card: {
-          verdict: $review_card_verdict,
-          change_type: $review_card_change_type,
-          external_acceptance: $review_card_external,
-          rollback: $review_card_rollback
-        }
-      },
-      external_acceptance: {
-        status: $external_status,
-        reviewer: $external_reviewer,
-        source: $external_source,
-        message: $external_message
       }
     }' > "$checks_report"
 else
@@ -617,8 +459,6 @@ else
   ],
   "guards": [
     {"name": "contract", "status": "$([[ "$contract_exit" -eq 0 ]] && printf pass || printf fail)"},
-    {"name": "review", "status": "$(json_escape "$review_status")"},
-    {"name": "external_acceptance", "status": "$(json_escape "$external_status")"},
     {"name": "allowed_paths", "status": "$(json_escape "$allowed_paths_status")"}
   ],
   "handoffs": [
@@ -644,23 +484,6 @@ else
     "exit_code": $contract_exit,
     "task_profile": "$(json_escape "$task_profile")",
     "allowed_paths": []
-  },
-  "review": {
-    "file": "$(json_escape "${review_file:-}")",
-    "status": "$(json_escape "$review_status")",
-    "message": "$(json_escape "$review_message")",
-    "card": {
-      "verdict": "$(json_escape "$review_card_verdict")",
-      "change_type": "$(json_escape "$review_card_change_type")",
-      "external_acceptance": "$(json_escape "$review_card_external")",
-      "rollback": "$(json_escape "$review_card_rollback")"
-    }
-  },
-  "external_acceptance": {
-    "status": "$(json_escape "$external_status")",
-    "reviewer": "$(json_escape "$external_reviewer")",
-    "source": "$(json_escape "$external_source")",
-    "message": "$(json_escape "$external_message")"
   }
 }
 EOF_CHECKS

package/scripts/workflow-contract.ts

@@ -185,11 +185,7 @@ export function getHelperScripts(contract: WorkflowContract): string[] {
 }
 
 export function getHelperRuntimeDir(contract: WorkflowContract): string {
-  return (
-    contract.helpers.runtimeDirectory ??
-    contract.helpers.compatibilityDirectory ??
-    "scripts"
-  );
+  return contract.helpers.runtimeDirectory ?? contract.helpers.compatibilityDirectory ?? "scripts";
 }
 
 export function getRequiredDirectories(contract: WorkflowContract): string[] {

package/src/cli/commands/init-hook.ts

@@ -17,7 +17,7 @@ import { Command } from 'commander';
 import { runDoctor, type CheckStatus, type DoctorReport } from './doctor';
 import { runStatus, type StatusReport } from './status';
 import { runMcpSetupChatgpt } from '../mcp/setup';
-import { resolveRepoPreferredControllerHome } from '../repositories/controller-home';
+import { resolveControllerHome } from '../repositories/controller-home';
 import {
   configureSetupProfile,
   detectSetupPlatform,
@@ -791,7 +791,7 @@ export function openSetupSession(options: SetupSessionOptions = {}): SetupSessio
   const platform = options.platform ?? detectSetupPlatform({ env: options.env });
   const target = options.target ?? setupHostTarget(profile);
   const report = options.report ?? runInitHook({ ...options, target });
-  const controllerHome = resolveRepoPreferredControllerHome(options.cwd ?? process.cwd(), options.controllerHome);
+  const controllerHome = resolveControllerHome(options.controllerHome);
   const nextAction = profileNextAction(profile, platform, { controllerHome, accountHome: options.accountHome }) ?? report.agent_actions[0];
   const now = (options.now ?? (() => new Date()))().toISOString();
   const reuse = previous && previous.status !== 'closed';
@@ -1010,4 +1010,4 @@ export function buildSetupCommand(): Command {
     });
 
   return command;
-}
+}

package/src/cli/commands/mcp.ts

@@ -28,7 +28,7 @@ export interface McpServeOptions {
   devRunnerAgents?: string;
   devRunnerTimeoutMs?: string;
   devRunnerMaxTimeoutMs?: string;
-  toolset?: 'core' | 'advanced' | 'full';
+  toolset?: 'facade' | 'core' | 'advanced' | 'full';
 }
 
 interface McpAccessOptions {
@@ -161,14 +161,14 @@ export function buildMcpCommand(): Command {
   mcp
     .command('serve')
     .description('Start the forge MCP server')
-    .option('--repo <path>', 'Repository root to expose through the selected MCP profile', '.')
+    .option('--repo <path>', 'Repository root to expose through the selected MCP profile')
     .option('--controller-home <path>', 'Controller state root; defaults to repo _ops/controller-home when present')
     .option('--transport <transport>', 'Transport: stdio|http', 'stdio')
     .option('--host <host>', 'HTTP bind host', '127.0.0.1')
     .option('--port <port>', 'HTTP bind port', '8765')
     .option('--profile <profile>', 'MCP profile: planner|executor|orchestrator|controller', 'controller')
-    .option('--toolset <toolset>', 'Controller toolset: core|advanced|full (default core; advanced/full are explicit compatibility profiles)')
-    .option('--auth <mode>', 'HTTP auth mode: oauth|bearer', 'oauth')
+    .option('--toolset <toolset>', 'Controller toolset: facade|core|advanced|full (default advanced; facade is an explicit five-tool ChatGPT surface)')
+    .option('--auth <mode>', 'HTTP auth mode: oauth|bearer|none', 'oauth')
     .option('--enable-chatgpt-browser', 'Expose tools that operate the user logged-in ChatGPT Web browser session')
     .option('--enable-dev-runner', 'Enable local Codex/Claude task runners for controller or orchestrator profiles')
     .option('--dev-runner-agents <agents>', 'Comma-separated dev runner agents: codex,claude')
@@ -181,7 +181,11 @@ export function buildMcpCommand(): Command {
         const devRunnerMaxTimeoutMs = parsePositiveIntegerOption('dev-runner-max-timeout-ms', rawOpts.devRunnerMaxTimeoutMs);
         if (rawOpts.transport === 'stdio') {
           await startMcpStdio({
-            repo: rawOpts.repo,
+            // stdio preserves its historical current-directory default.
+            // The HTTP controller Gateway deliberately leaves this unset so
+            // it can serve Controller Home without registering a launchd
+            // working directory as a repository.
+            repo: rawOpts.repo ?? '.',
             controllerHome: rawOpts.controllerHome,
             profile: rawOpts.profile,
             toolset: rawOpts.toolset,

package/src/cli/commands/plugin.ts

@@ -63,7 +63,7 @@ export function installerNextSteps(result:Record<string,unknown>):string[]{
     .filter(Boolean)
     .slice(0,10);
 }
-function registrationFrom(result:Record<string,unknown>,entry:RegistryEntry):ExternalPluginRegistrationInput{
+export function registrationFrom(result:Record<string,unknown>,entry:RegistryEntry):ExternalPluginRegistrationInput{
   if(result.registration){const input=result.registration as ExternalPluginRegistrationInput;if(input.pluginId!==entry.id)throw new Error('PLUGIN_INSTALLER_ID_MISMATCH');if(input.pluginVersion!==entry.version)throw new Error('PLUGIN_INSTALLER_VERSION_MISMATCH');return input;}
   const facts=result.providerInstall as Record<string,unknown>|undefined;
   if(!facts||facts.kind!=='desktop_operator'||entry.id!=='desktop_operator')throw new Error('PLUGIN_INSTALLER_REGISTRATION_MISSING');

package/src/cli/commands/recovery.ts

@@ -310,7 +310,10 @@ export async function verifyRecoveryConnector(
       body: initializeBody,
     });
     const challenge = response.headers.get('www-authenticate') ?? '';
-    const ok = response.status === 401 && /\bBearer\b/i.test(challenge) && challenge.includes('oauth-protected-resource');
+    const ok = response.status === 401
+      && /\bBearer\b/i.test(challenge)
+      && challenge.includes('error="invalid_token"')
+      && challenge.includes('oauth-protected-resource');
     probes.unauthenticatedChallenge = { ok, status: response.status };
     if (!ok) failures.push('unauthenticatedChallenge: Recovery MCP did not return the expected OAuth Bearer challenge.');
   } catch (error) {
@@ -514,11 +517,15 @@ export function buildRecoveryCommand(): Command {
       const home = resolveControllerHome(opts.controllerHome);
       const repoRoot = resolve(opts.repo);
       const current = loadRecoveryConfig(home);
-      const primaryConnectorService = launchdService(
+      const primaryConnectorBase = launchdService(
         opts.primaryConnectorServiceLabel,
         opts.primaryConnectorServicePlist,
         'RECOVERY_PRIMARY_CONNECTOR',
       ) as PrimaryConnectorServiceConfig;
+      const primaryConnectorService: PrimaryConnectorServiceConfig = {
+        ...primaryConnectorBase,
+        ...(current.primaryConnectorService?.localMcpUrl ? { localMcpUrl: current.primaryConnectorService.localMcpUrl } : {}),
+      };
       const installed = await installStandaloneRecovery({
         controllerHome: home,
         repoRoot,
@@ -526,6 +533,7 @@ export function buildRecoveryCommand(): Command {
         publicMcpUrl: current.publicMcpUrl,
         recoveryPublicUrl: current.recoveryPublicUrl,
         recoveryTunnelService: current.recoveryTunnelService,
+        primaryPublicTunnelService: current.primaryPublicTunnelService,
         primaryRuntimeService: current.primaryRuntimeService ?? { platform: 'launchd' },
         primaryConnectorService,
       });
@@ -622,6 +630,9 @@ export function buildRecoveryCommand(): Command {
     .option('--recovery-tunnel-service-plist <path>', 'Absolute Recovery tunnel launchd plist path')
     .option('--primary-connector-service-label <label>', 'Primary OAuth/Connector launchd label managed by standalone Recovery')
     .option('--primary-connector-service-plist <path>', 'Absolute primary OAuth/Connector launchd plist path')
+    .option('--primary-connector-local-url <url>', 'Local primary OAuth/Connector MCP endpoint used to distinguish Connector from tunnel failures')
+    .option('--primary-tunnel-service-label <label>', 'Primary public MCP tunnel launchd label managed by standalone Recovery')
+    .option('--primary-tunnel-service-plist <path>', 'Absolute primary public MCP tunnel launchd plist path')
     .option('--stage-only', 'Build and canary the Recovery release without activating services')
     .action(async (opts: {
       controllerHome: string;
@@ -632,13 +643,23 @@ export function buildRecoveryCommand(): Command {
       recoveryTunnelServicePlist?: string;
       primaryConnectorServiceLabel?: string;
       primaryConnectorServicePlist?: string;
+      primaryConnectorLocalUrl?: string;
+      primaryTunnelServiceLabel?: string;
+      primaryTunnelServicePlist?: string;
       stageOnly?: boolean;
     }) => {
       const home = resolveControllerHome(opts.controllerHome);
       const port = Number(opts.port);
       if (!Number.isInteger(port) || port < 1024 || port > 65535) throw new Error('RECOVERY_PORT_INVALID');
       const recoveryTunnelService = launchdService(opts.recoveryTunnelServiceLabel, opts.recoveryTunnelServicePlist, 'RECOVERY_TUNNEL') as PublicTunnelServiceConfig | undefined;
-      const primaryConnectorService = launchdService(opts.primaryConnectorServiceLabel, opts.primaryConnectorServicePlist, 'RECOVERY_PRIMARY_CONNECTOR') as PrimaryConnectorServiceConfig | undefined;
+      const primaryConnectorBase = launchdService(opts.primaryConnectorServiceLabel, opts.primaryConnectorServicePlist, 'RECOVERY_PRIMARY_CONNECTOR') as PrimaryConnectorServiceConfig | undefined;
+      const primaryConnectorLocalUrl = endpoint(opts.primaryConnectorLocalUrl, 'RECOVERY_PRIMARY_CONNECTOR_LOCAL_URL');
+      if (primaryConnectorLocalUrl && !primaryConnectorBase) throw new Error('RECOVERY_PRIMARY_CONNECTOR_LABEL_REQUIRED_FOR_LOCAL_URL');
+      const primaryConnectorService = primaryConnectorBase
+        ? { ...primaryConnectorBase, ...(primaryConnectorLocalUrl ? { localMcpUrl: primaryConnectorLocalUrl } : {}) }
+        : undefined;
+      const primaryPublicTunnelService = launchdService(opts.primaryTunnelServiceLabel, opts.primaryTunnelServicePlist, 'RECOVERY_PRIMARY_TUNNEL') as PublicTunnelServiceConfig | undefined;
+      if (primaryPublicTunnelService && !primaryConnectorService) throw new Error('RECOVERY_PRIMARY_CONNECTOR_REQUIRED_FOR_PRIMARY_TUNNEL');
       const recoveryPublicUrl = endpoint(opts.recoveryPublicUrl, 'RECOVERY_PUBLIC_URL');
       if (Boolean(recoveryTunnelService) !== Boolean(recoveryPublicUrl)) {
         throw new Error('RECOVERY_PUBLIC_URL_AND_TUNNEL_SERVICE_MUST_BE_CONFIGURED_TOGETHER');
@@ -653,6 +674,7 @@ export function buildRecoveryCommand(): Command {
         publicMcpUrl: endpoint(opts.publicMcpUrl, 'PUBLIC_MCP_URL'),
         recoveryPublicUrl,
         recoveryTunnelService,
+        primaryPublicTunnelService,
         primaryConnectorService,
       });
       output({

package/src/cli/commands/runtime.ts

@@ -13,8 +13,14 @@ import { observeRuntimeStatus } from '../../runtime/root/status';
 import { readMcpServiceBearerToken } from '../mcp/auth';
 import { publishRuntimeRelease } from '../../runtime/root/release-store';
 import { installForgeRuntimeService } from '../../runtime/root/service';
-import { installPackageRuntimeService } from '../../runtime/root/package-runtime-service';
+import { activateScheduledPackageRuntimeServiceFromPath, installPackageRuntimeService, readPackageRuntimeActivationReceipt } from '../../runtime/root/package-runtime-service';
 import { assertRuntimeReleaseFiles, stageRuntimeReleaseFromCandidateSource } from '../../runtime/root/release-materialize';
+import {
+  applyControllerHomeMigration,
+  previewControllerHomeMigration,
+  rollbackControllerHomeMigration,
+  archiveUnroutableMigratedWork,
+} from '../../runtime/control-plane/persistence/controller-home-migration';
 
 function output(value: unknown, json = true): void {
   console.log(json ? JSON.stringify(value, null, 2) : String(value));
@@ -30,6 +36,22 @@ export function buildRuntimeCommand(): Command {
   const service = command.command('service')
     .description('Install or inspect the user-level Forge Runtime owner');
 
+  service.command('activate-package', { hidden: true })
+    .description('Internal one-shot activation helper for a staged package Runtime release')
+    .requiredOption('--request <path>', 'Activation request path')
+    .action(async (opts: { request: string }) => {
+      output(await activateScheduledPackageRuntimeServiceFromPath(opts.request));
+    });
+
+  service.command('activation-status')
+    .description('Read a durable package Runtime activation receipt')
+    .requiredOption('--receipt <path>', 'Activation receipt path returned by install-package')
+    .action((opts: { receipt: string }) => {
+      const receipt = readPackageRuntimeActivationReceipt(resolve(opts.receipt));
+      if (!receipt) throw new Error('RUNTIME_PACKAGE_ACTIVATION_RECEIPT_NOT_FOUND');
+      output(receipt);
+    });
+
   service.command('install-package')
     .description('Install the current packaged Forge Runtime without requiring a Git checkout, Bun compilation, CodeGraph, or Standalone Recovery')
     .option('--controller-home <path>', 'Controller Home; defaults to the user-level Forge Controller Home')
@@ -37,7 +59,8 @@ export function buildRuntimeCommand(): Command {
     .option('--port <port>', 'MCP listener port', '8765')
     .option('--auth-token-file <path>', 'Raw bearer token file (created from user-level MCP config when missing)')
     .option('--portable', 'Force a detached session process instead of launchd/systemd user persistence')
-    .action(async (opts: { controllerHome?: string; host: string; port: string; authTokenFile?: string; portable?: boolean }) => {
+    .option('--refresh-connector', 'Explicitly replace/restart the persistent public MCP Gateway instead of reusing a healthy existing Gateway')
+    .action(async (opts: { controllerHome?: string; host: string; port: string; authTokenFile?: string; portable?: boolean; refreshConnector?: boolean }) => {
       const home = resolveControllerHome(opts.controllerHome);
       const port = Number(opts.port);
       if (!Number.isInteger(port) || port < 1 || port > 65_535) throw new Error('RUNTIME_SERVICE_PORT_INVALID');
@@ -56,6 +79,7 @@ export function buildRuntimeCommand(): Command {
         port,
         authTokenFile: tokenPath,
         forcePortable: opts.portable === true,
+        refreshConnector: opts.refreshConnector === true,
       });
       output({
         status: result.status,
@@ -73,8 +97,11 @@ export function buildRuntimeCommand(): Command {
         servicePath: result.servicePath,
         pid: result.pid,
         connector: result.connector,
+        activation: result.activation,
         warnings: result.warnings,
-        next: `forge runtime status --controller-home ${home}`,
+        next: result.activation
+          ? `forge runtime service activation-status --receipt ${result.activation.receiptPath}`
+          : `forge runtime status --controller-home ${home}`,
       });
     });
 
@@ -163,6 +190,31 @@ export function buildRuntimeCommand(): Command {
       });
     });
 
+  command.command('migrate-controller-home')
+    .description('Preview or transactionally migrate non-terminal business state from an explicitly selected retired Controller Home')
+    .requiredOption('--source <path>', 'Retired Controller Home to inspect; repository presence never selects this implicitly')
+    .option('--destination <path>', 'Canonical Controller Home; defaults to the installed user-level authority')
+    .option('--apply', 'Apply the reviewed migration and freeze the source SQLite as a read-only archive')
+    .option('--rollback <migration-id>', 'Rollback one migration only when none of its imported records changed')
+    .option('--archive-unroutable <migration-id>', 'Archive imported nonterminal Work whose repository is not registered in the canonical Home')
+    .action(async (opts: { source: string; destination?: string; apply?: boolean; rollback?: string; archiveUnroutable?: string }) => {
+      const destination = resolveControllerHome(opts.destination);
+      if (opts.archiveUnroutable?.trim()) {
+        output(archiveUnroutableMigratedWork({ destinationHome: destination, migrationId: opts.archiveUnroutable.trim() }));
+        return;
+      }
+      if (opts.rollback?.trim()) {
+        output(rollbackControllerHomeMigration({ destinationHome: destination, migrationId: opts.rollback.trim() }));
+        return;
+      }
+      const input = { sourceHome: resolve(opts.source), destinationHome: destination };
+      if (opts.apply === true) {
+        output(await applyControllerHomeMigration(input));
+        return;
+      }
+      output(await previewControllerHomeMigration(input));
+    });
+
   command.command('status')
     .description('Read the Runtime Root status projection, active durable Jobs, and materialized repository projections')
     .requiredOption('--controller-home <path>', 'Explicit Controller Home')

package/src/cli/commands/security.ts

@@ -8,7 +8,7 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import { execFileSync } from 'child_process';
-import { MANAGED_TAG, type HookEntry } from '../installer/managed-entries';
+import { MANAGED_TAG, isLegacyRepoHarnessCommand, type HookEntry } from '../installer/managed-entries';
 
 export type SecurityStatus = 'ok' | 'warn' | 'fail';
 export type SecuritySeverity = 'warn' | 'high' | 'fail';
@@ -273,6 +273,17 @@ function scanHookConfig(
     if (!command) continue;
     const suspicious = suspiciousMatch(command);
     if (command.includes(MANAGED_TAG) && suspicious === null) continue;
+    if (isLegacyRepoHarnessCommand(command)) {
+      findings.push({
+        filePath,
+        ruleId: 'legacy-repo-harness-hook-adapter',
+        severity: 'warn',
+        summary: `${hostLabel} ${event} hook uses the retired repo-harness adapter`,
+        recommendation: 'Run forge install --target codex --location global to replace retired adapters with forge-hook.',
+        command,
+      });
+      continue;
+    }
     findings.push({
       filePath,
       ruleId: suspicious?.ruleId ?? 'unmanaged-hook-command',