planning-with-files 3.18.3 → 3.20.5

package/README.md

@@ -1,25 +1,25 @@
-<div align="center">
-  <img src="https://raw.githubusercontent.com/OthmanAdi/planning-with-files/master/media/v3-banner-1400.jpg" alt="planning-with-files: task_plan.md, findings.md, and progress.md as three stone tablets" width="100%">
-</div>
-
-<h1 align="center">Planning with Files</h1>
-
-<p align="center">
-  <strong>The planning skill your agent cannot ignore.</strong><br>
-  Your agent's context window dies. The plan does not.
-</p>
-
-Persistent file-based planning for AI coding agents. Keep the plan, research and progress in your project so work can continue after context loss, `/clear`, crashes or compaction.
-
-| File | Purpose |
-| --- | --- |
-| `task_plan.md` | Goals, phases and decisions |
-| `findings.md` | Research and discoveries |
-| `progress.md` | Work completed, checks and next steps |
-
-This is the npm distribution of [OthmanAdi/planning-with-files](https://github.com/OthmanAdi/planning-with-files), available across 60+ agents via the Agent Skills standard. It includes the planning skill, scripts and templates. Supported agent integrations add lifecycle hooks that bring selected planning context back into the session.
-
-Automatic recovery reads project files only. Reading same-project local session records for aggregate counts or bounded replay requires an explicit catchup mode.
+<div align="center">
+  <img src="https://raw.githubusercontent.com/OthmanAdi/planning-with-files/master/media/v3-banner-1400.jpg" alt="planning-with-files: task_plan.md, findings.md, and progress.md as three stone tablets" width="100%">
+</div>
+
+<h1 align="center">Planning with Files</h1>
+
+<p align="center">
+  <strong>The planning skill your agent cannot ignore.</strong><br>
+  Your agent's context window dies. The plan does not.
+</p>
+
+Persistent file-based planning for AI coding agents. Keep the plan, research and progress in your project so work can continue after context loss, `/clear`, crashes or compaction.
+
+| File | Purpose |
+| --- | --- |
+| `task_plan.md` | Goals, phases and decisions |
+| `findings.md` | Research and discoveries |
+| `progress.md` | Work completed, checks and next steps |
+
+This is the npm distribution of [OthmanAdi/planning-with-files](https://github.com/OthmanAdi/planning-with-files), available across 60+ agents via the Agent Skills standard. It includes the planning skill, scripts and templates. Supported agent integrations add lifecycle hooks that bring selected planning context back into the session.
+
+Automatic recovery reads project files only. Reading same-project local session records for aggregate counts or bounded replay requires an explicit catchup mode.
 
 ## Installation
 
@@ -31,40 +31,40 @@ npm install planning-with-files
 
 Places the skill, scripts and templates under `node_modules/planning-with-files/`. Use this to pin an exact version into a project, or to copy `SKILL.md` and `scripts/` into your agent's skills directory yourself. It does not register hooks on its own.
 
-### Agent integrations
-
-Claude Code gets the full surface (skill, hooks, slash commands) through the plugin route, and 60+ other agents install in one line. See the [main README](https://github.com/OthmanAdi/planning-with-files#quick-install).
-
-## Usage
-
-Once the skill is installed for your agent, start with:
-
-```text
-Use the planning-with-files skill to help me with this task.
-```
-
-The workflow centers on three files in your project:
-
-```text
-your-project/
-├── task_plan.md
-├── findings.md
-└── progress.md
-```
-
-## Pi Coding Agent integration
-
-The package also bundles a [Pi Coding Agent](https://pi.dev) extension for lifecycle automation and a planning status bar.
-
-### Install in Pi
-
-```bash
-pi install npm:planning-with-files
-```
-
-Pi discovers the skill and extension from the installed package.
-
-For a local repository checkout:
+### Agent integrations
+
+Claude Code gets the full surface (skill, hooks, slash commands) through the plugin route, and 60+ other agents install in one line. See the [main README](https://github.com/OthmanAdi/planning-with-files#quick-install).
+
+## Usage
+
+Once the skill is installed for your agent, start with:
+
+```text
+Use the planning-with-files skill to help me with this task.
+```
+
+The workflow centers on three files in your project:
+
+```text
+your-project/
+├── task_plan.md
+├── findings.md
+└── progress.md
+```
+
+## Pi Coding Agent integration
+
+The package also bundles a [Pi Coding Agent](https://pi.dev) extension for lifecycle automation and a planning status bar.
+
+### Install in Pi
+
+```bash
+pi install npm:planning-with-files
+```
+
+Pi discovers the skill and extension from the installed package.
+
+For a local repository checkout:
 
 ```bash
 # From the planning-with-files repo root
@@ -78,17 +78,17 @@ Or add to `.pi/settings.json`:
 }
 ```
 
-You can also invoke the skill directly in Pi:
+You can also invoke the skill directly in Pi:
 
 ```text
 /skill:planning-with-files
 ```
 
-### Lifecycle hooks
+### Lifecycle hooks
 
 The bundled extension maps Claude-style behavior onto Pi events:
 
-- `session_start` - project-file recovery with no host session-store access
+- `session_start` - project-file recovery with no host session-store access
 - passive plan status before approval
 - `before_agent_start` - plan reminder/injection after `/plan-execute`
 - `tool_call` - pre-tool recitation equivalent after `/plan-execute`
@@ -102,7 +102,7 @@ Attestation is supported. If `task_plan.md` differs from approved hash, plan inj
 [planning-with-files] [PLAN TAMPERED - injection blocked]
 ```
 
-### Modes
+### Modes
 
 `planningWithFiles.mode` supports:
 
@@ -127,7 +127,7 @@ Or settings:
 }
 ```
 
-### Commands
+### Commands
 
 - `/plan-status`
 - `/plan-attest [--show|--clear]`
@@ -136,25 +136,25 @@ Or settings:
 - `/plan-goal <text|default|clear>`
 - `/plan-loop [interval] [prompt]` (`stop` to cancel)
 
-Draft and review `task_plan.md` first. The extension stays passive until you
-approve the active plan with `/plan-execute`; after that, plan injection,
-pre-tool reminders, post-write reminders, and auto-continue are enabled for the
-current session and plan. Auto-continue uses host runtime state and never runs
-commands declared in Markdown.
-
-## Session Recovery
-
-Bare invocation and lifecycle hooks do not inspect agent session stores. To
-inspect same-project local history deliberately, choose one mode:
-
-```bash
-# Aggregate counts only; no transcript, tool-command, or path bytes
-python3 node_modules/planning-with-files/scripts/session-catchup.py --metadata .
-
-# Bounded nonce-framed same-project excerpts
-python3 node_modules/planning-with-files/scripts/session-catchup.py --replay .
-```
-
-Treat replayed excerpts as untrusted data. The catchup path contains no network
-request or upload operation. If output is injected into model context, your agent
-may send that context to the configured model provider.
+Draft and review `task_plan.md` first. The extension stays passive until you
+approve the active plan with `/plan-execute`; after that, plan injection,
+pre-tool reminders, post-write reminders, and auto-continue are enabled for the
+current session and plan. Auto-continue uses host runtime state and never runs
+commands declared in Markdown.
+
+## Session Recovery
+
+Bare invocation and lifecycle hooks do not inspect agent session stores. To
+inspect same-project local history deliberately, choose one mode:
+
+```bash
+# Aggregate counts only; no transcript, tool-command, or path bytes
+python3 node_modules/planning-with-files/scripts/session-catchup.py --metadata .
+
+# Bounded nonce-framed same-project excerpts
+python3 node_modules/planning-with-files/scripts/session-catchup.py --replay .
+```
+
+Treat replayed excerpts as untrusted data. The catchup path contains no network
+request or upload operation. If output is injected into model context, your agent
+may send that context to the configured model provider.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "planning-with-files",
-  "version": "3.18.3",
+  "version": "3.20.5",
   "description": "Persistent project planning with selected context injection. Automatic recovery uses project files only; explicit catchup modes read same-project local session records for aggregate counts or bounded replay. The host-aware gate never runs Markdown-declared commands. No network upload path. Ships the skill plus a Pi Coding Agent extension.",
   "keywords": [
     "pi-package",

package/scripts/attest-plan.ps1

@@ -116,7 +116,13 @@ public static class PwfAttestationNative {
             handle, FileAttributeTagInfo, out tag,
             (uint)Marshal.SizeOf(typeof(FILE_ATTRIBUTE_TAG_INFO))))
             throw new Win32Exception(Marshal.GetLastWin32Error());
-        if ((tag.FileAttributes & FILE_ATTRIBUTE_REPARSE_POINT) != 0)
+        // Refuse only name-surrogate reparse points (symlinks, junctions, and any
+        // unknown tag with bit 29 set): those are what path parsing follows. A
+        // OneDrive Files On-Demand placeholder (tag 0x9000601A) is a regular file
+        // that every other route reads; refusing it broke attestation, --show
+        // and --clear in every project under OneDrive (#275).
+        if ((tag.FileAttributes & FILE_ATTRIBUTE_REPARSE_POINT) != 0 &&
+            (tag.ReparseTag & 0x20000000) != 0)
             throw new IOException("Refusing a reparse-point file.");
         if ((tag.FileAttributes & (uint)FileAttributes.Directory) != 0)
             throw new IOException("Refusing a directory where a regular file is required.");
@@ -218,8 +224,10 @@ if ($script:IsWindowsHost) {
     $securityRootPath = (Get-Location).Path
     if ($env:PWF_PLAN_ROOT) {
         $pin = $env:PWF_PLAN_ROOT
+        # Windows PowerShell 5.1 has no IsPathFullyQualified; a drive-qualified
+        # local path is the only accepted shape, as in resolve-plan-dir.ps1.
         $isUnc = $pin.StartsWith('\\') -or $pin.StartsWith('//')
-        if (-not [IO.Path]::IsPathFullyQualified($pin) -or $isUnc) {
+        if ($isUnc -or ($pin -notmatch '^[A-Za-z]:[\\/]')) {
             throw "[plan-attest] PWF_PLAN_ROOT must be an absolute local path."
         }
         $securityRootPath = $pin

package/scripts/init-session.ps1

@@ -1,5 +1,6 @@
 # Initialize planning files for a new session
 # Usage: .\init-session.ps1 [-Template TYPE] [project-name]
+#        .\init-session.ps1 -PlanDir             # isolated plan with generated slug
 #        .\init-session.ps1 -Autonomous        # v3 autonomous mode (opt-in)
 #        .\init-session.ps1 -Gated             # v3 gated mode (opt-in, implies autonomous)
 # Templates: default, analytics
@@ -12,6 +13,7 @@
 param(
     [string]$ProjectName = "project",
     [string]$Template = "default",
+    [switch]$PlanDir,
     [switch]$Autonomous,
     [switch]$Gated
 )
@@ -38,7 +40,65 @@ function Get-Nonce {
     ($bytes | ForEach-Object { $_.ToString("x2") }) -join ""
 }
 
-Write-Host "Initializing planning files for: $ProjectName (template: $Template)"
+function Get-PlanSlug([string]$Name) {
+    # -creplace: the case-insensitive -replace lets letters that .NET folds to
+    # ASCII (a dotted capital I, the Kelvin sign) survive into the plan id.
+    $slug = $Name.ToLowerInvariant() -creplace '[^a-z0-9]', '-'
+    $slug = $slug -creplace '-{2,}', '-'
+    $slug = $slug.Trim('-')
+    if ($slug.Length -gt 40) {
+        $slug = $slug.Substring(0, 40).TrimEnd('-')
+    }
+    # The resolvers and the selector only accept ASCII plan ids.
+    if ($slug -cnotmatch '^[a-z0-9-]*$') {
+        return ""
+    }
+    return $slug
+}
+
+function Get-ShortId {
+    return ([Guid]::NewGuid().ToString('N')).Substring(0, 8)
+}
+
+function Get-InheritedMode([string]$CurrentMode) {
+    $RootModePath = Join-Path (Get-Location).Path ".mode"
+    if (-not (Test-Path -LiteralPath $RootModePath)) {
+        return $CurrentMode
+    }
+    if ($CurrentMode -eq "gated") {
+        return $CurrentMode
+    }
+
+    $RootMode = Get-Content -LiteralPath $RootModePath -Raw -ErrorAction SilentlyContinue
+    # Case-sensitive like inherit_root_mode in init-session.sh and the injector.
+    if ($RootMode -cmatch 'gate') {
+        return "gated"
+    }
+    if ($RootMode -cmatch 'autonomous') {
+        return "autonomous"
+    }
+    return $CurrentMode
+}
+
+function Format-AttestationFailureReason {
+    param([object[]]$Output, [string]$Fallback)
+
+    $Reason = @(
+        $Output |
+            ForEach-Object {
+                if ($null -ne $_) { ($_.ToString()).Trim() }
+            } |
+            Where-Object { $_ }
+    ) -join " "
+    $Reason = ($Reason -replace '\s+', ' ').Trim()
+    if ([string]::IsNullOrWhiteSpace($Reason)) {
+        return $Fallback
+    }
+    if ($Reason.Length -gt 300) {
+        return ($Reason.Substring(0, 297) + "...")
+    }
+    return $Reason
+}
 
 # Validate template
 if ($Template -ne "default" -and $Template -ne "analytics") {
@@ -46,11 +106,86 @@ if ($Template -ne "default" -and $Template -ne "analytics") {
     $Template = "default"
 }
 
+# Match init-session.sh: zero args (or an empty name) preserve legacy root
+# mode. A positional project name or -PlanDir creates an isolated
+# .planning/<date>-<slug>/ plan.
+$NamedPlan = $PSBoundParameters.ContainsKey("ProjectName") -and -not [string]::IsNullOrEmpty($ProjectName)
+$UsePlanDir = $PlanDir -or $NamedPlan
+if ($UsePlanDir) {
+    $PlanningRoot = Join-Path (Get-Location).Path ".planning"
+    # Match init-session.sh: set-active-plan.ps1 owns every write to the
+    # shared pointer, so a named plan cannot be created without it.
+    $PlanSelector = Join-Path $ScriptDir "set-active-plan.ps1"
+    if (-not (Test-Path -LiteralPath $PlanSelector -PathType Leaf)) {
+        Write-Error "Error: set-active-plan.ps1 is required to create a named plan safely."
+        exit 1
+    }
+    New-Item -ItemType Directory -Path $PlanningRoot -Force | Out-Null
+    # Verify the physical planning root and the existing pointer before
+    # creating anything below it. A symlink or junction that escapes the
+    # project must not redirect init writes, and a linked or non-regular
+    # pointer must be refused before a plan directory exists on disk. A
+    # script that returns without exit leaves $LASTEXITCODE alone, so reset
+    # it first and treat a thrown error as a failure too.
+    $global:LASTEXITCODE = 0
+    try {
+        & $PlanSelector -VerifyRoot *> $null
+    } catch {
+        $global:LASTEXITCODE = 1
+    }
+    if ($LASTEXITCODE -ne 0) {
+        Write-Error "Error: the planning directory or the active plan pointer is outside the project or cannot be verified."
+        exit 1
+    }
+
+    if ($NamedPlan) {
+        $Slug = Get-PlanSlug $ProjectName
+    } else {
+        $Slug = ""
+        $ProjectName = "untitled"
+    }
+    if ([string]::IsNullOrEmpty($Slug)) {
+        $Slug = "untitled-$(Get-ShortId)"
+    }
+
+    $BaseId = "$DATE-$Slug"
+    $PlanId = $BaseId
+    $Counter = 2
+    while (Test-Path -LiteralPath (Join-Path $PlanningRoot $PlanId)) {
+        $PlanId = "$BaseId-$Counter"
+        $Counter++
+    }
+    $TargetDir = Join-Path $PlanningRoot $PlanId
+    New-Item -ItemType Directory -Path $TargetDir -Force -ErrorAction Stop | Out-Null
+    $Mode = Get-InheritedMode $Mode
+} else {
+    $TargetDir = (Get-Location).Path
+}
+
+$TaskPlanPath = Join-Path $TargetDir "task_plan.md"
+$FindingsPath = Join-Path $TargetDir "findings.md"
+$ProgressPath = Join-Path $TargetDir "progress.md"
+if ($UsePlanDir) {
+    $TaskPlanDisplay = $TaskPlanPath
+    $FindingsDisplay = $FindingsPath
+    $ProgressDisplay = $ProgressPath
+} else {
+    $TaskPlanDisplay = "task_plan.md"
+    $FindingsDisplay = "findings.md"
+    $ProgressDisplay = "progress.md"
+}
+
+Write-Host "Initializing planning files for: $ProjectName (template: $Template)"
+if ($UsePlanDir) {
+    Write-Host "PLAN_ID=$PlanId"
+}
+
+try {
 # Create task_plan.md if it doesn't exist
-if (-not (Test-Path "task_plan.md")) {
+if (-not (Test-Path -LiteralPath $TaskPlanPath)) {
     $AnalyticsPlan = Join-Path $TemplateDir "analytics_task_plan.md"
     if ($Template -eq "analytics" -and (Test-Path $AnalyticsPlan)) {
-        Copy-Item $AnalyticsPlan "task_plan.md"
+        Copy-Item -LiteralPath $AnalyticsPlan -Destination $TaskPlanPath -ErrorAction Stop
     } else {
         @"
 # Task Plan: [Brief Description]
@@ -99,18 +234,18 @@ Phase 1
 ## Errors Encountered
 | Error | Resolution |
 |-------|------------|
-"@ | Out-File -FilePath "task_plan.md" -Encoding UTF8
+"@ | Out-File -LiteralPath $TaskPlanPath -Encoding UTF8 -ErrorAction Stop
     }
-    Write-Host "Created task_plan.md"
+    Write-Host "Created $TaskPlanDisplay"
 } else {
-    Write-Host "task_plan.md already exists, skipping"
+    Write-Host "$TaskPlanDisplay already exists, skipping"
 }
 
 # Create findings.md if it doesn't exist
-if (-not (Test-Path "findings.md")) {
+if (-not (Test-Path -LiteralPath $FindingsPath)) {
     $AnalyticsFindings = Join-Path $TemplateDir "analytics_findings.md"
     if ($Template -eq "analytics" -and (Test-Path $AnalyticsFindings)) {
-        Copy-Item $AnalyticsFindings "findings.md"
+        Copy-Item -LiteralPath $AnalyticsFindings -Destination $FindingsPath -ErrorAction Stop
     } else {
         @"
 # Findings & Decisions
@@ -131,15 +266,15 @@ if (-not (Test-Path "findings.md")) {
 
 ## Resources
 -
-"@ | Out-File -FilePath "findings.md" -Encoding UTF8
+"@ | Out-File -LiteralPath $FindingsPath -Encoding UTF8 -ErrorAction Stop
     }
-    Write-Host "Created findings.md"
+    Write-Host "Created $FindingsDisplay"
 } else {
-    Write-Host "findings.md already exists, skipping"
+    Write-Host "$FindingsDisplay already exists, skipping"
 }
 
 # Create progress.md if it doesn't exist
-if (-not (Test-Path "progress.md")) {
+if (-not (Test-Path -LiteralPath $ProgressPath)) {
     if ($Template -eq "analytics") {
         @"
 # Progress Log
@@ -160,7 +295,7 @@ if (-not (Test-Path "progress.md")) {
 ### Errors
 | Error | Resolution |
 |-------|------------|
-"@ | Out-File -FilePath "progress.md" -Encoding UTF8
+"@ | Out-File -LiteralPath $ProgressPath -Encoding UTF8 -ErrorAction Stop
     } else {
         @"
 # Progress Log
@@ -181,23 +316,48 @@ if (-not (Test-Path "progress.md")) {
 ### Errors
 | Error | Resolution |
 |-------|------------|
-"@ | Out-File -FilePath "progress.md" -Encoding UTF8
+"@ | Out-File -LiteralPath $ProgressPath -Encoding UTF8 -ErrorAction Stop
     }
-    Write-Host "Created progress.md"
+    Write-Host "Created $ProgressDisplay"
 } else {
-    Write-Host "progress.md already exists, skipping"
+    Write-Host "$ProgressDisplay already exists, skipping"
+}
+} catch {
+    Write-Error "Error: could not initialize planning files in '$TargetDir': $($_.Exception.Message)"
+    exit 1
+}
+
+if ($UsePlanDir) {
+    # Activate the named plan only after all three planning files are ready.
+    # This matches init-session.sh and prevents a failed initialization from
+    # leaving .active_plan pointed at a partial plan directory.
+    $global:LASTEXITCODE = 0
+    try {
+        & $PlanSelector $PlanId *> $null
+    } catch {
+        $global:LASTEXITCODE = 1
+    }
+    if ($LASTEXITCODE -ne 0) {
+        Write-Error "Error: could not safely update the active plan pointer at $(Join-Path $PlanningRoot '.active_plan')."
+        exit 1
+    }
 }
 
 Write-Host ""
 Write-Host "Planning files initialized!"
-Write-Host "Files: task_plan.md, findings.md, progress.md"
+if ($UsePlanDir) {
+    Write-Host "Active plan recorded: $(Join-Path $PlanningRoot '.active_plan')"
+    Write-Host "Pin this terminal to the plan for parallel sessions:"
+    Write-Host "  `$env:PLAN_ID='$PlanId'"
+} else {
+    Write-Host "Files: task_plan.md, findings.md, progress.md"
+}
 
 # v3 opt-in mode side effects. No-op when -Autonomous/-Gated were not passed, so
-# the default path stays byte-equivalent to v2.43.0. PS1 init writes in CWD, so
-# dotfiles live in CWD and attest-plan.ps1 falls back to the legacy
-# .plan-attestation at the project root.
+# the default path stays byte-equivalent to v2.43.0. Dotfiles live beside the
+# selected plan; root mode therefore retains the legacy project-root behavior.
 if ($Mode -ne "") {
-    $PlanDirPwf = (Get-Location).Path
+    $PlanDirPwf = $TargetDir
 
     # (a) reset gate block counter, drop stale gate ledger.
     Set-Content -LiteralPath (Join-Path $PlanDirPwf ".stop_blocks") -Value "0" -Encoding ascii
@@ -216,15 +376,96 @@ if ($Mode -ne "") {
     Set-Content -LiteralPath (Join-Path $PlanDirPwf ".mode") -Value $MarkerText -Encoding ascii
 
     # (c) auto-attest (attestation default-on in v3 modes, security strand rec 1).
-    $AttestPs1 = Join-Path $ScriptDir "attest-plan.ps1"
+    # attest-plan.ps1 intentionally refuses non-Windows hosts because its secure
+    # no-follow implementation uses Win32 handles. On Unix, use the POSIX
+    # attester instead. Slug mode binds PWF_PLAN_ROOT and PLAN_ID to the plan
+    # we just created so an inherited pin or slug cannot redirect attestation
+    # to another project or plan (#261, #237). Root mode clears both instead:
+    # the attester only falls back to the legacy ./task_plan.md when no
+    # selector is set, and a bound pin would make it refuse the root plan.
+    $AttestationSucceeded = $false
+    $AttestationCommand = "attest-plan"
+    $AttestationReason = "task_plan.md was not available for attestation"
     $PlanFilePwf = Join-Path $PlanDirPwf "task_plan.md"
-    if ((Test-Path -LiteralPath $AttestPs1) -and (Test-Path -LiteralPath $PlanFilePwf)) {
+    if (Test-Path -LiteralPath $PlanFilePwf -PathType Leaf) {
+        $HadPlanId = Test-Path Env:PLAN_ID
+        $PreviousPlanId = $env:PLAN_ID
+        $HadPlanRoot = Test-Path Env:PWF_PLAN_ROOT
+        $PreviousPlanRoot = $env:PWF_PLAN_ROOT
         try {
-            & $AttestPs1 *> $null
+            if ($UsePlanDir) {
+                $env:PWF_PLAN_ROOT = (Get-Location).Path
+                $env:PLAN_ID = $PlanId
+            } else {
+                Remove-Item Env:PWF_PLAN_ROOT -ErrorAction SilentlyContinue
+                Remove-Item Env:PLAN_ID -ErrorAction SilentlyContinue
+            }
+
+            # A called script can return without changing $LASTEXITCODE, so
+            # clear the inherited value before every attempt. Both a non-zero
+            # status and a terminating exception mean the plan is not attested.
+            $global:LASTEXITCODE = 0
+            $AttestOutput = @()
+            $IsWindowsHost = [Environment]::OSVersion.Platform -eq [PlatformID]::Win32NT
+            if ($IsWindowsHost) {
+                $AttestationCommand = "attest-plan.ps1"
+                $AttestPs1 = Join-Path $ScriptDir $AttestationCommand
+                if (Test-Path -LiteralPath $AttestPs1 -PathType Leaf) {
+                    $AttestOutput = @(& $AttestPs1 2>&1)
+                    $AttestExitCode = $LASTEXITCODE
+                    if ($AttestExitCode -eq 0) {
+                        $AttestationSucceeded = $true
+                        $AttestationReason = ""
+                    } else {
+                        $AttestationReason = Format-AttestationFailureReason `
+                            -Output $AttestOutput `
+                            -Fallback "$AttestationCommand exited with code $AttestExitCode"
+                    }
+                } else {
+                    $AttestationReason = "$AttestationCommand was not found beside init-session.ps1"
+                }
+            } else {
+                $AttestationCommand = "attest-plan.sh"
+                $AttestSh = Join-Path $ScriptDir $AttestationCommand
+                $Sh = Get-Command sh -ErrorAction SilentlyContinue
+                if ($Sh -and (Test-Path -LiteralPath $AttestSh -PathType Leaf)) {
+                    $AttestOutput = @(& $Sh.Path $AttestSh 2>&1)
+                    $AttestExitCode = $LASTEXITCODE
+                    if ($AttestExitCode -eq 0) {
+                        $AttestationSucceeded = $true
+                        $AttestationReason = ""
+                    } else {
+                        $AttestationReason = Format-AttestationFailureReason `
+                            -Output $AttestOutput `
+                            -Fallback "$AttestationCommand exited with code $AttestExitCode"
+                    }
+                } elseif (-not $Sh) {
+                    $AttestationReason = "sh was not found; $AttestationCommand could not run"
+                } else {
+                    $AttestationReason = "$AttestationCommand was not found beside init-session.ps1"
+                }
+            }
         } catch {
-            # attestation failure must not abort init; the mode marker still stands.
+            $AttestationReason = Format-AttestationFailureReason `
+                -Output @($_) `
+                -Fallback "$AttestationCommand failed"
+        } finally {
+            if ($HadPlanId) {
+                $env:PLAN_ID = $PreviousPlanId
+            } else {
+                Remove-Item Env:PLAN_ID -ErrorAction SilentlyContinue
+            }
+            if ($HadPlanRoot) {
+                $env:PWF_PLAN_ROOT = $PreviousPlanRoot
+            } else {
+                Remove-Item Env:PWF_PLAN_ROOT -ErrorAction SilentlyContinue
+            }
         }
     }
 
-    Write-Host "Mode: $MarkerText (attested, gate counter reset)"
+    if ($AttestationSucceeded) {
+        Write-Host "Mode: $MarkerText (attested, gate counter reset)"
+    } else {
+        Write-Host "Mode: $MarkerText (NOT attested: $AttestationReason; run $AttestationCommand before the first hook fire)"
+    }
 }