@moretea-labs/forge 1.6.0 → 1.7.1

package/scripts/workflow-contract.ts

@@ -1,206 +1,5 @@
-import { existsSync, readFileSync } from "fs";
-import { dirname, join } from "path";
-import { fileURLToPath } from "url";
+#!/usr/bin/env bun
+export * from "../assets/templates/helpers/workflow-contract";
+import { runTrackedForgeHelper } from "./lib/run-forge-helper";
 
-export type WorkflowContract = {
-  version: string;
-  contractId: string;
-  compatibility: {
-    agents: string[];
-    repoLocalFirst: boolean;
-  };
-  externalTooling?: {
-    waza?: {
-      sourceRepo: string;
-      managedSkills: string[];
-      primaryHost: string;
-      codexPrimaryPath: string;
-      stagingCachePath: string;
-      syncMode: string;
-      hostDriftPolicy: string;
-    };
-    codexAutomationProfile?: {
-      requiredSkills: string[];
-      optionalSkills: string[];
-      mode: string;
-      source: string;
-      routes: {
-        workflowHealth: string;
-        reviewGate: string;
-        architectureDiagram: string;
-      };
-      vendoringPolicy: string;
-    };
-    diagramDesign?: {
-      skillName: string;
-      primaryHost: string;
-      codexPrimaryPath: string;
-      syncMode: string;
-      vendoringPolicy: string;
-    };
-  };
-  agenticDevelopment?: {
-    routing: {
-      productDiscovery: string;
-      complexEngineeringPlan: string;
-      designPlan: string;
-      smallOrMediumPlan: string;
-      bugOrRegression: string;
-      postImplementationReview: string;
-    };
-    dueDiligence: {
-      levels: string[];
-      explicitReportRequiredFor: string[];
-    };
-  };
-  documentation?: {
-    referenceConfigs?: {
-      source: string;
-      repoStubDirectory: string;
-      packageDirectory: string;
-      resolverCommand: string;
-      stubMarker: string;
-    };
-  };
-  helpers: {
-    runtimeDirectory?: string;
-    compatibilityDirectory?: string;
-    scripts: string[];
-  };
-  artifacts: {
-    runtimeManifest: string;
-    requiredDirectories: string[];
-    requiredFiles: string[];
-    runtimeFiles?: string[];
-  };
-  documents: {
-    spec: string;
-    currentStatus?: string;
-    planDirectory: string;
-    taskChecklist?: string;
-    deferredGoalLedger?: string;
-    researchReportsDirectory: string;
-    lessonsLog: string;
-  };
-  adoptionTemplates?: {
-    files?: Record<
-      string,
-      {
-        document: string;
-        reason: string;
-        lines: string[];
-      }
-    >;
-  };
-  migrations: {
-    legacyVersions: string[];
-    legacyPaths: string[];
-    upgrade?: {
-      strategyVersion: number;
-      supportedLegacyVersions: string[];
-      actionClasses: string[];
-      safety: {
-        removeOnlyOwnership: string;
-        unknownFiles: string;
-        customHooks: string;
-        ignoredReferenceMaterial: string;
-        localSecrets: string;
-      };
-      actions: Array<{
-        id: string;
-        signal: string;
-        action: "preserve" | "archive" | "reconfigure" | "remove";
-        risk: "low" | "medium" | "high";
-        ownership: "known_generated" | "managed_config" | "user_authored" | "user_local";
-        paths: string[];
-        targetPaths?: string[];
-        cleanupMode?: "always" | "generated_helper";
-        summary: string;
-      }>;
-    };
-  };
-};
-
-const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
-const REPO_ROOT = SCRIPT_DIR.endsWith("/.ai/harness/scripts")
-  ? join(SCRIPT_DIR, "../../..")
-  : SCRIPT_DIR.endsWith("/assets/templates/helpers")
-    ? join(SCRIPT_DIR, "../../..")
-    : join(SCRIPT_DIR, "..");
-const LOCAL_ASSET_PATH = join(REPO_ROOT, "assets", "workflow-contract.v1.json");
-
-export function resolveAgenticDevRoot(_repoRoot = REPO_ROOT): string {
-  const configuredRoot =
-    process.env.AGENTIC_DEV_ROOT ||
-    process.env.AGENTIC_DEV_SKILL_ROOT;
-  if (configuredRoot && configuredRoot.length > 0) return configuredRoot;
-
-  if (existsSync(LOCAL_ASSET_PATH)) return REPO_ROOT;
-
-  const home = process.env.HOME;
-  if (home && home.length > 0) {
-    const candidates = [
-      join(home, "Projects", "forge"),
-      join(home, ".codex", "skills", "forge"),
-      join(home, ".claude", "skills", "forge"),
-      join(home, ".agents", "skills", "forge"),
-    ];
-
-    for (const candidate of candidates) {
-      if (existsSync(candidate)) return candidate;
-    }
-
-    return candidates[0];
-  }
-
-  return join(".forge", "skills", "forge");
-}
-
-export function resolveAgenticDevSkillRoot(repoRoot = REPO_ROOT): string {
-  return resolveAgenticDevRoot(repoRoot);
-}
-
-export function resolveUpstreamWorkflowContract(repoRoot = REPO_ROOT): string {
-  if (existsSync(LOCAL_ASSET_PATH)) return LOCAL_ASSET_PATH;
-  return join(resolveAgenticDevRoot(repoRoot), "assets", "workflow-contract.v1.json");
-}
-
-export function loadWorkflowContract(
-  contractPath = resolveUpstreamWorkflowContract()
-): WorkflowContract {
-  return JSON.parse(readFileSync(contractPath, "utf-8")) as WorkflowContract;
-}
-
-export function resolveInstalledWorkflowContract(repoRoot: string): string {
-  return join(repoRoot, ".ai", "harness", "workflow-contract.json");
-}
-
-export function resolveWorkflowContractForRepo(repoRoot: string): string {
-  const installedPath = resolveInstalledWorkflowContract(repoRoot);
-  return existsSync(installedPath) ? installedPath : resolveUpstreamWorkflowContract(repoRoot);
-}
-
-export function getHelperScripts(contract: WorkflowContract): string[] {
-  return [...contract.helpers.scripts];
-}
-
-export function getHelperRuntimeDir(contract: WorkflowContract): string {
-  return (
-    contract.helpers.runtimeDirectory ??
-    contract.helpers.compatibilityDirectory ??
-    "scripts"
-  );
-}
-
-export function getRequiredDirectories(contract: WorkflowContract): string[] {
-  return [...contract.artifacts.requiredDirectories];
-}
-
-export function getRequiredFiles(contract: WorkflowContract): string[] {
-  return [...contract.artifacts.requiredFiles];
-}
-
-if (import.meta.main) {
-  const contract = loadWorkflowContract(process.argv[2] || resolveUpstreamWorkflowContract());
-  console.log(JSON.stringify(contract, null, 2));
-}
+if (import.meta.main) runTrackedForgeHelper("workflow-contract.ts");

package/scripts/workstream-sync.sh

@@ -1,263 +1,4 @@
 #!/bin/bash
 set -euo pipefail
-
-# Contract invariant: durable capability ledgers live under tasks/workstreams.
-
-usage() {
-  cat <<'USAGE_EOF'
-Usage:
-  scripts/workstream-sync.sh ensure --block <capability-prefix> [--slug <slug>] [--title <title>] [--plan <plan-file>] [--slice <todo-id>] [--request <architecture-request>]
-USAGE_EOF
-}
-
-repo="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
-repo="$(cd "$repo" && pwd)"
-cd "$repo"
-
-command_name="${1:-ensure}"
-shift || true
-
-functional_block=""
-slug=""
-title=""
-source_plan="(none)"
-current_slice="todo-01"
-request_file="(none)"
-
-json_escape() {
-  local value="$1"
-  value="${value//\\/\\\\}"
-  value="${value//\"/\\\"}"
-  value="${value//$'\n'/\\n}"
-  value="${value//$'\r'/\\r}"
-  value="${value//$'\t'/\\t}"
-  printf '%s' "$value"
-}
-
-json_get() {
-  local json_input="$1"
-  local key="$2"
-  local parsed=""
-
-  if [[ -z "$json_input" ]]; then
-    return 1
-  fi
-
-  if command -v jq >/dev/null 2>&1; then
-    parsed="$(printf '%s' "$json_input" | jq -r ".$key // empty" 2>/dev/null || true)"
-  fi
-
-  if [[ -z "$parsed" ]] && command -v node >/dev/null 2>&1; then
-    parsed="$(JSON_INPUT="$json_input" JSON_KEY="$key" node -e '
-const raw = process.env.JSON_INPUT || "";
-const key = process.env.JSON_KEY || "";
-try {
-  const value = JSON.parse(raw)[key];
-  if (value === undefined || value === null) process.exit(1);
-  process.stdout.write(String(value));
-} catch {
-  process.exit(1);
-}
-' 2>/dev/null || true)"
-  fi
-
-  [[ -n "$parsed" ]] || return 1
-  printf '%s' "$parsed"
-}
-
-safe_token() {
-  local value="$1"
-  value="$(printf '%s' "$value" | tr '[:upper:]' '[:lower:]')"
-  value="$(printf '%s' "$value" | sed -E 's/[^a-z0-9]+/-/g; s/^-+//; s/-+$//; s/-{2,}/-/g')"
-  printf '%s' "${value:-workstream}"
-}
-
-validate_block() {
-  local block="$1"
-  case "$block" in
-    ""|.|..|../*|*/../*|/*|*$'\n'*|*$'\r'*)
-      return 1
-      ;;
-  esac
-  [[ -e "$block" ]]
-}
-
-while [[ $# -gt 0 ]]; do
-  case "$1" in
-    --block)
-      [[ -n "${2:-}" ]] || { echo "workstream-sync: --block requires a value" >&2; exit 2; }
-      functional_block="${2#./}"
-      functional_block="${functional_block%/}"
-      shift 2
-      ;;
-    --slug)
-      [[ -n "${2:-}" ]] || { echo "workstream-sync: --slug requires a value" >&2; exit 2; }
-      slug="$(safe_token "$2")"
-      shift 2
-      ;;
-    --title)
-      [[ -n "${2:-}" ]] || { echo "workstream-sync: --title requires a value" >&2; exit 2; }
-      title="$2"
-      shift 2
-      ;;
-    --plan)
-      [[ -n "${2:-}" ]] || { echo "workstream-sync: --plan requires a value" >&2; exit 2; }
-      source_plan="$2"
-      shift 2
-      ;;
-    --slice)
-      [[ -n "${2:-}" ]] || { echo "workstream-sync: --slice requires a value" >&2; exit 2; }
-      current_slice="$2"
-      shift 2
-      ;;
-    --request)
-      [[ -n "${2:-}" ]] || { echo "workstream-sync: --request requires a value" >&2; exit 2; }
-      request_file="$2"
-      shift 2
-      ;;
-    --help|-h)
-      usage
-      exit 0
-      ;;
-    *)
-      echo "workstream-sync: unknown argument: $1" >&2
-      usage
-      exit 2
-      ;;
-  esac
-done
-
-if [[ "$command_name" != "ensure" ]]; then
-  echo "workstream-sync: unknown command: $command_name" >&2
-  usage
-  exit 2
-fi
-
-if ! validate_block "$functional_block"; then
-  echo "workstream-sync: --block must be an existing repo-relative capability prefix" >&2
-  exit 2
-fi
-
-if [[ ! -f "scripts/capability-resolver.ts" ]] || ! command -v bun >/dev/null 2>&1; then
-  echo "workstream-sync: scripts/capability-resolver.ts and bun are required" >&2
-  exit 2
-fi
-
-if ! resolver_json="$(bun scripts/capability-resolver.ts match --path "$functional_block" --format json 2>&1)"; then
-  echo "$resolver_json" >&2
-  exit 1
-fi
-
-if [[ "$(json_get "$resolver_json" "matched" || true)" != "true" ]]; then
-  echo "workstream-sync: --block must match a declared capability prefix in .ai/context/capabilities.json" >&2
-  exit 2
-fi
-
-capability_id="$(json_get "$resolver_json" "capability_id")"
-matched_prefix="$(json_get "$resolver_json" "matched_prefix")"
-architecture_domain="$(json_get "$resolver_json" "architecture_domain")"
-architecture_capability="$(json_get "$resolver_json" "architecture_capability")"
-architecture_module="$(json_get "$resolver_json" "architecture_module")"
-workstream_dir="$(json_get "$resolver_json" "workstream_dir")"
-contract_agents="$(json_get "$resolver_json" "contract_agents" || true)"
-contract_claude="$(json_get "$resolver_json" "contract_claude" || true)"
-
-if [[ -z "$slug" ]]; then
-  if [[ -n "$title" ]]; then
-    slug="$(safe_token "$title")"
-  else
-    slug="$(date '+%Y%m%d')-${architecture_capability}"
-  fi
-fi
-title="${title:-$slug}"
-workstream_file="${workstream_dir}/${slug}.md"
-event_file=".ai/harness/events.jsonl"
-iso_timestamp="$(date '+%Y-%m-%dT%H:%M:%S%z')"
-architecture_domain_file="docs/architecture/domains/${architecture_domain}.md"
-
-mkdir -p "$workstream_dir" "$(dirname "$architecture_module")" "$(dirname "$architecture_domain_file")" ".ai/harness"
-
-if [[ ! -f "$architecture_domain_file" ]]; then
-  cat > "$architecture_domain_file" <<EOF_DOMAIN
-# Architecture Domain: ${architecture_domain}
-
-> **Source**: \`.ai/context/capabilities.json\`
-
-## Capabilities
-
-- \`${capability_id}\` -> \`${architecture_module}\`
-EOF_DOMAIN
-elif ! grep -Fq "$architecture_module" "$architecture_domain_file"; then
-  {
-    echo ""
-    echo "- \`${capability_id}\` -> \`${architecture_module}\`"
-  } >> "$architecture_domain_file"
-fi
-
-if [[ ! -f "$architecture_module" ]]; then
-  cat > "$architecture_module" <<EOF_MODULE
-# Architecture Module: ${architecture_domain}/${architecture_capability}
-
-> **Capability ID**: \`${capability_id}\`
-> **Functional Block**: \`${functional_block}\`
-> **Matched Prefix**: \`${matched_prefix}\`
-> **Domain**: \`${architecture_domain}\`
-> **Capability**: \`${architecture_capability}\`
-
-## Boundary
-
-- Responsibility: Keep the capability boundary, entrypoints, runtime path, dependency rules, and local verification pointers for \`${capability_id}\`.
-- Entrypoints: \`${matched_prefix}\`
-- Runtime path: \`${matched_prefix}\`
-- Local contracts: \`${contract_agents:-none}\`, \`${contract_claude:-none}\`
-
-## Active Workstreams
-
-- \`${workstream_file}\`
-EOF_MODULE
-elif ! grep -Fq "$workstream_file" "$architecture_module"; then
-  {
-    echo ""
-    echo "- \`${workstream_file}\`"
-  } >> "$architecture_module"
-fi
-
-if [[ ! -f "$workstream_file" ]]; then
-  cat > "$workstream_file" <<EOF_WORKSTREAM
-# Workstream: ${title}
-
-> **Status**: active
-> **Capability ID**: \`${capability_id}\`
-> **Functional Block**: \`${functional_block}\`
-> **Matched Prefix**: \`${matched_prefix}\`
-> **Architecture Domain**: \`${architecture_domain}\`
-> **Architecture Capability**: \`${architecture_capability}\`
-> **Architecture Module**: \`${architecture_module}\`
-> **Source Plan**: ${source_plan}
-> **Current Slice**: ${current_slice}
-> **Last Handoff**: \`.ai/harness/session/continuation.md\`
-> **Architecture Request**: ${request_file}
-
-## Purpose
-
-Track durable multi-session progress for \`${capability_id}\` without inflating local agent instructions.
-
-## TODOs
-
-- [ ] ${current_slice}: Complete the current executable slice for \`${capability_id}\`.
-
-## Notes
-
-- Project the current slice into \`tasks/todos.md\` for a single session.
-- Keep architecture facts in \`${architecture_module}\`; keep execution progress here.
-EOF_WORKSTREAM
-fi
-
-event_json="{\"ts\":\"$(json_escape "$iso_timestamp")\",\"file_path\":\"$(json_escape "$workstream_file")\",\"severity\":\"medium\",\"functional_block\":\"$(json_escape "$functional_block")\",\"capability_id\":\"$(json_escape "$capability_id")\",\"matched_prefix\":\"$(json_escape "$matched_prefix")\",\"architecture_domain\":\"$(json_escape "$architecture_domain")\",\"architecture_capability\":\"$(json_escape "$architecture_capability")\",\"architecture_module\":\"$(json_escape "$architecture_module")\",\"workstream_dir\":\"$(json_escape "$workstream_dir")\",\"contract_agents\":\"$(json_escape "$contract_agents")\",\"contract_claude\":\"$(json_escape "$contract_claude")\",\"active_workstream\":\"$(json_escape "$workstream_file")\",\"change_type\":\"workstream-sync\",\"spawn_recommended\":false,\"contract_sync_required\":true,\"request_file\":\"$(json_escape "$request_file")\"}"
-printf '%s\n' "$event_json" >> "$event_file"
-
-if [[ -x "scripts/context-contract-sync.sh" ]]; then
-  bash "scripts/context-contract-sync.sh" sync-event --json "$event_json"
-fi
-
-echo "[WorkstreamSync] Ensured $workstream_file for $capability_id."
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+exec "$SCRIPT_DIR/lib/run-forge-helper.sh" "workstream-sync.sh" "$@"

package/src/cli/agent-jobs/executor-health.ts

@@ -1,4 +1,4 @@
-import type { GitHubStatus } from "../github/github";
+import type { GitHubStatus } from "../github/contracts";
 import type { McpAgentRunnerName } from "../mcp/types";
 import type { ControllerAgent, ControllerTask } from "../controller/types";
 

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,13 +63,17 @@ 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,
+  options: { packageIdentityVerified?: boolean } = {},
+):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');
   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.pluginVersion!==expectedProviderVersion&&!options.packageIdentityVerified)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');
@@ -86,7 +90,12 @@ function install(entry:RegistryEntry,controllerHome:string):Record<string,unknow
     const manifest=JSON.parse(readFileSync(manifestPath,'utf8')) as Record<string,unknown>;if(manifest.id!==entry.id||manifest.version!==entry.version)throw new Error(`PLUGIN_PACKAGE_IDENTITY_MISMATCH: ${entry.id}`);
     if(existsSync(finalRoot)){renameSync(finalRoot,backup);backed=true;}renameSync(stage,finalRoot);
     const result=installerJson(run(process.execPath,[within(finalRoot,entry.installer)],finalRoot,180000));
-    const installed=installExternalPluginRegistration(controllerHome,registrationFrom(result,entry));
+    // The staged package manifest is checked against the catalog before the
+    // installer runs. Provider identity is then probed through the installed
+    // socket during registry sync. The installer's providerInstall version is
+    // useful diagnostics, but must not strand a verified package when that
+    // helper field is stale.
+    const installed=installExternalPluginRegistration(controllerHome,registrationFrom(result,entry,{packageIdentityVerified:true}));
     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,nextSteps:installerNextSteps(result)};

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