@moretea-labs/forge 1.7.2 → 1.8.1

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/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,282 @@
+#!/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, getRepository } 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',
+  'verify_stable_runtime',
+  'stage_and_activate_runtime_release',
+  'release_session_status',
+  'advance_runtime_release_session',
+  'verify_runtime_release_session_static',
+  'verify_runtime_release_session_candidate',
+  'cutover_runtime_release_session',
+  'cancel_runtime_release_session',
+  'rollback_runtime_release_session',
+  'promote_runtime_release_session_known_good',
+];
+const RELEASE_SESSION_ACTIONS = new Set([
+  'release_session_status',
+  'verify_runtime_release_session_static',
+  'verify_runtime_release_session_candidate',
+  'cutover_runtime_release_session',
+  'cancel_runtime_release_session',
+  'rollback_runtime_release_session',
+  'promote_runtime_release_session_known_good',
+]);
+const MUTATING_ACTIONS = new Set([
+  'stage_and_activate_runtime_release',
+  'advance_runtime_release_session',
+  'verify_runtime_release_session_static',
+  'verify_runtime_release_session_candidate',
+  'cutover_runtime_release_session',
+  'cancel_runtime_release_session',
+  'rollback_runtime_release_session',
+  'promote_runtime_release_session_known_good',
+]);
+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') || undefined;
+  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 (called.payload?.result?.isError === true) {
+      const message = typeof text === 'string' && text.trim() ? text.trim().slice(0, 4000) : 'Recovery tool failed.';
+      throw providerError('LOCAL_RECOVERY_TOOL_FAILED', message, false);
+    }
+    if (text) return parseJson(text, 'LOCAL_RECOVERY_TOOL_RESULT_INVALID');
+    return called.payload?.result ?? {};
+  } finally {
+    if (sessionId) {
+      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; ReleaseSession durability is independent from this transport session. */ }
+    }
+  }
+}
+
+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 releaseSessionInput(input) {
+  if (!input || typeof input !== 'object' || Array.isArray(input) || Object.keys(input).length !== 1 || typeof input.session_id !== 'string') {
+    throw providerError('LOCAL_RECOVERY_RELEASE_SESSION_ARGUMENTS_INVALID', 'ReleaseSession actions accept only session_id.');
+  }
+  const sessionId = input.session_id.trim();
+  if (sessionId.length < 8 || sessionId.length > 120) {
+    throw providerError('LOCAL_RECOVERY_RELEASE_SESSION_ID_INVALID', 'ReleaseSession session_id must be 8 to 120 characters.');
+  }
+  return { session_id: sessionId };
+}
+
+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 readRepository = injected.getRepository ?? getRepository;
+  const recoveryConfig = loadConfig(controllerHome);
+  const repositoryId = typeof recoveryConfig.primaryRuntimeSourceRepositoryId === 'string'
+    ? recoveryConfig.primaryRuntimeSourceRepositoryId.trim()
+    : '';
+  const sourceRoot = typeof recoveryConfig.primaryRuntimeSourceRoot === 'string' ? recoveryConfig.primaryRuntimeSourceRoot.trim() : '';
+
+  if (repositoryId) {
+    let repository;
+    try {
+      repository = readRepository(repositoryId, controllerHome);
+    } catch {
+      throw providerError('LOCAL_RECOVERY_SOURCE_REPOSITORY_UNRESOLVED', 'Configured primary Runtime source repository id is not one enabled registered repository.');
+    }
+    if (!repository || repository.repoId !== repositoryId || repository.enabled === false || repository.removedAt) {
+      throw providerError('LOCAL_RECOVERY_SOURCE_REPOSITORY_UNRESOLVED', 'Configured primary Runtime source repository id is not one enabled registered repository.');
+    }
+    const canonicalRoot = typeof repository.canonicalRoot === 'string' && repository.canonicalRoot.trim()
+      ? resolve(repository.canonicalRoot.trim())
+      : '';
+    if (!canonicalRoot || !isAbsolute(canonicalRoot) || !existsSync(canonicalRoot)) {
+      throw providerError('LOCAL_RECOVERY_SOURCE_CANONICAL_ROOT_UNAVAILABLE', 'Configured primary Runtime source repository canonical root is unavailable.');
+    }
+    if (sourceRoot && resolve(sourceRoot) === canonicalRoot) return recoveryConfig;
+    return persistConfig(controllerHome, {
+      primaryRuntimeSourceRoot: canonicalRoot,
+      primaryRuntimeSourceRepositoryId: repositoryId,
+    });
+  }
+
+  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.');
+  const sessionArgs = RELEASE_SESSION_ACTIONS.has(actionId) ? releaseSessionInput(input) : undefined;
+  if (!sessionArgs) assertEmptyInput(input);
+  const callTool = injected.callRecoveryTool ?? callRecoveryTool;
+  if (actionId === 'stage_and_activate_runtime_release' || actionId === 'advance_runtime_release_session') ensureSourceRepositoryProvenance(config.controllerHome, injected);
+  const args = {
+    ...(sessionArgs ?? {}),
+    ...(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>>;