@moretea-labs/forge 1.5.1 → 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/chatgpt.ts

@@ -13,7 +13,11 @@ import {
 } from '../chatgpt-browser/engine';
 import type { BrowserProviderName, BrowserSessionStatus, NativeBrowserChannel, ThinkingLevel } from '../chatgpt-browser/types';
 import { durableControllerHome } from '../repositories/controller-home';
-import { runWorkChatgptContinuation } from '../../runtime/control-plane/launcher/chatgpt-work-continuation';
+import {
+  runWorkChatgptContinuation,
+  type ChatgptAutomationReasoning,
+  type ChatgptAutomationTabPolicy,
+} from '../../runtime/control-plane/launcher/chatgpt-work-continuation';
 
 interface BrowserCommonOptions {
   repo?: string;
@@ -84,6 +88,9 @@ interface WorkChatgptContinueOptions extends BrowserCommonOptions {
   title?: string;
   session?: string;
   conversationUrl?: string;
+  model?: string;
+  reasoning?: string;
+  tabPolicy?: string;
   timeoutMs?: string;
 }
 
@@ -109,6 +116,18 @@ interface BrowserFollowupOptions extends BrowserCommonOptions {
   oracleBin?: string;
 }
 
+function parseAutomationReasoning(value?: string): ChatgptAutomationReasoning | undefined {
+  if (value === undefined) return undefined;
+  if (value === 'medium' || value === 'high' || value === 'xhigh') return value;
+  throw new Error(`invalid --reasoning "${value}" (expected: medium, high, xhigh)`);
+}
+
+function parseAutomationTabPolicy(value?: string): ChatgptAutomationTabPolicy | undefined {
+  if (value === undefined) return undefined;
+  if (value === 'auto' || value === 'reuse' || value === 'new') return value;
+  throw new Error(`invalid --tab-policy "${value}" (expected: auto, reuse, new)`);
+}
+
 function parseProvider(value?: string): BrowserProviderName {
   if (value === undefined || value === 'oracle') return 'oracle';
   if (value === 'native') return 'native';
@@ -384,8 +403,11 @@ export function buildChatgptCommand(): Command {
     .requiredOption('--work-id <work-id>', 'Stable Forge Work id')
     .requiredOption('--prompt <text>', 'Bounded continuation prompt')
     .option('--title <title>', 'Human-readable local conversation alias')
-    .option('--session <session-id>', 'Legacy saved browser session to seed the binding')
+    .option('--session <session-id>', 'Saved browser session to seed or resume the Work binding')
     .option('--conversation-url <url>', 'Explicit ChatGPT conversation URL to seed the binding')
+    .option('--model <label>', 'Requested ChatGPT automation model', 'gpt-5.6')
+    .option('--reasoning <level>', 'Reasoning level: medium|high|xhigh', 'high')
+    .option('--tab-policy <policy>', 'Browser tab policy: auto|reuse|new', 'auto')
     .option('--timeout-ms <ms>', 'Assistant timeout in milliseconds')
     .action((rawOpts: WorkChatgptContinueOptions) => {
       void runChatgptAction(async () => {
@@ -398,6 +420,9 @@ export function buildChatgptCommand(): Command {
           title: rawOpts.title,
           browserSessionId: rawOpts.session,
           conversationUrl: rawOpts.conversationUrl,
+          model: rawOpts.model,
+          reasoning: parseAutomationReasoning(rawOpts.reasoning),
+          tabPolicy: parseAutomationTabPolicy(rawOpts.tabPolicy),
           timeoutMs: parsePositiveInteger('timeout-ms', rawOpts.timeoutMs),
         });
         console.log(JSON.stringify({
@@ -408,6 +433,10 @@ export function buildChatgptCommand(): Command {
           conversationId: result.conversationId,
           localAlias: result.localAlias,
           resumedFromBinding: result.resumedFromBinding,
+          model: result.model,
+          reasoning: result.reasoning,
+          tabPolicy: result.tabPolicy,
+          executionPreferenceVerified: result.executionPreferenceVerified,
           error: result.error,
         }, null, 2));
       });

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

@@ -5,11 +5,11 @@ import { dirname, isAbsolute, join, resolve, sep } from 'path';
 import { fileURLToPath } from 'url';
 import { Command } from 'commander';
 import { resolveControllerHome, controllerSystemRoot } from '../repositories/controller-home';
-import { installExternalPluginRegistration, listExternalPluginRegistrations, type ExternalPluginRegistrationInput } from '../../runtime/plugins/external-registration';
+import { installExternalPluginRegistration, listExternalPluginRegistrations, type ExternalPluginRegistration, type ExternalPluginRegistrationInput } from '../../runtime/plugins/external-registration';
 import { createDesktopOperatorRegistrationInput } from '../../runtime/plugins/desktop-operator-registration';
 import { controllerPluginRepository, getAssistantPluginManifest, syncAssistantPluginRegistry } from '../../runtime/plugins/store';
 
-interface RegistryEntry { id:string; name:string; version:string; description:string; repository:string; ref:string; installer:string; platforms:NodeJS.Platform[]; }
+export interface RegistryEntry { id:string; name:string; version:string; description:string; repository:string; ref:string; installer:string; providerVersion?:string; protocolVersion?:string; platforms:NodeJS.Platform[]; }
 interface Registry { schemaVersion:1; plugins:RegistryEntry[]; }
 interface CliOptions { json?:boolean; controllerHome?:string; refresh?:boolean; }
 const packageRoot=resolve(dirname(fileURLToPath(import.meta.url)),'../../..');
@@ -24,11 +24,26 @@ function registry():Registry{
     if(!plugin.repository.startsWith('https://github.com/moretea-labs/')||!plugin.repository.endsWith('.git'))throw new Error(`PLUGIN_CATALOG_UNTRUSTED_REPOSITORY: ${plugin.id}`);
     if(!/^v\d+\.\d+\.\d+(?:[-+][A-Za-z0-9.-]+)?$/.test(plugin.ref))throw new Error(`PLUGIN_CATALOG_UNPINNED_REF: ${plugin.id}`);
     if(plugin.installer!=='forge-plugin-install.mjs')throw new Error(`PLUGIN_CATALOG_INSTALLER_INVALID: ${plugin.id}`);
+    if(plugin.providerVersion!==undefined&&!/^\d+\.\d+\.\d+(?:[-+][A-Za-z0-9.-]+)?$/.test(plugin.providerVersion))throw new Error(`PLUGIN_CATALOG_PROVIDER_VERSION_INVALID: ${plugin.id}`);
+    if(plugin.protocolVersion!==undefined&&!/^\d+\.\d+$/.test(plugin.protocolVersion))throw new Error(`PLUGIN_CATALOG_PROTOCOL_VERSION_INVALID: ${plugin.id}`);
     ids.add(plugin.id);
   }
   return value;
 }
 function within(root:string,relative:string):string{const target=resolve(root,relative);const base=`${resolve(root)}${sep}`;if(target!==resolve(root)&&!target.startsWith(base))throw new Error('PLUGIN_INSTALL_PATH_ESCAPE');return target;}
+export function pluginCatalogCompatibility(entry:RegistryEntry,platform:NodeJS.Platform=process.platform):{compatible:boolean;reason?:string}{
+  if(!entry.platforms.includes(platform))return{compatible:false,reason:`unsupported platform: ${platform}`};
+  if(entry.providerVersion&&entry.providerVersion!==entry.version)return{compatible:false,reason:`catalog version ${entry.version} does not match pinned provider version ${entry.providerVersion}`};
+  return{compatible:true};
+}
+export function officialPluginCatalogItems(platform:NodeJS.Platform=process.platform){return registry().plugins.map(entry=>({...entry,...pluginCatalogCompatibility(entry,platform)}));}
+export function externalPluginListItem(controllerHome:string,registration:ExternalPluginRegistration){
+  const base={pluginId:registration.pluginId,version:registration.pluginVersion,provider:registration.provider,enabled:registration.enabled,scope:registration.scope,transport:registration.transport.kind};
+  if(registration.scope==='repository')return{...base,healthScope:'repository_context_required' as const};
+  const repository=controllerPluginRepository(controllerHome);
+  try{return{...base,health:getAssistantPluginManifest(controllerHome,repository,registration.pluginId).health};}
+  catch(error){return{...base,health:{state:'error',message:error instanceof Error?error.message:String(error)}};}
+}
 function run(command:string,args:string[],cwd:string,timeoutMs=120000):string{
   const result=spawnSync(command,args,{cwd,encoding:'utf8',timeout:timeoutMs,maxBuffer:32*1024*1024,shell:false,windowsHide:true});
   if(result.error)throw new Error(`PLUGIN_INSTALL_COMMAND_FAILED: ${result.error.message}`);
@@ -40,17 +55,29 @@ function installerJson(stdout:string):Record<string,unknown>{
   for(let i=lines.length-1;i>=0;i--){try{const x=JSON.parse(lines[i]);if(x&&typeof x==='object'&&!Array.isArray(x)&&x.schemaVersion===1)return x;}catch{}}
   throw new Error('PLUGIN_INSTALLER_OUTPUT_INVALID');
 }
-function registrationFrom(result:Record<string,unknown>,entry:RegistryEntry):ExternalPluginRegistrationInput{
+export function installerNextSteps(result:Record<string,unknown>):string[]{
+  if(!Array.isArray(result.nextSteps))return[];
+  return result.nextSteps
+    .filter((value):value is string=>typeof value==='string')
+    .map(value=>value.replace(/[\u0000-\u001F\u007F]/g,' ').trim().slice(0,1000))
+    .filter(Boolean)
+    .slice(0,10);
+}
+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');
-  if(facts.pluginVersion!==entry.version||facts.protocolVersion!=='1.0')throw new Error('PLUGIN_INSTALLER_PROVIDER_VERSION_MISMATCH');
+  const expectedProviderVersion=entry.providerVersion??entry.version;
+  const expectedProtocolVersion=entry.protocolVersion??'1.0';
+  if(facts.pluginVersion!==expectedProviderVersion)throw new Error(`PLUGIN_INSTALLER_PROVIDER_VERSION_MISMATCH: expected ${expectedProviderVersion} for ${entry.id}@${entry.version}, actual ${String(facts.pluginVersion??'missing')}`);
+  if(facts.protocolVersion!==expectedProtocolVersion)throw new Error(`PLUGIN_INSTALLER_PROTOCOL_VERSION_MISMATCH: expected ${expectedProtocolVersion} for ${entry.id}@${entry.version}, actual ${String(facts.protocolVersion??'missing')}`);
   const socketPath=typeof facts.socketPath==='string'?facts.socketPath:'';const launchAgentLabel=typeof facts.launchAgentLabel==='string'?facts.launchAgentLabel:'';const expectedProgramContains=typeof facts.expectedProgramContains==='string'?facts.expectedProgramContains:'';
   if(!isAbsolute(socketPath)||!launchAgentLabel||!expectedProgramContains)throw new Error('PLUGIN_INSTALLER_PROVIDER_FACTS_INVALID');
-  return createDesktopOperatorRegistrationInput({socketPath,launchAgentLabel,expectedProgramContains,pluginVersion:entry.version,protocolVersion:'1.0'});
+  return createDesktopOperatorRegistrationInput({socketPath,launchAgentLabel,expectedProgramContains,pluginVersion:expectedProviderVersion,protocolVersion:expectedProtocolVersion});
 }
 function install(entry:RegistryEntry,controllerHome:string):Record<string,unknown>{
-  if(!entry.platforms.includes(process.platform))throw new Error(`PLUGIN_PLATFORM_UNSUPPORTED: ${entry.id}/${process.platform}`);
+  const compatibility=pluginCatalogCompatibility(entry,process.platform);
+  if(!compatibility.compatible)throw new Error(`PLUGIN_CATALOG_INCOMPATIBLE: ${entry.id}@${entry.version}: ${compatibility.reason}`);
   const packagesRoot=join(controllerSystemRoot(controllerHome),'plugins','packages');mkdirSync(packagesRoot,{recursive:true,mode:0o700});
   const finalRoot=join(packagesRoot,entry.id),stage=join(packagesRoot,`.${entry.id}.${randomUUID()}.staging`),backup=join(packagesRoot,`.${entry.id}.${randomUUID()}.backup`);let backed=false;
   try{
@@ -62,13 +89,13 @@ function install(entry:RegistryEntry,controllerHome:string):Record<string,unknow
     const installed=installExternalPluginRegistration(controllerHome,registrationFrom(result,entry));
     const repository=controllerPluginRepository(controllerHome);syncAssistantPluginRegistry(controllerHome,repository);const plugin=getAssistantPluginManifest(controllerHome,repository,entry.id);
     if(backed)rmSync(backup,{recursive:true,force:true});
-    return{pluginId:entry.id,version:entry.version,packageRoot:finalRoot,registrationRevision:installed.revision,enabled:plugin.enabled,health:plugin.health};
+    return{pluginId:entry.id,version:entry.version,packageRoot:finalRoot,registrationRevision:installed.revision,enabled:plugin.enabled,health:plugin.health,nextSteps:installerNextSteps(result)};
   }catch(error){rmSync(stage,{recursive:true,force:true});if(backed&&existsSync(finalRoot))rmSync(finalRoot,{recursive:true,force:true});if(backed&&existsSync(backup))renameSync(backup,finalRoot);throw error;}
 }
 export function buildPluginCommand():Command{
   const root=new Command('plugin').description('Discover and install trusted Forge plugins');
-  root.command('catalog').description('List official plugins').option('--json','Output JSON').action((o:CliOptions)=>{const items=registry().plugins.map(x=>({...x,compatible:x.platforms.includes(process.platform)}));if(o.json)console.log(JSON.stringify({schemaVersion:1,platform:process.platform,plugins:items},null,2));else items.forEach(x=>console.log(`${x.id}\t${x.version}\t${x.compatible?'compatible':'unsupported'}\t${x.name}`));});
-  root.command('list').description('List installed external plugins').option('--json','Output JSON').option('--controller-home <path>','Override Controller Home').option('--refresh','Probe providers').action((o:CliOptions)=>{const home=resolveControllerHome(o.controllerHome),repo=controllerPluginRepository(home);if(o.refresh)syncAssistantPluginRegistry(home,repo);const items=listExternalPluginRegistrations(home).map(r=>{let health:unknown;try{health=getAssistantPluginManifest(home,repo,r.pluginId).health;}catch(e){health={state:'error',message:e instanceof Error?e.message:String(e)};}return{pluginId:r.pluginId,version:r.pluginVersion,provider:r.provider,enabled:r.enabled,transport:r.transport.kind,health};});if(o.json)console.log(JSON.stringify({schemaVersion:1,plugins:items},null,2));else if(!items.length)console.log('No external Forge plugins installed.');else items.forEach(x=>console.log(`${x.pluginId}\t${x.version}\t${x.enabled?'enabled':'disabled'}\t${(x.health as {state?:string})?.state??'unknown'}`));});
-  root.command('install <plugin-id>').description('Install/update an official plugin from a pinned public release').option('--json','Output JSON').option('--controller-home <path>','Override Controller Home').action((id:string,o:CliOptions)=>{const entry=registry().plugins.find(x=>x.id===id);if(!entry)throw new Error(`PLUGIN_NOT_IN_OFFICIAL_CATALOG: ${id}`);const result=install(entry,resolveControllerHome(o.controllerHome));if(o.json)console.log(JSON.stringify(result,null,2));else console.log(`Installed ${entry.name} ${entry.version} (${(result.health as {state?:string})?.state??'unknown'}).`);});
+  root.command('catalog').description('List official plugins').option('--json','Output JSON').action((o:CliOptions)=>{const items=officialPluginCatalogItems();if(o.json)console.log(JSON.stringify({schemaVersion:1,platform:process.platform,plugins:items},null,2));else items.forEach(x=>console.log(`${x.id}\t${x.version}\t${x.compatible?'compatible':`incompatible (${x.reason})`}\t${x.name}`));});
+  root.command('list').description('List installed external plugins').option('--json','Output JSON').option('--controller-home <path>','Override Controller Home').option('--refresh','Probe controller-scoped providers').action((o:CliOptions)=>{const home=resolveControllerHome(o.controllerHome),repo=controllerPluginRepository(home);if(o.refresh)syncAssistantPluginRegistry(home,repo);const items=listExternalPluginRegistrations(home).map(r=>externalPluginListItem(home,r));if(o.json)console.log(JSON.stringify({schemaVersion:1,plugins:items},null,2));else if(!items.length)console.log('No external Forge plugins installed.');else items.forEach(x=>console.log(`${x.pluginId}\t${x.version}\t${x.enabled?'enabled':'disabled'}\t${'healthScope' in x?'repository-context-required':((x.health as {state?:string})?.state??'unknown')}`));});
+  root.command('install <plugin-id>').description('Install/update an official plugin from a pinned public release').option('--json','Output JSON').option('--controller-home <path>','Override Controller Home').action((id:string,o:CliOptions)=>{const entry=registry().plugins.find(x=>x.id===id);if(!entry)throw new Error(`PLUGIN_NOT_IN_OFFICIAL_CATALOG: ${id}`);const result=install(entry,resolveControllerHome(o.controllerHome));if(o.json)console.log(JSON.stringify(result,null,2));else{console.log(`Installed ${entry.name} ${entry.version} (${(result.health as {state?:string})?.state??'unknown'}).`);for(const step of (result.nextSteps as string[]|undefined)??[])console.log(`- ${step}`);}});
   return root;
 }

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({