@moretea-labs/forge 1.7.1 → 1.8.0

package/scripts/init-project.sh

@@ -47,18 +47,10 @@ install_hook_settings_template() {
 ensure_runtime_gitignore_block() {
     local file_path="$1"
     local extra_entries=""
-    local helper_entries=""
     if pi_should_enable_factor_factory "$(pi_plan_type "$STACK")"; then
         extra_entries="$(pi_factor_factory_gitignore_entries)"
     fi
-    helper_entries="$(pi_helper_wrapper_gitignore_entries "$ASSETS_WORKFLOW_CONTRACT")"
-    if [[ -n "$helper_entries" ]]; then
-        if [[ -n "$extra_entries" ]]; then
-            extra_entries="${extra_entries}"$'\n'"${helper_entries}"
-        else
-            extra_entries="$helper_entries"
-        fi
-    fi
+    # Package helpers are runtime/package capabilities, not generated repo files.
     pi_ensure_gitignore_block "$file_path" "" "$extra_entries" "apply"
 }
 
@@ -206,30 +198,13 @@ create_structure() {
     if pi_should_generate_full_docs; then
         mkdir -p docs/architecture
     fi
-    mkdir -p tasks/archive
-    mkdir -p tasks/contracts
-    mkdir -p tasks/reviews
-    mkdir -p tasks/notes
-    mkdir -p plans/archive
     mkdir -p .ai/context
-    mkdir -p .ai/harness/checks
-    mkdir -p .ai/harness/session .ai/harness/controller/packets .ai/harness/projections .ai/harness/transfers
-    mkdir -p .ai/harness/failures
-    mkdir -p .ai/harness/runs
-    mkdir -p .claude/templates
     mkdir -p deploy/env
     mkdir -p deploy/scripts
     mkdir -p deploy/submissions
     mkdir -p deploy/runbooks
     mkdir -p deploy/release-checklists
     mkdir -p deploy/sql
-    mkdir -p _ops/env
-    mkdir -p _ops/secrets
-    mkdir -p _ops/artifacts
-    mkdir -p _ops/logs
-    mkdir -p _ops/state
-    mkdir -p _ops/scratch
-    mkdir -p artifacts
     create_contract_directories
 
     # Create documentation files
@@ -262,25 +237,6 @@ Do not duplicate that execution checklist here. Record only work intentionally d
 | Goal | Why Deferred | Tradeoff | Revisit Trigger |
 |------|--------------|----------|-----------------|
 | (none) | No deferred medium/long-term goal recorded yet. | Keep the first sprint bounded. | Add a row when a real follow-up is postponed. |
-EOF
-
-    cat > tasks/current.md << EOF
-# Current Status Snapshot
-
-<!-- generated-by: forge refresh-current-status v1 -->
-<!-- updated_at: bootstrap -->
-<!-- stale_after: 24h -->
-
-> **Status**: Idle
-> **Updated At**: bootstrap
-> **Source Branch**: main
-> **Source Commit**: bootstrap
-> **Target Branch**: main
-> **Stale After**: 24h
-> **Reason**: bootstrap
-> **Derived From**: active-plan, workstreams, handoff, checks, git status
-
-This file is a tracked mainline snapshot derived from repo artifacts. It is not a live lock, not a kanban board, and not an implementation gate. If it is stale, read the source artifacts below.
 EOF
 
     cat > tasks/lessons.md << EOF
@@ -297,8 +253,6 @@ EOF
 - Where to apply next time:
 EOF
 
-    pi_install_templates "$PWD" "$ASSETS_TEMPLATES_DIR" "apply"
-
     mkdir -p docs/researches
     cat > docs/researches/README.md << EOF
 # Research Reports
@@ -306,36 +260,21 @@ EOF
 Durable research reports live in this directory as topic-scoped Markdown files.
 
 Use \`YYYYMMDD-topic.md\` names when chronology matters, or \`<topic>.md\` for
-stable subject reports. Keep task-local implementation decisions in
-\`tasks/notes/\`, and keep repeated correction-derived rules in \`tasks/lessons.md\`.
+stable subject reports. Keep durable product/architecture decisions in authored
+documentation; mutable Requirement/Plan/Work execution state stays in Controller Home.
 EOF
 
-    local helper_names
-    helper_names="$(pi_workflow_contract_query_lines "$ASSETS_WORKFLOW_CONTRACT" "helpers.scripts" | xargs)"
-    pi_install_helpers "$PWD" "$ASSETS_TEMPLATES_DIR/helpers" "apply" "$helper_names"
     install_workflow_contract
     if pi_should_enable_factor_factory "$(pi_plan_type "$STACK")"; then
         pi_install_factor_factory "$PWD" "$ASSETS_FACTOR_FACTORY_DIR" "$SCRIPT_DIR" "apply"
     fi
     ensure_task_sync_package_script
-    # Canonical harness state surface:
-    # - .ai/context/context-map.json
-    # - .ai/harness/policy.json
-    # - .ai/harness/brain-manifest.json
-    # - .ai/harness/checks/latest.json
-    # - .ai/harness/events.jsonl
-    # - .ai/harness/architecture/events.jsonl
-    # - .ai/harness/session/continuation.md
-    # - .ai/harness/session/resume.md
-    # - .ai/harness/failures/latest.jsonl
-    # - .ai/harness/security/.gitkeep
-    # - .ai/harness/worktrees/.gitkeep
-    # - .ai/harness/runs/.gitkeep
-    pi_ensure_harness_state_surface "$PWD" "apply"
+    # Mutable Forge Runtime state is intentionally not scaffolded into the repository.
+    # Repository registration binds Runtime state to Controller Home.
 
     install_hook_settings_template
-
-    install_hook_assets
+    pi_install_root_context_files "$PWD" "apply"
+    pi_install_directory_context_files "$PWD" "apply"
 
     if [ -d "$ASSETS_REF_DIR" ]; then
         pi_install_reference_configs "$PWD" "$ASSETS_REF_DIR" "apply"
@@ -354,10 +293,13 @@ EOF
     ensure_gitignore_entry .gitignore ""
     ensure_gitignore_entry .gitignore "# External references"
     ensure_gitignore_entry .gitignore "_ref/"
+    ensure_gitignore_entry .gitignore ".codegraph"
     ensure_gitignore_entry .gitignore ".codegraph/"
     ensure_gitignore_entry .gitignore ""
     ensure_gitignore_entry .gitignore "# Local operations state"
     ensure_gitignore_entry .gitignore "_ops/"
+    ensure_gitignore_entry .gitignore ".forge/browser"
+    ensure_gitignore_entry .gitignore ".forge/plugins"
     ensure_gitignore_entry .gitignore ""
     ensure_gitignore_entry .gitignore "# Environment"
     ensure_gitignore_entry .gitignore ".env"
@@ -493,8 +435,8 @@ main() {
     echo "  1. cd $PROJECT_NAME"
     echo "  2. Copy .env.example to .env and configure"
     echo "  3. Run: $PKG_MANAGER run dev"
-    echo "  4. Use Codex Plan mode or Forge /plan, then capture it with: bash scripts/capture-plan.sh --slug first-feature --title \"First Feature\""
-    echo "  5. After approval, run: bash scripts/plan-to-todo.sh --plan <active-plan>"
+    echo "  4. Use Forge /plan only when real decomposition is needed; mutable Plan/Work state stays in Controller Home"
+    echo "  5. Keep only authored product, architecture, research, and deferred-goal documents in Git"
     echo ""
     pi_print_external_tooling_report "$PWD" "apply" "$SCRIPT_DIR/check-agent-tooling.sh"
     echo ""

package/scripts/install-desktop-operator-registration.ts

@@ -13,13 +13,15 @@ function argument(name: string): string | undefined {
 }
 
 function usage(): never {
-  throw new Error('Usage: bun scripts/install-desktop-operator-registration.ts --controller-home <path> [--socket <absolute-path>] [--launch-agent-label <label>] [--expected-program-contains <identity>] [--version 0.2.1] [--protocol 1.0] [--expected-revision N] [--disabled]');
+  throw new Error('Usage: bun scripts/install-desktop-operator-registration.ts --controller-home <path> --version <provider-version> [--socket <absolute-path>] [--launch-agent-label <label>] [--expected-program-contains <identity>] [--protocol 1.0] [--expected-revision N] [--disabled]');
 }
 
 const controllerHome = argument('--controller-home') ?? process.env.FORGE_CONTROLLER_HOME?.trim();
 if (!controllerHome) usage();
 const userHome = homedir();
 const socketPath = argument('--socket') ?? join(userHome, 'Library', 'Caches', 'Forge', 'desktop-operator.sock');
+const pluginVersion = argument('--version');
+if (!pluginVersion) usage();
 const launchAgentLabel = argument('--launch-agent-label') ?? 'com.moretea.forge.desktop-operator';
 const expectedProgramContains = argument('--expected-program-contains')
   ?? join(userHome, 'Applications', 'Forge Desktop Operator.app', 'Contents', 'MacOS', 'desktop-operator');
@@ -35,7 +37,7 @@ const registration = installExternalPluginRegistration(
     socketPath,
     launchAgentLabel,
     expectedProgramContains,
-    pluginVersion: argument('--version') ?? '0.2.1',
+    pluginVersion,
     protocolVersion: argument('--protocol') ?? '1.0',
     enabled: !process.argv.includes('--disabled'),
   }),

package/scripts/install-independent-windows-wsl-recovery.ts

@@ -0,0 +1,125 @@
+#!/usr/bin/env bun
+/**
+ * Bootstrap only: install immutable fixed-command rescue scripts outside the
+ * Forge checkout. This script never invokes Forge Runtime, MCP, Controller,
+ * or the existing Recovery implementation.
+ */
+import { chmodSync, copyFileSync, existsSync, mkdirSync, renameSync, writeFileSync } from 'fs';
+import { homedir } from 'os';
+import { dirname, join, resolve } from 'path';
+import { fileURLToPath } from 'url';
+import { spawnSync } from 'child_process';
+import {
+  createIndependentHostRescueConfig,
+  renderIndependentHostRescueEnv,
+  renderIndependentHostRescueSystemdUnit,
+  renderWindowsHostRescueConfig,
+} from '../src/runtime/standalone-recovery/independent-host-rescue';
+import { discoverWslWindowsHostEnvironment } from '../src/runtime/platform/windows-host-discovery';
+import { resolveWindowsRecoveryDeployment } from '../src/runtime/platform/windows-recovery-deployment';
+
+function option(name: string): string | undefined {
+  const index = process.argv.indexOf(name);
+  return index >= 0 ? process.argv[index + 1] : undefined;
+}
+
+function writeAtomic(path: string, content: string, mode: number): void {
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const temporary = `${path}.${process.pid}.tmp`;
+  writeFileSync(temporary, content, { encoding: 'utf8', mode });
+  renameSync(temporary, path);
+  chmodSync(path, mode);
+}
+
+function copyAtomic(source: string, destination: string, mode: number): void {
+  mkdirSync(dirname(destination), { recursive: true, mode: 0o700 });
+  const temporary = `${destination}.${process.pid}.tmp`;
+  copyFileSync(source, temporary);
+  chmodSync(temporary, mode);
+  renameSync(temporary, destination);
+}
+
+function command(command: string, args: string[]): void {
+  const result = spawnSync(command, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 30_000 });
+  if (result.status !== 0 || result.error) {
+    throw new Error(`HOST_RESCUE_COMMAND_FAILED: ${command} ${args.join(' ')}: ${(result.stderr || result.stdout || result.error?.message || 'unknown error').trim()}`);
+  }
+}
+
+const sourceRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const home = homedir();
+const rescueRoot = resolve(option('--rescue-root') ?? join(home, '.forge-recovery'));
+const host = discoverWslWindowsHostEnvironment();
+const discoveredWindowsRoot = host?.programData ? join(host.programData, 'ForgeRecovery') : undefined;
+const windowsRootOption = option('--windows-root');
+const windowsRoot = resolve(windowsRootOption ?? discoveredWindowsRoot ?? (() => { throw new Error('HOST_RESCUE_WINDOWS_ROOT_DISCOVERY_REQUIRED: provide --windows-root when Windows ProgramData cannot be discovered'); })());
+const deployment = resolveWindowsRecoveryDeployment({
+  rescueRoot,
+  host,
+  recoveryScriptHostPath: join(windowsRoot, 'ForgeRecovery.ps1'),
+  recoveryScriptWindowsPath: option('--recovery-script-windows'),
+  powershellHostPath: option('--powershell-host'),
+  powershellWindowsPath: option('--powershell-windows'),
+});
+const controllerHome = resolve(option('--controller-home') ?? join(home, '.forge', 'controller'));
+const tunnelClient = resolve(option('--tunnel-client') ?? join(home, '.local', 'bin', 'tunnel-client'));
+const stageOnly = process.argv.includes('--stage-only');
+const installWindowsLogonTask = process.argv.includes('--install-windows-logon-task');
+
+const config = createIndependentHostRescueConfig({
+  wslDistro: option('--distro') ?? process.env.WSL_DISTRO_NAME ?? '',
+  controllerHome,
+  sourceRoot,
+  rescueRoot,
+  tunnelClient,
+  tunnelAlias: option('--tunnel-alias') ?? '',
+  tunnelId: option('--tunnel-id') ?? '',
+  tunnelRuntimeApiKeyRef: option('--tunnel-runtime-api-key-ref') ?? `file:${rescueRoot}/secrets/openai-tunnel-runtime-api-key`,
+  tunnelProfile: option('--tunnel-profile'),
+  tunnelProfileDir: option('--tunnel-profile-dir') ?? join(home, '.config', 'tunnel-client'),
+  tunnelAdminProfile: option('--tunnel-admin-profile'),
+  localMcpUrl: option('--local-mcp-url'),
+});
+
+const assetRoot = join(sourceRoot, 'assets', 'recovery');
+copyAtomic(join(assetRoot, 'forge-wsl-rescue'), join(rescueRoot, 'bin', 'forge-wsl-rescue'), 0o700);
+writeAtomic(join(rescueRoot, 'config', 'rescue.env'), renderIndependentHostRescueEnv(config), 0o600);
+copyAtomic(join(assetRoot, 'ForgeRecovery.ps1'), join(windowsRoot, 'ForgeRecovery.ps1'), 0o600);
+writeAtomic(join(windowsRoot, 'config.json'), renderWindowsHostRescueConfig(config), 0o600);
+
+const unitPath = join(home, '.config', 'systemd', 'user', config.recoveryUnit);
+writeAtomic(unitPath, renderIndependentHostRescueSystemdUnit(config), 0o644);
+if (!stageOnly) {
+  command('systemctl', ['--user', 'daemon-reload']);
+  command('systemctl', ['--user', 'enable', '--now', config.recoveryUnit]);
+}
+let windowsLogonTask: { name: string; installed: boolean; error?: string } | undefined;
+if (installWindowsLogonTask) {
+  const scriptPath = deployment.recoveryScriptWindowsPath;
+  const taskName = 'Forge Independent Recovery WSL';
+  const powershell = deployment.powershellHostPath;
+  try {
+    command(powershell, ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-File', scriptPath, 'task_install']);
+    windowsLogonTask = { name: taskName, installed: true };
+  } catch (error) {
+    // The external agent and WSL watchdog remain valid without a logon task.
+    // Task Scheduler permission is a Windows elevation boundary, not a reason
+    // to report a fully staged host-rescue installation as absent.
+    windowsLogonTask = {
+      name: taskName,
+      installed: false,
+      error: error instanceof Error ? error.message.slice(0, 1_000) : String(error).slice(0, 1_000),
+    };
+  }
+}
+
+process.stdout.write(`${JSON.stringify({
+  status: stageOnly ? 'staged' : 'installed',
+  rescueRoot,
+  windowsRoot,
+  deployment,
+  controllerHome: config.controllerHome,
+  units: { runtime: config.runtimeUnit, connector: config.connectorUnit, recovery: config.recoveryUnit },
+  tunnel: { alias: config.tunnelAlias, id: config.tunnelId, localMcpUrl: config.localMcpUrl },
+  ...(windowsLogonTask ? { windowsLogonTask } : {}),
+}, null, 2)}\n`);

package/scripts/install-standalone-recovery.ts

@@ -1,4 +1,9 @@
+import { createHash } from 'crypto';
 import { isAbsolute, join, resolve } from 'path';
+import { hostname } from 'os';
+import { systemdUserUnitName } from '../src/cli/controller/systemd-user';
+import { openAiSecureTunnelConnectArgs } from '../src/cli/mcp/openai-secure-tunnel';
+import type { OpenAiSecureTunnelServiceConfig, PrimaryConnectorServiceConfig, PublicTunnelServiceConfig, RecoveryTunnelServiceConfig } from '../src/runtime/standalone-recovery/core';
 import { installStandaloneRecovery } from '../src/runtime/standalone-recovery/installer';
 
 function option(name: string): string | undefined {
@@ -30,6 +35,54 @@ function launchdService(label: string | undefined, plistPath: string | undefined
   return { platform: 'launchd' as const, label, ...(plistPath ? { plistPath } : {}) };
 }
 
+function openAiTunnelService(input: {
+  tunnelId?: string;
+  alias?: string;
+  runtimeApiKeyRef?: string;
+  profile?: string;
+  profileDir?: string;
+  adminProfile?: string;
+  mcpServerUrl: string;
+  defaultAlias: string;
+  role: string;
+}): OpenAiSecureTunnelServiceConfig | undefined {
+  const supplied = Boolean(input.tunnelId || input.alias || input.runtimeApiKeyRef || input.profile || input.profileDir || input.adminProfile);
+  if (!supplied) return undefined;
+  if (!input.tunnelId) throw new Error(`${input.role}_OPENAI_TUNNEL_ID_REQUIRED`);
+  if (input.profileDir && !isAbsolute(input.profileDir)) throw new Error(`${input.role}_OPENAI_PROFILE_DIR_ABSOLUTE_REQUIRED`);
+  const service: OpenAiSecureTunnelServiceConfig = {
+    platform: 'openai-secure-tunnel',
+    alias: input.alias?.trim() || input.defaultAlias,
+    tunnelId: input.tunnelId.trim(),
+    mcpServerUrl: input.mcpServerUrl,
+    ...(input.runtimeApiKeyRef?.trim() ? { runtimeApiKeyRef: input.runtimeApiKeyRef.trim() } : {}),
+    ...(input.profile?.trim() ? { profile: input.profile.trim() } : {}),
+    ...(input.profileDir ? { profileDir: resolve(input.profileDir) } : {}),
+    ...(input.adminProfile?.trim() ? { adminProfile: input.adminProfile.trim() } : {}),
+  };
+  try { openAiSecureTunnelConnectArgs(service); } catch (error) {
+    throw new Error(`${input.role}_${error instanceof Error ? error.message : 'OPENAI_TUNNEL_CONFIG_INVALID'}`);
+  }
+  return service;
+}
+
+function assertDistinctOpenAiTunnelIdentity(
+  recovery: RecoveryTunnelServiceConfig | undefined,
+  primary: PublicTunnelServiceConfig | undefined,
+): void {
+  if (recovery?.platform !== 'openai-secure-tunnel' || primary?.platform !== 'openai-secure-tunnel') return;
+  if (recovery.alias === primary.alias) throw new Error('RECOVERY_OPENAI_TUNNEL_ALIAS_CONFLICT');
+  if (recovery.tunnelId === primary.tunnelId) throw new Error('RECOVERY_OPENAI_TUNNEL_ID_CONFLICT');
+}
+
+function recoveryOpenAiTunnelDefaultAlias(controllerHome: string): string {
+  const suffix = createHash('sha256')
+    .update(`${hostname()}\0${process.platform}\0${resolve(controllerHome)}`)
+    .digest('hex')
+    .slice(0, 12);
+  return `forge-recovery-${suffix}`;
+}
+
 const controllerHomeRaw = option('--controller-home') ?? process.env.FORGE_CONTROLLER_HOME ?? '';
 const controllerHome = resolve(controllerHomeRaw);
 if (!controllerHomeRaw || controllerHome === resolve('.')) throw new Error('RECOVERY_CONTROLLER_HOME_REQUIRED');
@@ -38,28 +91,79 @@ const stageOnly = process.argv.includes('--stage-only');
 const publicMcpUrl = endpointOption('--public-mcp-url');
 const recoveryPublicUrl = endpointOption('--recovery-public-url');
 
-const recoveryTunnelService = launchdService(
+const recoveryLaunchdTunnelService = launchdService(
   option('--recovery-tunnel-service-label'),
   option('--recovery-tunnel-service-plist'),
   'RECOVERY_TUNNEL_SERVICE',
 );
-if (Boolean(recoveryTunnelService) !== Boolean(recoveryPublicUrl)) throw new Error('RECOVERY_PUBLIC_URL_AND_TUNNEL_SERVICE_MUST_BE_CONFIGURED_TOGETHER');
+const recoverySystemdUnitRaw = option('--recovery-tunnel-systemd-unit');
+const recoverySystemdTunnelService = recoverySystemdUnitRaw
+  ? { platform: 'systemd-user' as const, unitName: systemdUserUnitName(recoverySystemdUnitRaw) }
+  : undefined;
+if (recoveryLaunchdTunnelService && recoverySystemdTunnelService) throw new Error('RECOVERY_TUNNEL_OWNER_CONFLICT');
+if (recoveryLaunchdTunnelService && process.platform === 'linux') throw new Error('RECOVERY_TUNNEL_LAUNCHD_UNSUPPORTED_ON_LINUX');
+if (recoverySystemdTunnelService && process.platform !== 'linux') throw new Error('RECOVERY_TUNNEL_SYSTEMD_UNSUPPORTED_ON_THIS_PLATFORM');
+const recoveryLocalMcpUrl = `http://127.0.0.1:${port}/recovery/mcp`;
+const recoveryOpenAiTunnelService = openAiTunnelService({
+  tunnelId: option('--recovery-openai-tunnel-id'),
+  alias: option('--recovery-openai-tunnel-alias'),
+  runtimeApiKeyRef: option('--recovery-openai-runtime-api-key-ref'),
+  profile: option('--recovery-openai-profile'),
+  profileDir: option('--recovery-openai-profile-dir'),
+  adminProfile: option('--recovery-openai-admin-profile'),
+  mcpServerUrl: recoveryLocalMcpUrl,
+  defaultAlias: recoveryOpenAiTunnelDefaultAlias(controllerHome),
+  role: 'RECOVERY',
+});
+const recoveryTunnelOwners = [recoverySystemdTunnelService, recoveryLaunchdTunnelService, recoveryOpenAiTunnelService].filter(Boolean);
+if (recoveryTunnelOwners.length > 1) throw new Error('RECOVERY_TUNNEL_OWNER_CONFLICT');
+const recoveryTunnelService = recoveryOpenAiTunnelService ?? recoverySystemdTunnelService ?? recoveryLaunchdTunnelService;
+if (recoveryOpenAiTunnelService && recoveryPublicUrl) throw new Error('RECOVERY_OPENAI_TUNNEL_PUBLIC_URL_CONFLICT');
+if ((recoverySystemdTunnelService || recoveryLaunchdTunnelService) && !recoveryPublicUrl) {
+  throw new Error('RECOVERY_PUBLIC_URL_AND_TUNNEL_SERVICE_MUST_BE_CONFIGURED_TOGETHER');
+}
+if (!recoveryTunnelService && recoveryPublicUrl) throw new Error('RECOVERY_PUBLIC_URL_AND_TUNNEL_SERVICE_MUST_BE_CONFIGURED_TOGETHER');
 const primaryConnectorLocalUrl = endpointOption('--primary-connector-local-url');
 const primaryConnectorBase = launchdService(
   option('--primary-connector-service-label'),
   option('--primary-connector-service-plist'),
   'RECOVERY_PRIMARY_CONNECTOR',
 );
-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(
+let primaryConnectorService: PrimaryConnectorServiceConfig | undefined;
+if (process.platform === 'linux') {
+  if (primaryConnectorBase) throw new Error('RECOVERY_PRIMARY_CONNECTOR_LAUNCHD_UNSUPPORTED_ON_LINUX');
+  primaryConnectorService = primaryConnectorLocalUrl ? { platform: 'systemd-user', localMcpUrl: primaryConnectorLocalUrl } : undefined;
+} else {
+  if (primaryConnectorLocalUrl && !primaryConnectorBase) throw new Error('RECOVERY_PRIMARY_CONNECTOR_LABEL_REQUIRED_FOR_LOCAL_URL');
+  primaryConnectorService = primaryConnectorBase
+    ? { ...primaryConnectorBase, ...(primaryConnectorLocalUrl ? { localMcpUrl: primaryConnectorLocalUrl } : {}) }
+    : undefined;
+}
+const primaryLaunchdTunnelService = launchdService(
   option('--primary-tunnel-service-label'),
   option('--primary-tunnel-service-plist'),
   'RECOVERY_PRIMARY_TUNNEL',
+ ) as PublicTunnelServiceConfig | undefined;
+const primaryOpenAiTunnelService = primaryConnectorLocalUrl ? openAiTunnelService({
+  tunnelId: option('--primary-openai-tunnel-id'),
+  alias: option('--primary-openai-tunnel-alias'),
+  runtimeApiKeyRef: option('--primary-openai-runtime-api-key-ref'),
+  profile: option('--primary-openai-profile'),
+  profileDir: option('--primary-openai-profile-dir'),
+  adminProfile: option('--primary-openai-admin-profile'),
+  mcpServerUrl: primaryConnectorLocalUrl,
+  defaultAlias: 'forge',
+  role: 'RECOVERY_PRIMARY',
+}) : undefined;
+const primaryOpenAiOptionsSupplied = Boolean(
+  option('--primary-openai-tunnel-id') || option('--primary-openai-tunnel-alias') || option('--primary-openai-runtime-api-key-ref')
+  || option('--primary-openai-profile') || option('--primary-openai-profile-dir') || option('--primary-openai-admin-profile'),
 );
+if (primaryOpenAiOptionsSupplied && !primaryConnectorLocalUrl) throw new Error('RECOVERY_PRIMARY_CONNECTOR_LOCAL_URL_REQUIRED_FOR_OPENAI_TUNNEL');
+if (primaryLaunchdTunnelService && primaryOpenAiTunnelService) throw new Error('RECOVERY_PRIMARY_TUNNEL_OWNER_CONFLICT');
+const primaryPublicTunnelService = primaryOpenAiTunnelService ?? primaryLaunchdTunnelService;
 if (primaryPublicTunnelService && !primaryConnectorService) throw new Error('RECOVERY_PRIMARY_CONNECTOR_REQUIRED_FOR_PRIMARY_TUNNEL');
+assertDistinctOpenAiTunnelIdentity(recoveryTunnelService, primaryPublicTunnelService);
 
 const result = await installStandaloneRecovery({
   controllerHome,
@@ -86,13 +190,21 @@ console.log(JSON.stringify({
     publicMcpUrl: config.publicMcpUrl,
     recoveryPublicUrl: config.recoveryPublicUrl,
     recoveryTunnelService: config.recoveryTunnelService
-      ? { platform: config.recoveryTunnelService.platform, label: config.recoveryTunnelService.label, plistPath: config.recoveryTunnelService.plistPath }
+      ? config.recoveryTunnelService.platform === 'launchd'
+        ? { platform: config.recoveryTunnelService.platform, label: config.recoveryTunnelService.label, plistPath: config.recoveryTunnelService.plistPath }
+        : config.recoveryTunnelService.platform === 'systemd-user'
+          ? { platform: config.recoveryTunnelService.platform, unitName: config.recoveryTunnelService.unitName }
+          : { platform: config.recoveryTunnelService.platform, alias: config.recoveryTunnelService.alias, tunnelId: config.recoveryTunnelService.tunnelId, mcpServerUrl: config.recoveryTunnelService.mcpServerUrl, runtimeApiKeyRef: config.recoveryTunnelService.runtimeApiKeyRef, profile: config.recoveryTunnelService.profile, profileDir: config.recoveryTunnelService.profileDir }
       : undefined,
     primaryConnectorService: config.primaryConnectorService
-      ? { platform: config.primaryConnectorService.platform, label: config.primaryConnectorService.label, plistPath: config.primaryConnectorService.plistPath, localMcpUrl: config.primaryConnectorService.localMcpUrl }
+      ? config.primaryConnectorService.platform === 'launchd'
+        ? { platform: config.primaryConnectorService.platform, label: config.primaryConnectorService.label, plistPath: config.primaryConnectorService.plistPath, localMcpUrl: config.primaryConnectorService.localMcpUrl }
+        : { platform: config.primaryConnectorService.platform, label: config.primaryConnectorService.label, localMcpUrl: config.primaryConnectorService.localMcpUrl }
       : undefined,
     primaryPublicTunnelService: config.primaryPublicTunnelService
-      ? { platform: config.primaryPublicTunnelService.platform, label: config.primaryPublicTunnelService.label, plistPath: config.primaryPublicTunnelService.plistPath }
+      ? config.primaryPublicTunnelService.platform === 'launchd'
+        ? { platform: config.primaryPublicTunnelService.platform, label: config.primaryPublicTunnelService.label, plistPath: config.primaryPublicTunnelService.plistPath }
+        : { platform: config.primaryPublicTunnelService.platform, alias: config.primaryPublicTunnelService.alias, tunnelId: config.primaryPublicTunnelService.tunnelId, mcpServerUrl: config.primaryPublicTunnelService.mcpServerUrl, runtimeApiKeyRef: config.primaryPublicTunnelService.runtimeApiKeyRef, profile: config.primaryPublicTunnelService.profile, profileDir: config.primaryPublicTunnelService.profileDir }
       : undefined,
   },
 }, null, 2));

package/scripts/install-uu-remote-rescue-registration.ts

@@ -0,0 +1,74 @@
+#!/usr/bin/env bun
+import { mkdirSync, renameSync, writeFileSync } from 'fs';
+import { homedir } from 'os';
+import { dirname, isAbsolute, join, resolve } from 'path';
+import { fileURLToPath } from 'url';
+import { controllerSystemRoot } from '../src/cli/repositories/controller-home';
+import { installExternalPluginRegistration } from '../src/runtime/plugins/external-registration';
+import { createUuRemoteRescueRegistrationInput } from '../src/runtime/plugins/uu-remote-rescue-registration';
+
+function argument(name: string): string | undefined {
+  const index = process.argv.indexOf(name);
+  if (index < 0) return undefined;
+  const value = process.argv[index + 1]?.trim();
+  if (!value || value.startsWith('--')) throw new Error(`UU_REMOTE_RESCUE_INSTALL_ARGUMENT_MISSING: ${name}`);
+  return value;
+}
+
+function required(name: string): string {
+  const value = argument(name);
+  if (!value) throw new Error(`UU_REMOTE_RESCUE_INSTALL_ARGUMENT_REQUIRED: ${name}`);
+  return value;
+}
+
+function writeConfig(path: string, value: Record<string, unknown>): void {
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const temporary = `${path}.${process.pid}.tmp`;
+  writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+  renameSync(temporary, path);
+}
+
+const controllerHome = resolve(argument('--controller-home') ?? process.env.FORGE_CONTROLLER_HOME ?? '');
+if (!controllerHome || controllerHome === resolve('.')) throw new Error('UU_REMOTE_RESCUE_INSTALL_CONTROLLER_HOME_REQUIRED');
+const deviceId = required('--device-id');
+const deviceName = required('--device-name');
+const wslDistro = required('--wsl-distro');
+const remoteControllerHome = required('--remote-controller-home');
+if (!remoteControllerHome.startsWith('/')) throw new Error('UU_REMOTE_RESCUE_REMOTE_CONTROLLER_HOME_ABSOLUTE_REQUIRED');
+
+const configDirectory = join(controllerSystemRoot(controllerHome), 'plugins', 'uu-remote-rescue');
+const configPath = join(configDirectory, 'config.json');
+const helperPath = resolve(argument('--helper') ?? join(dirname(fileURLToPath(import.meta.url)), 'forge-uu-remote-rescue-helper.mjs'));
+const runtimeExecutable = resolve(argument('--runtime') ?? process.execPath);
+const uuycCliPath = resolve(argument('--uuyc-cli') ?? '/usr/local/bin/uuyc-cli');
+const desktopOperatorSocketPath = resolve(argument('--desktop-socket') ?? join(homedir(), 'Library', 'Caches', 'Forge', 'desktop-operator.sock'));
+const expectedRevisionValue = argument('--expected-revision');
+const expectedRevision = expectedRevisionValue === undefined ? undefined : Number(expectedRevisionValue);
+if (expectedRevisionValue !== undefined && (!Number.isInteger(expectedRevision) || Number(expectedRevision) < 1)) {
+  throw new Error('UU_REMOTE_RESCUE_INSTALL_EXPECTED_REVISION_INVALID');
+}
+for (const [name, path] of Object.entries({ helperPath, runtimeExecutable, uuycCliPath, desktopOperatorSocketPath })) {
+  if (!isAbsolute(path)) throw new Error(`UU_REMOTE_RESCUE_INSTALL_ABSOLUTE_PATH_REQUIRED: ${name}`);
+}
+
+writeConfig(configPath, {
+  schemaVersion: 1,
+  device: { id: deviceId, name: deviceName, platform: 'windows' },
+  wsl: { distro: wslDistro, controllerHome: remoteControllerHome },
+  uuycCliPath,
+  desktopOperatorSocketPath,
+  uuBundleId: 'com.netease.uuremote',
+});
+
+const registration = installExternalPluginRegistration(
+  controllerHome,
+  createUuRemoteRescueRegistrationInput({
+    runtimeExecutable,
+    helperPath,
+    configDirectory,
+    enabled: !process.argv.includes('--disabled'),
+  }),
+  expectedRevision === undefined ? {} : { expectedRevision },
+);
+
+process.stdout.write(`${JSON.stringify({ registration, configPath }, null, 2)}\n`);

package/scripts/install-windows-host-recovery-registration.ts

@@ -0,0 +1,22 @@
+#!/usr/bin/env bun
+import { homedir } from 'os';
+import { join, resolve } from 'path';
+import { installWindowsHostRecoveryPlugin } from '../src/runtime/plugins/windows-host-recovery-install';
+
+function option(name: string): string | undefined {
+  const index = process.argv.indexOf(name);
+  return index >= 0 ? process.argv[index + 1]?.trim() : undefined;
+}
+
+const controllerHome = resolve(option('--controller-home') ?? process.env.FORGE_CONTROLLER_HOME ?? join(homedir(), '.forge', 'controller'));
+const result = installWindowsHostRecoveryPlugin({
+  controllerHome,
+  rescueRoot: option('--rescue-root'),
+  helperSource: option('--helper-source'),
+  recoveryScriptHostPath: option('--recovery-script-host') ?? option('--recovery-script'),
+  recoveryScriptWindowsPath: option('--recovery-script-windows'),
+  powershellHostPath: option('--powershell-host'),
+  powershellWindowsPath: option('--powershell-windows'),
+  enabled: !process.argv.includes('--disabled'),
+});
+process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);

package/scripts/lib/controller-home-env.sh

@@ -1,15 +1,18 @@
 #!/usr/bin/env bash
 
 forge_default_controller_home() {
-  local repo_root="${1:?repo root is required}"
-  printf '%s\n' "$repo_root/_ops/controller-home"
+  if [[ -n "${XDG_STATE_HOME:-}" ]]; then
+    printf '%s\n' "$XDG_STATE_HOME/forge/controller"
+  else
+    printf '%s\n' "${HOME:?HOME is required}/.forge/controller"
+  fi
 }
 
 forge_use_local_controller_home() {
   local repo_root="${1:?repo root is required}"
   if [[ -z "${FORGE_CONTROLLER_HOME:-}" ]]; then
     export FORGE_CONTROLLER_HOME
-    FORGE_CONTROLLER_HOME="$(forge_default_controller_home "$repo_root")"
+    FORGE_CONTROLLER_HOME="$(forge_default_controller_home)"
   fi
   mkdir -p "$FORGE_CONTROLLER_HOME"
 }