@moretea-labs/forge 1.7.1 → 1.8.0

package/scripts/check-source-duplication.mjs

@@ -33,6 +33,14 @@ function isPlaceholder(paths, lines) {
   return lines <= 1 && paths.every((path) => path.endsWith('/.gitkeep'));
 }
 
+function isPureBarrelReExport(paths, lines) {
+  if (lines !== 1) return false;
+  return paths.every((path) => {
+    const source = readFileSync(path, 'utf8').trim();
+    return /^export\s+\*\s+from\s+['"]\.\/[^'"]+['"];?$/.test(source);
+  });
+}
+
 const duplicateGroups = [...byHash.values()].filter((group) => group.length > 1);
 const failures = [];
 let classifiedGroups = 0;
@@ -41,7 +49,7 @@ for (const group of duplicateGroups) {
   const paths = group.map(({ path }) => path).sort();
   const lines = group[0].lines;
   const redundantLines = lines * (group.length - 1);
-  if (isGeneratedTemplateProjection(paths) || isGuidanceAlias(paths) || isPlaceholder(paths, lines)) {
+  if (isGeneratedTemplateProjection(paths) || isGuidanceAlias(paths) || isPlaceholder(paths, lines) || isPureBarrelReExport(paths, lines)) {
     classifiedGroups += 1;
     classifiedRedundantLines += redundantLines;
     continue;

package/scripts/check-tarball-install-smoke.sh

@@ -4,10 +4,29 @@ set -euo pipefail
 ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 cd "$ROOT"
 
-PACKAGE_VERSION="$(bun -e 'const pkg = await Bun.file("package.json").json(); console.log(pkg.version)')"
+PACKAGE_VERSION="$(node -e 'const fs=require("node:fs"); const pkg=JSON.parse(fs.readFileSync("package.json","utf8")); console.log(pkg.version)')"
 TMP_DIR="$(mktemp -d)"
 trap 'rm -rf "$TMP_DIR"' EXIT
 
+CLEAN_HOME="$TMP_DIR/home"
+CONTROLLER_HOME="$TMP_DIR/controller-home"
+XDG_STATE_HOME_DIR="$TMP_DIR/xdg-state"
+NPM_CACHE_DIR="$TMP_DIR/npm-cache"
+mkdir -p "$CLEAN_HOME" "$XDG_STATE_HOME_DIR" "$NPM_CACHE_DIR"
+export HOME="$CLEAN_HOME"
+export FORGE_CONTROLLER_HOME="$CONTROLLER_HOME"
+export XDG_STATE_HOME="$XDG_STATE_HOME_DIR"
+export npm_config_cache="$NPM_CACHE_DIR"
+unset BUN_INSTALL
+# The hosting immutable Runtime may be older than the package under test. Its
+# build identity must not override the installed tarball's package version.
+unset FORGE_BUILD_VERSION
+
+if [[ -e "$FORGE_CONTROLLER_HOME" ]]; then
+  echo "[tarball-smoke] ERROR: isolated Controller Home must start empty: $FORGE_CONTROLLER_HOME" >&2
+  exit 1
+fi
+
 if [[ "$#" -gt 0 ]]; then
   TARBALL_PATH="$(cd "$(dirname "$1")" && pwd)/$(basename "$1")"
   if [[ ! -f "$TARBALL_PATH" ]]; then
@@ -16,15 +35,13 @@ if [[ "$#" -gt 0 ]]; then
   fi
   TARBALL="$(basename "$TARBALL_PATH")"
 else
-  PACK_JSON="$TMP_DIR/pack.json"
-  npm pack --json --pack-destination "$TMP_DIR" >"$PACK_JSON"
-  TARBALL="$(bun - "$PACK_JSON" <<'JS_EOF'
-const [, , path] = process.argv;
-const pack = await Bun.file(path).json();
-const entry = Array.isArray(pack) ? pack[0] : pack;
-console.log(entry.filename);
-JS_EOF
-)"
+  PACK_OUTPUT="$(npm pack --silent --pack-destination "$TMP_DIR")"
+  TARBALL="$(printf '%s\n' "$PACK_OUTPUT" | awk '/\.tgz$/ { name=$0 } END { print name }')"
+  if [[ -z "$TARBALL" ]]; then
+    echo "[tarball-smoke] ERROR: npm pack did not report a tarball filename" >&2
+    printf '%s\n' "$PACK_OUTPUT" >&2
+    exit 1
+  fi
   TARBALL_PATH="$TMP_DIR/$TARBALL"
 fi
 APP_DIR="$TMP_DIR/app"
@@ -47,11 +64,12 @@ if [[ "$VERSION" != "$PACKAGE_VERSION" ]]; then
   exit 1
 fi
 
-(cd "$TARGET_REPO" && "$CLI" status --json >/dev/null)
+(cd "$TARGET_REPO" && "$CLI" status --json >"$TMP_DIR/status.json")
 "$CLI" adopt --repo "$TARGET_REPO" --dry-run --json >"$TMP_DIR/adopt-plan.json"
-bun - "$TMP_DIR/adopt-plan.json" <<'JS_EOF'
-const [, , path] = process.argv;
-const plan = await Bun.file(path).json();
+node - "$TMP_DIR/adopt-plan.json" <<'JS_EOF'
+const fs = require('node:fs');
+const path = process.argv[2];
+const plan = JSON.parse(fs.readFileSync(path, 'utf8'));
 if (plan.protocol !== 1 || plan.command !== "adopt" || plan.apply !== false) {
   console.error("[tarball-smoke] ERROR: packaged adopt dry-run did not return protocol v1 plan JSON");
   process.exit(1);
@@ -64,4 +82,69 @@ if ! "$CLI" run check-task-workflow --help >/dev/null; then
 fi
 printf '{"prompt":"review release readiness"}\n' | "$HOOK" prompt-guard-decide >/dev/null
 
-echo "[tarball-smoke] OK: ${TARBALL} installs and packaged CLI bins start."
+SETUP_OUTPUT="$TMP_DIR/setup-open.txt"
+"$CLI" setup open --controller mcp --tunnel none --capability computer.observe.v1 --json >"$SETUP_OUTPUT"
+for marker in \
+  "forge setup: open" \
+  "Primary controller: mcp" \
+  "Install the user-level Forge Runtime" \
+  "forge runtime service install-package --controller-home"; do
+  if ! grep -Fq "$marker" "$SETUP_OUTPUT"; then
+    echo "[tarball-smoke] ERROR: packaged setup did not expose expected bootstrap marker: $marker" >&2
+    cat "$SETUP_OUTPUT" >&2
+    exit 1
+  fi
+done
+
+case "$(uname -s)" in
+  Darwin)
+    if ! grep -Eq 'Platform: macos/[^;]+; service=launchd' "$SETUP_OUTPUT"; then
+      echo "[tarball-smoke] ERROR: macOS packaged bootstrap did not select launchd" >&2
+      cat "$SETUP_OUTPUT" >&2
+      exit 1
+    fi
+    ;;
+  Linux)
+    if ! grep -Eq 'Platform: (linux|wsl2)/[^;]+; service=(systemd-user|portable)' "$SETUP_OUTPUT"; then
+      echo "[tarball-smoke] ERROR: Linux packaged bootstrap did not select systemd-user or the explicit portable fallback" >&2
+      cat "$SETUP_OUTPUT" >&2
+      exit 1
+    fi
+    ;;
+esac
+
+COMPUTER_STATUS="$TMP_DIR/computer-status.json"
+"$CLI" computer status --controller-home "$FORGE_CONTROLLER_HOME" --json >"$COMPUTER_STATUS"
+node - "$COMPUTER_STATUS" <<'JS_EOF'
+const fs = require('node:fs');
+const path = process.argv[2];
+const status = JSON.parse(fs.readFileSync(path, 'utf8'));
+if (status.schemaVersion !== 1 || status.product !== 'computer' || !Array.isArray(status.capabilities)) {
+  console.error('[tarball-smoke] ERROR: packaged Computer status did not expose the capability-level contract');
+  process.exit(1);
+}
+if (status.ready !== true) {
+  const blockers = status.capabilities.filter((entry) => entry.ready !== true);
+  if (blockers.length === 0 || blockers.some((entry) => typeof entry.reason !== 'string' || entry.reason.trim().length === 0)) {
+    console.error('[tarball-smoke] ERROR: non-ready Computer status lacked a precise capability blocker');
+    process.exit(1);
+  }
+}
+JS_EOF
+
+if [[ -d "$FORGE_CONTROLLER_HOME" ]] && grep -RIlF "$ROOT" "$FORGE_CONTROLLER_HOME" 2>/dev/null | grep -q .; then
+  echo "[tarball-smoke] ERROR: packaged Controller state captured the Forge source checkout path" >&2
+  exit 1
+fi
+
+CLI_REALPATH="$(node -e 'const fs=require("node:fs"); console.log(fs.realpathSync(process.argv[1]))' "$CLI")"
+APP_REALPATH="$(node -e 'const fs=require("node:fs"); console.log(fs.realpathSync(process.argv[1]))' "$APP_DIR")"
+case "$CLI_REALPATH" in
+  "$APP_REALPATH"/*) ;;
+  *)
+    echo "[tarball-smoke] ERROR: packaged forge executable resolved outside isolated install: $CLI_REALPATH" >&2
+    exit 1
+    ;;
+esac
+
+echo "[tarball-smoke] OK: ${TARBALL} installs under isolated HOME/Controller Home and packaged CLI bins start without Bun."

package/scripts/controller-ngrok-rotation.sh

@@ -9,9 +9,10 @@ forge_use_local_controller_home "$ROOT"
 
 REPO_ROOT="$ROOT"
 LOCAL_CLI="$ROOT/scripts/forge-local.sh"
-CONFIG_FILE_DEFAULT="$ROOT/_ops/secrets/controller-ngrok-rotation.env"
-STATE_DIR_DEFAULT="$ROOT/_ops/state"
-LOG_DIR_DEFAULT="$ROOT/_ops/logs"
+NGROK_ROTATION_ROOT="$FORGE_CONTROLLER_HOME/system/ngrok-rotation"
+CONFIG_FILE_DEFAULT="$NGROK_ROTATION_ROOT/secrets/controller-ngrok-rotation.env"
+STATE_DIR_DEFAULT="$NGROK_ROTATION_ROOT/state"
+LOG_DIR_DEFAULT="$NGROK_ROTATION_ROOT/logs"
 
 CONFIG_FILE="${FORGE_NGROK_ROTATION_CONFIG:-$CONFIG_FILE_DEFAULT}"
 STATE_DIR="${FORGE_NGROK_ROTATION_STATE_DIR:-$STATE_DIR_DEFAULT}"
@@ -40,7 +41,7 @@ Usage: scripts/controller-ngrok-rotation.sh <start|stop|status|logs|run> [option
 
 Options:
   --repo <path>     Repository root (default: repo root containing this script)
-  --config <path>   Rotation config file (default: _ops/secrets/controller-ngrok-rotation.env)
+  --config <path>   Rotation config file (default: Controller Home system/ngrok-rotation/secrets/controller-ngrok-rotation.env)
   --tail <lines>    Approximate number of log lines for `logs` (default: 200)
 EOF
 }

package/scripts/create-project-dirs.sh

@@ -5,7 +5,7 @@
 # Creates the three-layer project structure:
 #   IMMUTABLE LAYER (资产层): specs, contracts, tests
 #   MUTABLE LAYER (厕纸层): src
-#   SUPPORTING (支撑层): docs, deploy, _ops, artifacts, tasks, plans
+#   SUPPORTING (支撑层): authored docs/deploy/tasks only; Runtime state lives in Controller Home
 
 set -euo pipefail
 
@@ -23,31 +23,14 @@ ASSETS_WORKFLOW_CONTRACT="$SCRIPT_DIR/../assets/workflow-contract.v1.json"
 
 write_runtime_gitignore_block() {
   local extra_entries=""
-  local helper_entries=""
   if pi_should_enable_factor_factory "$(pi_plan_type)"; 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 not materialized by the v1.5 scaffold, so do not
+  # manufacture ignore entries for files that should never be created.
   pi_ensure_gitignore_block ".gitignore" "$PI_DEFAULT_GITIGNORE_CONTENT" "$extra_entries" "apply"
 }
 
-write_templates() {
-  pi_install_templates "$PWD" "$ASSETS_TEMPLATES_DIR" "apply"
-}
-
-install_workflow_helpers() {
-  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() {
   pi_install_workflow_contract "$PWD" "$ASSETS_WORKFLOW_CONTRACT" "apply"
 }
@@ -84,26 +67,12 @@ if pi_should_generate_full_docs; then
   mkdir -p docs/guides
   mkdir -p docs/archives
 fi
-mkdir -p .ai/hooks
-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/security
-mkdir -p .ai/harness/runs
 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
 
 # ===== Initial Files =====
@@ -131,25 +100,6 @@ Do not duplicate that execution checklist here. Record only work intentionally d
 | (none) | No deferred medium/long-term goal recorded yet. | Keep the first sprint bounded. | Add a row when a real follow-up is postponed. |
 TASK_TODO_EOF
 
-cat > tasks/current.md << 'TASK_CURRENT_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.
-TASK_CURRENT_EOF
-
 cat > tasks/lessons.md << 'TASK_LESSONS_EOF'
 # Lessons Learned (Self-Improvement Loop)
 
@@ -171,22 +121,17 @@ cat > docs/researches/README.md << 'RESEARCH_README_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.
 RESEARCH_README_EOF
 
-write_templates
-install_workflow_helpers
 install_workflow_contract
-install_hook_assets
 if pi_should_enable_factor_factory "$(pi_plan_type)"; then
   pi_install_factor_factory "$PWD" "$ASSETS_FACTOR_FACTORY_DIR" "$SCRIPT_DIR" "apply"
 fi
 ensure_task_sync_package_script
 write_runtime_gitignore_block
 
-pi_install_hook_adapters "$PWD" "$ASSETS_HOOKS_DIR" "apply"
-pi_print_codex_hook_trust_notice
 
 cat > docs/spec.md << 'DOCS_SPEC_EOF'
 # Product Spec
@@ -194,20 +139,8 @@ cat > docs/spec.md << 'DOCS_SPEC_EOF'
 > **Status**: Draft
 > **Owner**: Planner
 DOCS_SPEC_EOF
-# 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.
 
 cat > interfaces/types.ts << 'INTERFACES_TYPES_EOF'
 /**
@@ -244,6 +177,9 @@ bun test --watch      # Watch mode
 ```
 TESTS_README_EOF
 
+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"
 else

package/scripts/forge-local-recovery-helper.mjs

@@ -0,0 +1,204 @@
+#!/usr/bin/env bun
+import { createHash } from 'crypto';
+import { existsSync, readFileSync } from 'fs';
+import { isAbsolute, join, resolve } from 'path';
+import { pathToFileURL } from 'url';
+import { resolveControllerHome } from '../src/cli/repositories/controller-home.ts';
+import { findRegisteredRepositoryByCheckoutRoot } from '../src/cli/repositories/registry.ts';
+import { createRecoveryConfig, gatewayToken, loadRecoveryConfig } from '../src/runtime/standalone-recovery/core.ts';
+
+export const PLUGIN_ID = 'local_recovery';
+export const PLUGIN_VERSION = '0.1.0';
+export const PROTOCOL_VERSION = 1;
+export const CAPABILITIES = ['forge.local_recovery.transport.v1'];
+export const ACTIONS = ['runtime_status', 'list_releases', 'stage_and_activate_runtime_release'];
+const MUTATING_ACTIONS = new Set(['stage_and_activate_runtime_release']);
+const LOOPBACK_HOSTS = new Set(['127.0.0.1', 'localhost', '::1']);
+
+function providerError(code, message, retryable = false, details) {
+  const error = new Error(message);
+  error.code = code;
+  error.retryable = retryable;
+  if (details) error.details = details;
+  return error;
+}
+
+function parseJson(text, code) {
+  try { return JSON.parse(text); } catch { throw providerError(code, 'Local Recovery provider JSON is invalid.'); }
+}
+
+export function validateProviderConfig(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw providerError('LOCAL_RECOVERY_CONFIG_INVALID', 'Local Recovery provider config must be an object.');
+  const keys = Object.keys(value);
+  if (keys.some((key) => key !== 'controllerHome')) throw providerError('LOCAL_RECOVERY_CONFIG_INVALID', 'Local Recovery provider config accepts only controllerHome.');
+  if (typeof value.controllerHome !== 'string' || !value.controllerHome.trim() || !isAbsolute(value.controllerHome.trim())) {
+    throw providerError('LOCAL_RECOVERY_CONTROLLER_HOME_REQUIRED', 'Local Recovery provider requires one absolute controllerHome.');
+  }
+  return { controllerHome: resolve(value.controllerHome.trim()) };
+}
+
+export function loadProviderConfig() {
+  const path = join(process.cwd(), 'config.json');
+  if (!existsSync(path)) return { controllerHome: resolveControllerHome() };
+  return validateProviderConfig(parseJson(readFileSync(path, 'utf8'), 'LOCAL_RECOVERY_CONFIG_INVALID'));
+}
+
+function recoveryEndpoint(config) {
+  const gateway = config.gateway;
+  if (!gateway || typeof gateway.host !== 'string' || !LOOPBACK_HOSTS.has(gateway.host) || !Number.isInteger(gateway.port) || gateway.port < 1 || gateway.port > 65535) {
+    throw providerError('LOCAL_RECOVERY_GATEWAY_INVALID', 'Installed Recovery Gateway must use one configured loopback endpoint.');
+  }
+  const host = gateway.host === '::1' ? '[::1]' : gateway.host;
+  return `http://${host}:${gateway.port}/recovery/mcp`;
+}
+
+function rpcPayload(text, contentType = '') {
+  if (/text\/event-stream/i.test(contentType)) {
+    const data = text.split(/\r?\n/).find((line) => line.startsWith('data: '));
+    if (!data) throw providerError('LOCAL_RECOVERY_MCP_RESPONSE_INVALID', 'Recovery MCP SSE response did not contain data.');
+    return parseJson(data.slice(6), 'LOCAL_RECOVERY_MCP_RESPONSE_INVALID');
+  }
+  return parseJson(text || '{}', 'LOCAL_RECOVERY_MCP_RESPONSE_INVALID');
+}
+
+async function postRpc(fetchImpl, endpoint, token, body, sessionId) {
+  const response = await fetchImpl(endpoint, {
+    method: 'POST',
+    headers: {
+      authorization: `Bearer ${token}`,
+      'content-type': 'application/json',
+      accept: 'application/json, text/event-stream',
+      ...(sessionId ? { 'mcp-session-id': sessionId } : {}),
+    },
+    body: JSON.stringify(body),
+  });
+  const text = await response.text();
+  if (!response.ok) throw providerError('LOCAL_RECOVERY_MCP_HTTP_FAILED', `Recovery MCP returned HTTP ${response.status}.`, true, { status: response.status });
+  return { response, payload: text ? rpcPayload(text, response.headers.get('content-type') ?? '') : undefined };
+}
+
+export async function callRecoveryTool(controllerHome, toolName, args = {}, injected = {}) {
+  const loadConfig = injected.loadRecoveryConfig ?? loadRecoveryConfig;
+  const readToken = injected.gatewayToken ?? gatewayToken;
+  const fetchImpl = injected.fetch ?? fetch;
+  const config = loadConfig(controllerHome);
+  if (resolve(config.controllerHome) !== resolve(controllerHome)) throw providerError('LOCAL_RECOVERY_CONTROLLER_HOME_MISMATCH', 'Installed Recovery config belongs to a different Controller Home.');
+  const endpoint = recoveryEndpoint(config);
+  const token = readToken(config);
+  if (!token) throw providerError('LOCAL_RECOVERY_GATEWAY_TOKEN_UNAVAILABLE', 'Installed Recovery Gateway token is unavailable or expired.');
+  const initialized = await postRpc(fetchImpl, endpoint, token, {
+    jsonrpc: '2.0', id: 1, method: 'initialize', params: {
+      protocolVersion: '2025-06-18', capabilities: {}, clientInfo: { name: 'forge-local-recovery-provider', version: PLUGIN_VERSION },
+    },
+  });
+  const sessionId = initialized.response.headers.get('mcp-session-id');
+  if (!sessionId) throw providerError('LOCAL_RECOVERY_MCP_SESSION_MISSING', 'Recovery MCP initialize did not return a session id.');
+  try {
+    await postRpc(fetchImpl, endpoint, token, { jsonrpc: '2.0', method: 'notifications/initialized' }, sessionId);
+    const called = await postRpc(fetchImpl, endpoint, token, {
+      jsonrpc: '2.0', id: 2, method: 'tools/call', params: { name: toolName, arguments: args },
+    }, sessionId);
+    if (called.payload?.error) throw providerError('LOCAL_RECOVERY_TOOL_FAILED', String(called.payload.error?.message ?? 'Recovery tool failed.'), false);
+    const content = called.payload?.result?.content;
+    const text = Array.isArray(content) ? content.find((entry) => entry?.type === 'text' && typeof entry.text === 'string')?.text : undefined;
+    if (text) return parseJson(text, 'LOCAL_RECOVERY_TOOL_RESULT_INVALID');
+    return called.payload?.result ?? {};
+  } finally {
+    try {
+      await fetchImpl(endpoint, {
+        method: 'DELETE',
+        headers: { authorization: `Bearer ${token}`, accept: 'application/json, text/event-stream', 'mcp-session-id': sessionId },
+      });
+    } catch { /* Session cleanup is best effort; Recovery owns mutation transaction durability. */ }
+  }
+}
+
+function assertEmptyInput(input) {
+  if (!input || typeof input !== 'object' || Array.isArray(input) || Object.keys(input).length !== 0) {
+    throw providerError('LOCAL_RECOVERY_ARGUMENTS_FORBIDDEN', 'Local Recovery actions accept no caller endpoint, path, command, token, release, source, or tunnel arguments.');
+  }
+}
+
+function mutationRequestId(requestId) {
+  return `local-recovery:${createHash('sha256').update(String(requestId)).digest('hex').slice(0, 32)}`;
+}
+
+export function ensureSourceRepositoryProvenance(controllerHome, injected = {}) {
+  const loadConfig = injected.loadRecoveryConfig ?? loadRecoveryConfig;
+  const persistConfig = injected.createRecoveryConfig ?? createRecoveryConfig;
+  const findRepository = injected.findRegisteredRepositoryByCheckoutRoot ?? findRegisteredRepositoryByCheckoutRoot;
+  const recoveryConfig = loadConfig(controllerHome);
+  if (typeof recoveryConfig.primaryRuntimeSourceRepositoryId === 'string' && recoveryConfig.primaryRuntimeSourceRepositoryId.trim()) return recoveryConfig;
+  const sourceRoot = typeof recoveryConfig.primaryRuntimeSourceRoot === 'string' ? recoveryConfig.primaryRuntimeSourceRoot.trim() : '';
+  if (!sourceRoot) throw providerError('LOCAL_RECOVERY_SOURCE_ROOT_UNAVAILABLE', 'Installed Recovery config does not identify the primary Runtime source root.');
+  const repository = findRepository(sourceRoot, controllerHome);
+  if (!repository?.repoId) throw providerError('LOCAL_RECOVERY_SOURCE_REPOSITORY_UNRESOLVED', 'Configured primary Runtime source root is not owned by one registered repository.');
+  return persistConfig(controllerHome, {
+    primaryRuntimeSourceRoot: sourceRoot,
+    primaryRuntimeSourceRepositoryId: repository.repoId,
+  });
+}
+
+export async function executeAction(actionId, input, providerConfig, injected = {}) {
+  const config = validateProviderConfig(providerConfig);
+  if (!ACTIONS.includes(actionId)) throw providerError('LOCAL_RECOVERY_ACTION_UNSUPPORTED', 'Unsupported Local Recovery action.');
+  assertEmptyInput(input);
+  const callTool = injected.callRecoveryTool ?? callRecoveryTool;
+  if (actionId === 'stage_and_activate_runtime_release') ensureSourceRepositoryProvenance(config.controllerHome, injected);
+  const args = MUTATING_ACTIONS.has(actionId) ? { request_id: mutationRequestId(injected.requestId ?? actionId) } : {};
+  return await callTool(config.controllerHome, actionId, args, injected);
+}
+
+function manifest() {
+  return {
+    id: PLUGIN_ID,
+    name: 'Forge Local Recovery Transport',
+    version: PLUGIN_VERSION,
+    protocolVersion: '1.0',
+    mode: 'external',
+    scope: 'controller',
+    provider: 'local-recovery-gateway',
+    capabilities: CAPABILITIES,
+    actions: ACTIONS,
+  };
+}
+
+async function providerAction(request) {
+  const config = loadProviderConfig();
+  if (request.actionId === 'manifest') return manifest();
+  if (request.actionId === 'health') {
+    try {
+      const status = await executeAction('runtime_status', {}, config, { requestId: request.requestId });
+      return { state: 'ready', recovery: status };
+    } catch (error) {
+      return { state: 'degraded', warnings: [error?.code || 'LOCAL_RECOVERY_UNAVAILABLE'] };
+    }
+  }
+  return await executeAction(request.actionId, request.input, config, { requestId: request.requestId });
+}
+
+export async function runManagedHelper() {
+  process.stdout.write(`${JSON.stringify({ schemaVersion: 1, type: 'handshake', protocolVersion: PROTOCOL_VERSION, pluginId: PLUGIN_ID, helperVersion: PLUGIN_VERSION, capabilities: CAPABILITIES })}\n`);
+  let raw = '';
+  for await (const chunk of process.stdin) raw += chunk;
+  const line = raw.split(/\r?\n/).find((entry) => entry.trim());
+  if (!line) throw providerError('LOCAL_RECOVERY_REQUEST_MISSING', 'Managed plugin request is missing.');
+  const request = parseJson(line, 'LOCAL_RECOVERY_REQUEST_INVALID');
+  if (request.schemaVersion !== 1 || request.type !== 'execute' || typeof request.requestId !== 'string' || typeof request.actionId !== 'string' || !request.input || typeof request.input !== 'object' || Array.isArray(request.input)) {
+    throw providerError('LOCAL_RECOVERY_REQUEST_INVALID', 'Managed plugin request envelope is invalid.');
+  }
+  try {
+    const result = await providerAction(request);
+    process.stdout.write(`${JSON.stringify({ schemaVersion: 1, type: 'result', requestId: request.requestId, ok: true, result })}\n`);
+  } catch (error) {
+    process.stdout.write(`${JSON.stringify({ schemaVersion: 1, type: 'result', requestId: request.requestId, ok: false, error: { code: error?.code || 'LOCAL_RECOVERY_FAILED', message: String(error?.message || 'Local Recovery provider failed.').replace(/(token|secret|password|authorization)\s*[=:]\s*\S+/gi, '$1=[redacted]').slice(0, 1000), retryable: error?.retryable === true, ...(error?.details ? { details: error.details } : {}) } })}\n`);
+  }
+}
+
+const invokedDirectly = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (invokedDirectly) {
+  runManagedHelper().catch((error) => {
+    process.stderr.write(`LOCAL_RECOVERY_HELPER_FATAL: ${String(error?.message || error).replace(/(token|secret|password|authorization)\s*[=:]\s*\S+/gi, '$1=[redacted]').slice(0, 1000)}\n`);
+    process.exitCode = 1;
+  });
+}

package/scripts/forge-uu-remote-rescue-helper.d.mts

@@ -0,0 +1,31 @@
+export interface UuRemoteRescueConfig {
+  schemaVersion: 1;
+  device: {
+    id: string;
+    name: string;
+    platform: 'windows';
+  };
+  wsl: {
+    distro: string;
+    controllerHome: string;
+  };
+  uuycCliPath: string;
+  desktopOperatorSocketPath: string;
+  uuBundleId: string;
+}
+
+export function validateConfig(value: unknown): UuRemoteRescueConfig;
+
+export function serviceUnits(controllerHome: string): {
+  runtime: string;
+  connector: string;
+  recoveryGateway: string;
+  recoveryWatchdog: string;
+};
+
+export function executeAction(
+  actionId: string,
+  input: Record<string, unknown>,
+  configInput: unknown,
+  injected?: Record<string, unknown>,
+): Promise<Record<string, unknown>>;