@moretea-labs/forge 1.7.2 → 1.8.0

package/assets/partials/05-workflow.partial.md

@@ -1,79 +1,24 @@
-### Plan Annotation Protocol
-
-Use `docs/researches/` for deep codebase understanding, `docs/spec.md` for stable intent, `plans/` for timestamped execution plans, and `tasks/todos.md` for deferred medium/long-term goals with tradeoffs and revisit triggers.
+### Forge Workflow Protocol
 
 ```yaml
-PLAN_LOOP:
-  MODE: {{RUNTIME_PROFILE}}
-  RECOVERY: {{RECOVERY_PROFILE}}
+FORGE_WORKFLOW:
   STATE: {{STATE_PROFILE}}
-  CONTEXT: {{CONTEXT_PROFILE}}
-  PHASES: research -> spec -> plan -> contract -> implement -> verify -> check -> review -> handoff
-  RESEARCH_DIR: docs/researches/
-  SPEC_FILE: docs/spec.md
-  PLAN_DIR: plans/
-  PLAN_ARCHIVE: plans/archive/
-  ACTIVE_PLAN_RULE: .ai/harness/active-plan marker is scoped to this worktree; .ai/harness/active-worktree records the owner; legacy .claude/.active-plan is fallback only
-  PLAN_SWITCH: .ai/harness/scripts/switch-plan.sh --plan <plan-file> | --list
-  DEFERRED_LEDGER: tasks/todos.md
-  TODO_ARCHIVE: tasks/archive/
-  CONTRACT_DIR: tasks/contracts/
-  REVIEW_DIR: tasks/reviews/
-  NOTES_DIR: tasks/notes/
-  POLICY_FILE: .ai/harness/policy.json
-  CHECKS_FILE: .ai/harness/checks/latest.json
-  HANDOFF_FILE: .ai/harness/session/continuation.md
-  EVENTS_FILE: .ai/harness/events.jsonl
-  RUNS_DIR: .ai/harness/runs/
-  LESSONS_FILE: tasks/lessons.md
-  CONTEXT_MAP: .ai/context/context-map.json
-  ANNOTATION_GUARD: do not implement until plan Status is "Approved"
-  CONTRACT_GUARD: do not mark done until contract exit criteria pass; then perform a fresh semantic impact review
-  EXECUTION_CONTEXT: contract-level work starts in a linked codex/<slug> worktree when policy enables it; primary worktree warning by default; enforce via .claude/.require-worktree
-  CONTRACT_WORKTREE_FINISH: run Forge /review, fill the review artifact from that verdict, then .ai/harness/scripts/contract-worktree.sh finish
-  COMMIT_POLICY: explicit commits after green checks; no automatic checkpoint hook
+  PHASES: understand -> design -> execute -> verify -> review -> terminalize
+  REPO_AUTHORED:
+    - docs/spec.md
+    - docs/researches/
+    - tasks/todos.md
+    - tasks/lessons.md
+    - forge.config.json
+  RUNTIME_AUTHORITY: Controller Home
 ```
 
-### Agentic Skill Routing
-
-- Product discovery, early demand shaping, or "is this worth building" -> gstack `office-hours`.
-- Complex engineering plans, architecture lock-in, or cross-module refactors -> gstack `plan-eng-review`.
-- UI/UX or design-system plans -> gstack `plan-design-review`.
-- Small or medium feature plans -> Forge `/plan`.
-- Bugs, regressions, crashes, errors, or failing tests -> Forge `/debug`.
-- Implemented diffs, pre-merge checks, or release follow-through -> Forge `/review`.
-- Architecture diagrams or system-flow diagrams -> Markdown Mermaid first, `mermaid` for optional human HTML.
-- Use P1/P2/P3 as the shared due-diligence protocol; report it explicitly for `plan-eng-review`, `/hunt`, risky refactors, deployments, auth/payment/data work, and shared contracts.
-- Hooks may emit advisory Forge `/review` and `/health` route hints, but must not auto-run skills or vendor skill bodies.
-
-### Task Management Protocol
-
-Core rules (canonical source: see Workflow Orchestration section below):
-- `docs/spec.md` is product truth; `plans/` is execution truth.
-- `tasks/contracts/`, `tasks/reviews/`, and `tasks/notes/` are done gates; hooks are accelerators only.
-- Treat `.ai/harness/active-plan` as authoritative only for its owning worktree; `.ai/harness/active-worktree` records that owner; `.claude/.active-plan` is a legacy fallback during transition.
-- Require plan/contract workflow inventory before implementation: active plan, owning worktree, contract, review, notes, deferred ledger, checks, runs, scope owner, switching rule, and worktree path.
-- Mark done only with verification evidence.
-- Durable progress lives in `tasks/workstreams/`; release history belongs in `docs/CHANGELOG.md`.
-
-### Harness References
-
-- `docs/reference-configs/harness-overview.md`
-- `docs/reference-configs/sprint-contracts.md`
-- `docs/reference-configs/evaluator-rubric.md`
-- `docs/reference-configs/handoff-protocol.md`
-- `docs/reference-configs/changelog-versioning.md`
-- `docs/reference-configs/git-strategy.md`
-- `docs/reference-configs/release-deploy.md`
-- `docs/reference-configs/agentic-development-flow.md`
-- `docs/reference-configs/external-tooling.md`
-
-{{#IF FACTOR_FACTORY_ENABLED}}
-### Factor Research Protocol
+Rules:
 
-- `tasks/factors/registry.json` is the authoritative factor inventory for Plan G projects.
-- Use `bash .ai/harness/scripts/factor-lab-new.sh --name <slug>` to create a candidate workspace.
-- Use `bash .ai/harness/scripts/factor-lab-promote.sh --name <slug>` only after `hypothesis.md` and `backtest-summary.md` exist.
-- Use `bash .ai/harness/scripts/factor-lab-reject.sh --name <slug> --reason "<reason>"` to reject a candidate with an auditable reason.
-- Use `bash .ai/harness/scripts/factor-lab-check.sh` to validate registry state, candidate completeness, and promoted directory drift.
-{{/IF}}
+- Prompt/agent files explain intent; they are not execution, authorization, lifecycle, or completion authority.
+- Use direct execution for bounded understood work. Create durable Requirement/Plan/Work only when decomposition, continuity, isolation, scheduling, recovery, or external effects justify it.
+- Before high-risk or architecture-changing mutation, close the cross-cutting Engineering Design contract instead of reviewing only the touched module.
+- A successor Plan must explicitly reconcile every unfinished predecessor obligation as KEEP/CHANGE/DEFER/DROP.
+- Mutable checks, sessions, leases, Work/Plan state, Plugin config, run receipts, and caches belong to Controller Home, never new repo-local `.ai/harness` or generated `tasks/*` lifecycle files.
+- Human-authored research, stable product intent, deferred goals, lessons, and intentionally maintained planning documents may remain in Git.
+- Completion requires exact verification/review evidence and terminal cleanup; no prompt text or generated status Markdown may declare semantic success.

package/assets/partials/07-footer.partial.md

@@ -18,7 +18,7 @@ CLAUDE.md is a routing card. Keep context minimal and load only what the current
 | Evaluator verdict | `tasks/reviews/<plan-stem>.review.md` |
 | Implementation notes | `tasks/notes/<plan-stem>.notes.md` |
 | Latest verification evidence | `.ai/harness/checks/latest.json` |
-| Historical implementation context | `plans/archive/` and `tasks/archive/` |
+| Historical implementation context | Git history and durable Control Plane Plan/Work/Verification evidence |
 | Agentic skill routing | `docs/reference-configs/agentic-development-flow.md` |
 | Harness runtime model | `docs/reference-configs/harness-overview.md` |
 | Sprint contract rules | `docs/reference-configs/sprint-contracts.md` |

package/assets/partials-agents/02-operating-mode.partial.md

@@ -23,8 +23,7 @@
 - Lessons contract: `tasks/lessons.md`.
 - Plan directory: `plans/` (timestamped plans).
 - Active plan rule: `.ai/harness/active-plan` for this worktree when present, `.ai/harness/active-worktree` as owner marker, and `.claude/.active-plan` legacy fallback during transition. Do not infer active execution from the latest plan.
-- Plan archive: `plans/archive/`.
-- Todo archive: `tasks/archive/`.
+- Terminal repo-local workflow artifacts are deleted only after their exact final state is represented by Git; do not maintain plan/todo archive directories.
 - Shared automation layer: `.ai/hooks/`.
 - Host adapters: user-level `~/.claude/settings.json` and `~/.codex/hooks.json` call `forge-hook`, falling back to `forge hook`, which dispatches into opted-in repos.
 - External reference cache: `_ref/` is an occasional ignored external checkout cache, read/refresh-only comparison material, and must stay out of commits; decisions based on it must cite repo+commit/tag+path in notes or research.

package/assets/partials-agents/04-task-protocol.partial.md

@@ -1,69 +1,24 @@
-## Task Management Protocol
+## Work Management Protocol
 
 ```yaml
-TASK_SOURCES:
+AUTHORED_REPO_SOURCES:
   - docs/spec.md
   - docs/researches/
   - tasks/todos.md
-  - tasks/contracts/
-  - tasks/reviews/
-  - tasks/notes/
   - tasks/lessons.md
-  - .ai/harness/checks/latest.json
-  - .ai/harness/session/continuation.md
-  - plans/
+  - forge.config.json
 
-PHASES: research -> spec -> plan -> contract -> implement -> verify -> check -> review -> handoff
+DURABLE_RUNTIME_AUTHORITY:
+  - Controller Home Requirement / Plan / Work / ControllerRound
+  - Process / Schedule / resource claims / authorization / evidence / review
 
-ARCHIVE:
-  PLAN: plans/archive/
-  TODO: tasks/archive/
-
-RULES:
-  - Treat repo-local artifact files as the primary cross-agent workflow contract
-  - For non-chat tasks, sync tasks/ whenever substantive work changes the repo
-  - Research first for unfamiliar areas and persist findings in docs/researches/
-  - Keep stable product intent in docs/spec.md
-  - Plan with trade-offs in plans/plan-{timestamp}-{slug}.md
-  - Treat .ai/harness/active-plan as authoritative only for this worktree; .ai/harness/active-worktree records the owner; .claude/.active-plan is a legacy fallback during transition
-  - Keep multiple active plans in parallel worktrees when tasks diverge; fill workflow inventory before implementation: active plan, owning worktree, contract, review, notes, deferred ledger, checks, runs, scope owner, switching rule, and worktree path
-  - Process annotation notes before implementing
-  - Project approved plans with .ai/harness/scripts/plan-to-todo.sh; the execution checklist stays in the plan ## Task Breakdown
-  - Define task contracts in tasks/contracts/{plan-stem}.contract.md
-  - Fill tasks/reviews/{plan-stem}.review.md from Forge /review after verification
-  - Record only non-obvious implementation decisions, deviations, tradeoffs, and open questions in tasks/notes/{plan-stem}.notes.md
-  - Verify contracts before claiming completion
-  - Require review pass before claiming completion
-  - Keep tasks/todos.md limited to deferred medium/long-term goals, with tradeoff and revisit trigger; do not duplicate plan Task Breakdown
-  - Record correction-derived prevention rules in tasks/lessons.md
-  - Distill repeated corrections into tasks/lessons.md instead of keeping them in tasks/todos.md
-  - Capture deep findings and hidden contracts in docs/researches/
-  - Keep sprint-level verification notes, behavior diffs, and residual risks in tasks/reviews/{plan-stem}.review.md
-  - Do not use implementation notes as durable memory or task logs; archive them on close and promote only after evidence shows the rule should outlive the sprint
-  - Promote implementation-ready follow-up work into a new plans/plan-{timestamp}-{slug}.md file; keep deferred goals in tasks/todos.md only when intentionally postponed
-  - Treat `.ai/hooks/` as the shared automation entrypoint when repo scripts reference hook-backed workflow checks
-  - Treat user-level `~/.claude/settings.json` and `~/.codex/hooks.json` as host adapters; do not add repo-local project hook adapters unless explicitly migrating legacy config
-  - For Codex sessions, treat `bash .ai/harness/scripts/check-task-sync.sh` and `bash .ai/harness/scripts/check-task-workflow.sh --strict` as required repo-local checks
-  - Before ending a session, refresh `.ai/harness/session/continuation.md` when the task state changed
-  - Update `tasks/workstreams/` only when durable capability progress changes
-  - Archive completed/abandoned plans and todos with metadata
-{{#IF FACTOR_FACTORY_ENABLED}}
-  - Treat `tasks/factors/registry.json` as the source of truth for factor lifecycle state
-  - Create factor candidates with `bash .ai/harness/scripts/factor-lab-new.sh --name <slug>`
-  - Promote factors only after hypothesis and backtest summary artifacts exist
-  - Run `bash .ai/harness/scripts/factor-lab-check.sh` before claiming factor-lab work is complete
-{{/IF}}
-
-ACTIVE_PLAN:
-  - .ai/harness/active-plan selects the current active plan only for its owning worktree; .ai/harness/active-worktree records that owner; .claude/.active-plan is a legacy fallback during transition
-
-STATUS:
-  ENUM: [Draft, Annotating, Approved, Executing, Archived]
-  LOCATION: "> **Status**: {value}" line in plan file (must be exact, no trailing whitespace)
-  TRANSITIONS:
-    - Draft -> Annotating -> Approved -> Executing -> Archived
-    - Annotating -> Draft (rollback when plan direction needs rethinking)
-  GUARD: do not implement when status is Draft or Annotating
+PHASES: understand -> design -> implement -> verify -> review -> cleanup
 ```
 
----
+Rules:
+
+- Do not recreate `tasks/contracts`, `tasks/reviews`, `tasks/current.md`, `tasks/workstreams`, or `.ai/harness` as current machine authority. They are legacy migration inputs only.
+- Plan is a late semantic commitment, not ceremony for every non-trivial edit.
+- High-risk/cross-cutting work must have current Context Closure and Engineering Design evidence before mutation.
+- Successor Plans cannot silently drop unresolved predecessor objectives, acceptance criteria, non-goals, decisions, stop conditions, or replan conditions.
+- Work completion is bound to exact implementation review and verification evidence; a chat or Markdown status claim is never enough.

package/assets/partials-agents/06-quality-safety.partial.md

@@ -1,23 +1,18 @@
 ## Quality & Safety
 
 ### Verification Gate
-- Never mark work done without verification output.
-- Run impact-based checks: typecheck, tests, lint/build.
-- Run `bash .ai/harness/scripts/check-task-workflow.sh --strict` before claiming the workflow is clean.
-- Run `bash .ai/harness/scripts/verify-contract.sh --contract <active-plan-contract> --strict` before any done/completed response when the active plan has a contract.
-- Require the matching `tasks/reviews/<plan-stem>.review.md` to recommend pass before claiming completion.
-- Require the matching `tasks/notes/<plan-stem>.notes.md` to capture material implementation decisions before review.
+- Never mark work done without current verification evidence for the exact candidate.
+- Run impact-based type/tests/lint/build checks through Forge Process Runtime.
+- High-risk or architecture-changing work requires the current Engineering Design contract and independent implementation review evidence.
+- If a Plan is involved, verify its declared acceptance criteria and predecessor-obligation continuity; do not infer semantic acceptance from passing commands alone.
 
 ### Safety Rules
-- Do not silently expand scope beyond approved plan.
-- If unexpected repo changes appear, stop and ask.
-- Prefer modifying existing files over unnecessary file creation.
+- Do not silently expand scope beyond the user/Work/Plan authority.
+- Preserve single-writer, authorization, resource fencing, replay/idempotency, and lifecycle cleanup boundaries.
+- Unexpected unrelated dirty work is placement/ownership evidence: isolate or reconcile it rather than absorbing it.
+- Prefer strengthening an existing general capability over adding incident-specific helpers or parallel lifecycle owners.
 
 ### Final Response Contract
-1. What changed — list modified files with one-line summary each
-2. Verification evidence — paste tool output: test results, build logs, or `git diff --stat`
-3. Which workflow artifacts were updated — list `tasks/*.md`, `docs/spec.md`, or `.ai/harness/*` files and what changed in each
-4. Known risks/gaps — bullet list with severity tag: `[HIGH]`, `[MEDIUM]`, `[LOW]`
-5. Optional next steps — actionable items the next session or user should address
-
----
+1. What changed
+2. Verification actually run
+3. Residual blockers/risks

package/assets/partials-agents/08-deep-docs.partial.md

@@ -15,8 +15,7 @@
 - `.ai/harness/checks/latest.json`: structured verification evidence
 - `.ai/harness/runs/`: immutable run snapshots for verification audit
 - `.ai/context/context-map.json`: progressive context index for primary functional-block `CLAUDE.md` and `AGENTS.md` files
-- `plans/archive/`: archived plans and outcomes
-- `tasks/archive/`: archived todo snapshots
+- Terminal plan/task history: Git history plus durable Control Plane evidence; do not create repository archive directories.
 - `docs/reference-configs/agentic-development-flow.md`: gstack/Waza routing, P1/P2/P3 reporting triggers, and daily flow
 - `docs/reference-configs/harness-overview.md`: orchestration playbook
 - `docs/reference-configs/external-tooling.md`: gstack/Waza/gbrain routing, Codex-first Waza sync, and required CodeGraph readiness commands

package/assets/plan-map.json

@@ -34,7 +34,7 @@
         "evaluation": "browser-qa",
         "handoff": "artifact-aware",
         "recovery": "hybrid",
-        "state": "file-backed"
+        "state": "controller-home"
       },
       "defaultLsp": "typescript-lsp",
       "defaultTemplateVariables": {
@@ -60,7 +60,7 @@
         "evaluation": "browser-qa",
         "handoff": "artifact-aware",
         "recovery": "hybrid",
-        "state": "file-backed"
+        "state": "controller-home"
       },
       "defaultLsp": "typescript-lsp",
       "defaultTemplateVariables": {
@@ -86,7 +86,7 @@
         "evaluation": "browser-qa",
         "handoff": "artifact-aware",
         "recovery": "hybrid",
-        "state": "file-backed"
+        "state": "controller-home"
       },
       "defaultLsp": "typescript-lsp",
       "defaultTemplateVariables": {
@@ -112,7 +112,7 @@
         "evaluation": "command-qa",
         "handoff": "artifact-aware",
         "recovery": "hybrid",
-        "state": "file-backed"
+        "state": "controller-home"
       },
       "defaultLsp": "typescript-lsp",
       "defaultTemplateVariables": {
@@ -138,7 +138,7 @@
         "evaluation": "browser-qa",
         "handoff": "artifact-aware",
         "recovery": "hybrid",
-        "state": "file-backed"
+        "state": "controller-home"
       },
       "defaultLsp": "typescript-lsp",
       "defaultTemplateVariables": {
@@ -163,7 +163,7 @@
         "evaluation": "browser-qa",
         "handoff": "artifact-aware",
         "recovery": "hybrid",
-        "state": "file-backed"
+        "state": "controller-home"
       },
       "defaultLsp": "typescript-lsp",
       "defaultTemplateVariables": {
@@ -190,7 +190,7 @@
         "evaluation": "command-qa",
         "handoff": "artifact-aware",
         "recovery": "hybrid",
-        "state": "file-backed"
+        "state": "controller-home"
       },
       "defaultLsp": "pyright-lsp",
       "defaultTemplateVariables": {
@@ -215,7 +215,7 @@
         "evaluation": "command-qa",
         "handoff": "artifact-aware",
         "recovery": "hybrid",
-        "state": "file-backed"
+        "state": "controller-home"
       },
       "defaultLsp": "gopls-lsp",
       "defaultTemplateVariables": {
@@ -240,7 +240,7 @@
         "evaluation": "browser-qa",
         "handoff": "artifact-aware",
         "recovery": "hybrid",
-        "state": "file-backed"
+        "state": "controller-home"
       },
       "defaultLsp": "typescript-lsp",
       "defaultTemplateVariables": {
@@ -265,7 +265,7 @@
         "evaluation": "command-qa",
         "handoff": "artifact-aware",
         "recovery": "hybrid",
-        "state": "file-backed"
+        "state": "controller-home"
       },
       "defaultLsp": "rust-analyzer-lsp",
       "defaultTemplateVariables": {
@@ -290,7 +290,7 @@
         "evaluation": "command-qa",
         "handoff": "artifact-aware",
         "recovery": "hybrid",
-        "state": "file-backed"
+        "state": "controller-home"
       },
       "defaultLsp": "typescript-lsp",
       "defaultTemplateVariables": {

package/assets/plugin-registry.v1.json

@@ -4,15 +4,21 @@
     {
       "id": "desktop_operator",
       "name": "Forge Desktop Operator",
-      "version": "0.2.3",
+      "version": "0.3.2",
       "description": "Native macOS desktop automation provider for Forge.",
       "repository": "https://github.com/moretea-labs/forge-desktop-operator.git",
-      "ref": "v0.2.3",
+      "ref": "v0.3.2",
       "installer": "forge-plugin-install.mjs",
-      "providerVersion": "0.2.3",
+      "providerVersion": "0.3.2",
       "protocolVersion": "1.0",
       "platforms": [
         "darwin"
+      ],
+      "semanticCapabilities": [
+        "computer.observe.v1",
+        "computer.input.v1",
+        "computer.capture.v1",
+        "computer.browser_automation.v1"
       ]
     },
     {

package/assets/plugin-trust-policy.v1.json

@@ -0,0 +1,6 @@
+{
+  "schemaVersion": 1,
+  "firstPartyRepositoryPrefixes": [
+    "https://github.com/moretea-labs/"
+  ]
+}

package/assets/recovery/ForgeRecovery.ps1

@@ -0,0 +1,100 @@
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory = $true, Position = 0)]
+    [ValidateSet(
+        'host_status', 'task_status', 'task_install', 'task_run',
+        'wsl_status', 'wsl_start',
+        'forge_source_status', 'controller_status',
+        'runtime_status', 'runtime_start', 'runtime_restart',
+        'connector_status', 'connector_start', 'connector_restart',
+        'recovery_status', 'recovery_start', 'recovery_restart',
+        'tunnel_status', 'tunnel_start', 'tunnel_restart',
+        'forge_cloud_verify', 'full_recover'
+    )]
+    [string]$Action
+)
+
+$ErrorActionPreference = 'Stop'
+$Root = Split-Path -Parent $PSCommandPath
+$ConfigPath = Join-Path $Root 'config.json'
+if (-not (Test-Path -LiteralPath $ConfigPath -PathType Leaf)) {
+    throw "FORGE_RESCUE_CONFIG_MISSING: $ConfigPath"
+}
+
+$Config = Get-Content -LiteralPath $ConfigPath -Raw -Encoding UTF8 | ConvertFrom-Json
+if ($Config.schemaVersion -ne 1 -or [string]::IsNullOrWhiteSpace($Config.distro) -or [string]::IsNullOrWhiteSpace($Config.wslRescuePath)) {
+    throw 'FORGE_RESCUE_CONFIG_INVALID'
+}
+$WslRescuePathPattern = '^/' + 'home/[A-Za-z0-9._-]+/\.forge-recovery/bin/forge-wsl-rescue$'
+if ($Config.distro -match "[\r\n'`"`$;&|<>]" -or $Config.wslRescuePath -notmatch $WslRescuePathPattern) {
+    throw 'FORGE_RESCUE_CONFIG_UNSAFE'
+}
+
+$Wsl = Join-Path $env:WINDIR 'System32\wsl.exe'
+$PowerShell = Join-Path $env:WINDIR 'System32\WindowsPowerShell\v1.0\powershell.exe'
+$TaskName = 'Forge Independent Recovery WSL'
+$RunKey = 'HKCU:\Software\Microsoft\Windows\CurrentVersion\Run'
+$RunValueName = 'ForgeIndependentRecoveryWSL'
+$RunCommand = ('"' + $PowerShell + '" -NoProfile -NonInteractive -ExecutionPolicy Bypass -File "' + $PSCommandPath + '" full_recover')
+if (-not (Test-Path -LiteralPath $Wsl -PathType Leaf)) {
+    throw "FORGE_RESCUE_WSL_MISSING: $Wsl"
+}
+
+function Invoke-WslRescue([string]$WslAction) {
+    & $Wsl --distribution $Config.distro --exec $Config.wslRescuePath $WslAction
+    if ($LASTEXITCODE -ne 0) {
+        throw "FORGE_RESCUE_WSL_ACTION_FAILED: action=$WslAction exitCode=$LASTEXITCODE"
+    }
+}
+
+switch ($Action) {
+    'host_status' {
+        [PSCustomObject]@{
+            executionEnvironment = 'WINDOWS_WSL'
+            hostname = $env:COMPUTERNAME
+            user = [Security.Principal.WindowsIdentity]::GetCurrent().Name
+            distro = $Config.distro
+            wslRescuePath = $Config.wslRescuePath
+        } | ConvertTo-Json -Depth 3
+    }
+    'task_status' {
+        $Task = Get-ScheduledTask -TaskName $TaskName -ErrorAction SilentlyContinue
+        if ($null -ne $Task) {
+            [PSCustomObject]@{ installed = $true; method = 'scheduled_task'; taskName = $TaskName; state = [string]$Task.State; execute = $Task.Actions[0].Execute; arguments = $Task.Actions[0].Arguments } | ConvertTo-Json -Depth 4
+        } else {
+            $RunValue = (Get-ItemProperty -LiteralPath $RunKey -Name $RunValueName -ErrorAction SilentlyContinue).$RunValueName
+            [PSCustomObject]@{ installed = ($RunValue -eq $RunCommand); method = $(if ($RunValue) { 'hkcu_run' } else { 'none' }); taskName = $TaskName; runValueName = $RunValueName; identityMatches = ($RunValue -eq $RunCommand) } | ConvertTo-Json -Depth 4
+        }
+    }
+    'task_install' {
+        $ActionObject = New-ScheduledTaskAction -Execute $PowerShell -Argument ('-NoProfile -NonInteractive -ExecutionPolicy Bypass -File "' + $PSCommandPath + '" full_recover')
+        $Trigger = New-ScheduledTaskTrigger -AtLogOn
+        try {
+            $null = Register-ScheduledTask -TaskName $TaskName -Action $ActionObject -Trigger $Trigger -Description 'Forge independent Windows/WSL rescue cold-start trigger.' -Force -ErrorAction Stop
+            [PSCustomObject]@{ installed = $true; method = 'scheduled_task'; taskName = $TaskName } | ConvertTo-Json -Depth 3
+        } catch {
+            if (-not (Test-Path -LiteralPath $RunKey)) { $null = New-Item -Path $RunKey -Force }
+            Set-ItemProperty -LiteralPath $RunKey -Name $RunValueName -Value $RunCommand -Type String -Force
+            $InstalledValue = (Get-ItemProperty -LiteralPath $RunKey -Name $RunValueName -ErrorAction Stop).$RunValueName
+            if ($InstalledValue -ne $RunCommand) { throw 'FORGE_RESCUE_LOGON_TRIGGER_IDENTITY_MISMATCH' }
+            [PSCustomObject]@{ installed = $true; method = 'hkcu_run'; taskName = $TaskName; schedulerError = $_.Exception.HResult } | ConvertTo-Json -Depth 3
+        }
+    }
+    'task_run' {
+        $Task = Get-ScheduledTask -TaskName $TaskName -ErrorAction SilentlyContinue
+        if ($null -ne $Task) {
+            Start-ScheduledTask -InputObject $Task
+            [PSCustomObject]@{ started = $true; method = 'scheduled_task'; taskName = $TaskName } | ConvertTo-Json -Depth 3
+        } else {
+            & $PowerShell -NoProfile -NonInteractive -ExecutionPolicy Bypass -File $PSCommandPath full_recover
+            if ($LASTEXITCODE -ne 0) { throw "FORGE_RESCUE_DIRECT_TRIGGER_FAILED: exitCode=$LASTEXITCODE" }
+            [PSCustomObject]@{ started = $true; method = 'direct_fixed_action'; taskName = $TaskName } | ConvertTo-Json -Depth 3
+        }
+    }
+    'wsl_start' {
+        & $Wsl --distribution $Config.distro --exec /bin/true
+        if ($LASTEXITCODE -ne 0) { throw "FORGE_RESCUE_WSL_START_FAILED: exitCode=$LASTEXITCODE" }
+        Invoke-WslRescue 'wsl_status'
+    }
+    default { Invoke-WslRescue $Action }
+}