Compare commits

..
46 Commits
Author SHA1 Message Date
OthmanAdi 3b7690eafd release: v3.20.7 2026-09-23 22:13:44 +02:00
OthmanAdi f473fa8930 fix: disclose Pi package planning capabilities 2026-09-23 22:09:00 +02:00
OthmanAdi 3827d3c018 release: v3.20.6 2026-09-23 21:58:59 +02:00
OthmanAdi b7edae42dc fix: retry transient PowerShell pointer inspection 2026-09-23 21:51:09 +02:00
OthmanAdi 10c64d464e fix: compare canonical active plan pointer roots 2026-09-23 21:16:28 +02:00
TayfurYldz a82c5a4588 fix: keep DSH core in sync 2026-09-23 21:16:28 +02:00
TayfurYldz 16b6a452bc fix: replace OpenCode active pointer safely 2026-09-23 21:16:28 +02:00
TayfurYldz abd39f7e9b fix: retry concurrent PowerShell pointer replacement 2026-09-23 20:55:49 +02:00
TayfurYldz 388b591f77 fix: recover PowerShell bracketed project cwd 2026-09-23 20:55:43 +02:00
TayfurYldz 87b2553fa1 test: scope read-only pointer case to Windows 2026-09-23 20:55:38 +02:00
TayfurYldz a3bd42954b fix: reject read-only active plan pointers 2026-09-23 20:55:38 +02:00
TayfurYldz 5165ffe847 fix: replace Hermes active pointer safely 2026-09-23 20:55:22 +02:00
kuei51307-hub f7b9be9d58 fix(locking): claim phase status lock atomically 2026-09-23 20:54:59 +02:00
OthmanAdi 0827eeaecf docs: add official skills.sh install badge 2026-09-22 22:07:58 +02:00
OthmanAdi 09d2254d76 docs: restore ClawHub chart below star history 2026-09-22 21:58:33 +02:00
OthmanAdi 78e5bf7b5b docs: simplify star history to the graph 2026-09-22 21:57:34 +02:00
OthmanAdi 27ab93c15d docs: show full star history below reference dropdown 2026-09-22 21:49:40 +02:00
OthmanAdi 4a40450390 docs: remove workflow caption 2026-09-22 19:51:19 +02:00
OthmanAdi 0bd06d344b docs: refresh README layout and visual story 2026-09-22 17:38:29 +02:00
OthmanAdi 5ac39bcb41 docs: align v3.20.5 citation date and replay description 2026-09-21 21:00:22 +02:00
OthmanAdi b81c488d46 release: v3.20.5 2026-09-21 20:59:55 +02:00
Shaun Lin f869dfb4d0 fix: fail PowerShell init on denied writes 2026-09-21 20:57:40 +02:00
kuei51307-hub 428b96c982 fix(init): report attestation failures 2026-09-21 20:57:36 +02:00
kuei51307-hub cd0bc3d202 fix(templates): add analytics next step 2026-09-21 20:56:57 +02:00
TayfurYldz 5ad5452276 fix: tolerate malformed OpenCode replay parts 2026-09-21 20:56:53 +02:00
OthmanAdi 726da18dc7 release: v3.20.4
PowerShell route on OneDrive (#275: pointer checks and the attester refuse only symlinks, junctions and name-surrogate reparse points) and the session-catchup copy guard checks tracked copies only (#274). Parity set bumped with scripts/bump-version.py; CHANGELOG, README releases row.
2026-09-19 20:39:00 +02:00
OthmanAdi 3a4f2077be fix(powershell): attest-plan.ps1 refuses only name-surrogate reparse points
ValidateRegular in the attester's native helper threw "Refusing a
reparse-point file" for any file with the ReparsePoint attribute, so in a
project under OneDrive (Files On-Demand marks every synced file, tag
0x9000601A) attestation, --show and --clear all failed, and init-session.ps1
still printed "attested" because it swallows the attester's failure. The
check now refuses only name-surrogate tags (bit 29 set: symlinks, junctions
and any unknown surrogate), which is exactly the set Windows path parsing
follows, so the security property is unchanged and placeholder files read
as the regular files they are. Every mirror synced (#275).
2026-09-19 20:35:25 +02:00
OthmanAdi 864577857d test: keep the exact session-catchup.py basename on the git pathspec 2026-09-19 20:35:25 +02:00
OthmanAdi a33fc3eb1a fix(powershell): the .active_plan pointer check is LinkType, not the ReparsePoint attribute
resolve-plan-dir.ps1, the Cursor hook resolve-plan-context.ps1 and the
set-active-plan.ps1 writer refused an .active_plan pointer that carried the
ReparsePoint attribute. OneDrive Files On-Demand marks every synced file as
a reparse point, so in a project under OneDrive the Cursor hooks stopped
with the unsafe-pointer notice, the resolver printed nothing for
attest-plan.ps1 and check-complete.ps1, and set-active-plan.ps1 refused to
write, while every other route read the pointer normally. The three checks
now refuse a container or a LinkType of SymbolicLink or Junction, the same
predicate v3.20.3 gave the directory checks and the `[ -L ]` of the shell
scripts. Every mirror synced. Tests cover the plain pointer and the
symlinked pointer (skipped where file symlinks need a privilege). Fixes #275.
2026-09-19 20:18:27 +02:00
OthmanAdi 85dfd5dcdd test: check only tracked session-catchup.py copies
The exact-basename guard walked the whole checkout, so any untracked copy
of session-catchup.py, such as a stale clone kept under the gitignored
.planning/ directory on a maintainer machine, was loaded as a shipped copy
and failed the two tests with 120 subtests while CI stayed green. Shipped
means tracked: the copies now come from git ls-files, with the filtered
walk kept only for a checkout without git, where .planning and .git are
excluded as well. Fixes #274.
2026-09-19 20:18:27 +02:00
OthmanAdi 57fe376da9 release: v3.20.3
A symlinked or junctioned directory under .planning/ is never a plan on
any route (#270, PR #271 by @ShaunLinTW plus three maintainer commits).

Parity set bumped to 3.20.3 with scripts/bump-version.py. CHANGELOG,
CONTRIBUTORS.md (PR #271 for Shaun Lin), README releases row.
2026-09-19 11:24:08 +02:00
OthmanAdi 663908180e docs(hermes): name the routes that share the linked-directory rule 2026-09-19 11:23:53 +02:00
OthmanAdi f54f8144c2 fix(scripts): match symlinks and junctions only, and keep linked directories out of set-active-plan
Review of the previous two commits found the PowerShell resolver testing the
ReparsePoint attribute, which every OneDrive Files On-Demand directory
carries: a project under OneDrive would have lost every plan on the Cursor
route. The resolver now tests LinkType for SymbolicLink or Junction, the
exact `[ -L ]` of the shell scripts and is_link of the Python twin, and the
Codex counter uses the same symlink-or-junction tag rule instead of the
adapter's any-reparse helper.

set-active-plan.sh and set-active-plan.ps1 refuse to point the shared
default at a linked directory and leave it out of --list, since no route
selects it; the sh/py/ps1 suites cover PLAN_ID naming a link (refused with
the existing notice) and the pointer naming one (falls through to the real
plan like a stale pointer). Hermes docstring names the routes precisely (#270).
2026-09-19 11:13:08 +02:00
OthmanAdi 95cf6f499b fix(adapters): skip linked plan directories in the Codex, OpenCode and DSH plan counters
The Codex adapter's session_plan_requires_binding and the shared
countSelectablePlans of the OpenCode and DeepSeek Harness plugins counted a
symlinked or junctioned plan directory although their selection paths (and
the shell family since the previous commit) refuse it. A linked directory
never counts now, so the several-plans notice fires on the same trees on
every route. The two TypeScript cores stay byte-identical (#270).
2026-09-19 10:44:07 +02:00
OthmanAdi 0308a2f819 fix(scripts): a linked plan directory is never selectable, on every shell-family route
PR #271 made the several-plans counters in inject-plan.sh and
resolve-plan-dir.sh skip symlinked and junctioned plan directories, matching
the Hermes plugin. Skipping the link in the counter alone left the selection
paths following it through containment: one real plan plus a newer linked
one counted as one plan and the newest-mtime scan then selected the linked
directory, the mtime guess the #240 rule exists to prevent. The PowerShell
twin reproduced that after the counter port.

The rule now holds end to end in the shell family: resolve-plan-dir.sh,
inject-plan.sh, resolve-plan-dir.ps1 and the Python twin inject-plan.py
refuse a linked plan directory in the PLAN_ID, .active_plan and
newest-mtime branches and never count it. Every shipped copy is synced.

Tests: the sh/py parity suite gains the linked-directory fixture (the twin
contract), and test_unarmed_plan_ambiguity drives both resolvers and both
injectors over a real plan plus a junction or symlink (#270).
2026-09-19 10:43:59 +02:00
Shaun Lin 0bbc43cff3 fix: skip linked plan dirs in ambiguity counts 2026-09-19 10:36:51 +02:00
OthmanAdi f01a88a12b release: v3.20.2
Hermes plugin 0.2.2: the launch-directory notice for the Hermes 0.21.3
first-turn TERMINAL_CWD rewrite, the /pwf-status and /pwf diagnostics,
and PWF_PLAN_ROOT honored by the slash commands (#272).

Parity set bumped to 3.20.2 with scripts/bump-version.py. CHANGELOG,
CONTRIBUTORS.md (@ericshunhinglee-cloud), README releases row,
CITATION.cff date.
2026-09-19 09:59:30 +02:00
OthmanAdi 9a3843b31d docs(hermes): describe the Hermes 0.21.3 working-directory rewrite and the pin
Adds the section on the first-turn TERMINAL_CWD rewrite: the mechanism,
what was reproduced with the 0.21.0 source, what the plugin says since
v3.20.2, the PWF_PLAN_ROOT pin for project-scoped CLI sessions, the
shell-hook route as the unaffected alternative, and the home-directory
inverse risk (#272).
2026-09-19 09:57:44 +02:00
OthmanAdi 1528b31d7f fix(hermes): name the launch directory plan when the host re-homes the working directory
On Hermes 0.21.3 the first turn of a CLI session rewrites the
process-global TERMINAL_CWD to the home directory (agent/relay_runtime.py
imports gateway/run.py lazily, whose import-time bridge applies the
Path.home() fallback), so resolve_agent_cwd() names HOME, the hooks find
no plan there and inject nothing. The rewrite runs before the first
plugin hook, so the plugin cannot recover the root and does not guess.

pre_llm_call now injects one line naming the resolved directory, the
launch directory that holds a plan, and the PWF_PLAN_ROOT pin instead of
returning nothing. CLI only; silent for hermes -w worktree sessions
(TERMINAL_CWD at <repo>/.worktrees/<name> without a chdir is intended),
for a launch directory without planning state, and for a launch
directory whose session isolation refuses the session.

/pwf and /pwf-status honor PWF_PLAN_ROOT like the hooks and report a pin
that does not resolve instead of acting in the directory Hermes named.
/pwf-status prints the same line under "No planning files found", and
/pwf appends it when the plan it created went somewhere other than a
launch directory that already holds one.

Fixes #272. Upstream: NousResearch/hermes-agent#86411, #95577.
2026-09-19 09:57:38 +02:00
OthmanAdi faf1a15a7d release: v3.20.1 2026-09-18 17:32:57 +02:00
OthmanAdi c05821a1cf fix(init): bind the attest selectors in slug mode only, clear them in root mode
Binding PWF_PLAN_ROOT for the attestation call in both modes (#265) made
root-mode --autonomous and --gated plans unattested on the shell and the
PowerShell route: the attester only falls back to the legacy ./task_plan.md
when no selector is set and refuses the root plan under an explicit pin,
while init still reported the plan as attested and every hook then refused
to inject it. Slug mode keeps the binding from #265 (PWF_PLAN_ROOT and
PLAN_ID name the plan just created); root mode now clears both selectors,
which also stops an inherited PLAN_ID from redirecting the shell attester
to a sibling slug plan, as the PowerShell twin already did (#261).

Regression tests cover root-mode attestation for --autonomous and --gated
with and without an inherited PWF_PLAN_ROOT and PLAN_ID, on both routes.
2026-09-18 17:32:57 +02:00
kuei51307-hub 52572e3301 docs(hermes): clarify multiple-plan selection 2026-09-18 17:32:09 +02:00
kuei51307-hub 1df6f5808b fix(hermes): require selector for multiple plans 2026-09-18 17:32:09 +02:00
TayfurYldz d03002bcee fix: normalize multiline plan slugs 2026-09-18 17:31:54 +02:00
TayfurYldz 1bea197584 fix: bind init attestation to current project 2026-09-18 17:31:38 +02:00
Shaun Lin e33359977c fix(catchup): skip malformed OpenCode parts 2026-09-18 17:31:18 +02:00
238 changed files with 7823 additions and 1434 deletions
+1 -1
View File
@@ -28,7 +28,7 @@ hooks:
- type: command
command: "SH=\"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\"; [ -f \"$SH\" ] || SH=$(ls \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\" 2>/dev/null | head -1); [ -n \"$SH\" ] && [ -f \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
metadata:
version: "3.20.0"
version: "3.20.7"
---
# Planning with Files
@@ -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.");
@@ -18,6 +18,27 @@ param(
[switch]$Gated
)
# Windows PowerShell 5.1 can silently relocate a -File invocation when the
# inherited cwd contains wildcard characters such as [ or ]. Recover the
# physical cwd for a direct invocation before any project-relative paths are
# resolved.
if ($PSVersionTable.PSVersion.Major -eq 5 -and
[System.Management.Automation.WildcardPattern]::ContainsWildcardCharacters([Environment]::CurrentDirectory)) {
$processArgs = [Environment]::GetCommandLineArgs()
for ($index = 0; $index -lt ($processArgs.Length - 1); $index++) {
if ($processArgs[$index] -ieq '-File') {
$entryScript = $processArgs[$index + 1]
if (-not [IO.Path]::IsPathRooted($entryScript)) {
$entryScript = Join-Path ([Environment]::CurrentDirectory) $entryScript
}
if ([IO.Path]::GetFullPath($entryScript) -eq [IO.Path]::GetFullPath($PSCommandPath)) {
Set-Location -LiteralPath ([Environment]::CurrentDirectory)
}
break
}
}
}
$DATE = Get-Date -Format "yyyy-MM-dd"
# Resolve v3 opt-in mode. -Gated implies autonomous and is the stronger marker.
@@ -80,6 +101,26 @@ function Get-InheritedMode([string]$CurrentMode) {
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") {
Write-Host "Unknown template: $Template (available: default, analytics). Using default."
@@ -136,20 +177,7 @@ if ($UsePlanDir) {
$Counter++
}
$TargetDir = Join-Path $PlanningRoot $PlanId
New-Item -ItemType Directory -Path $TargetDir -Force | Out-Null
# Reuse the selector's contained, atomic pointer replacement. Set-Content
# would follow a reparse point and truncate a hardlinked pointer in place,
# overwriting whichever file shares that inode.
$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
}
New-Item -ItemType Directory -Path $TargetDir -Force -ErrorAction Stop | Out-Null
$Mode = Get-InheritedMode $Mode
} else {
$TargetDir = (Get-Location).Path
@@ -173,11 +201,12 @@ if ($UsePlanDir) {
Write-Host "PLAN_ID=$PlanId"
}
try {
# Create task_plan.md if it doesn't exist
if (-not (Test-Path -LiteralPath $TaskPlanPath)) {
$AnalyticsPlan = Join-Path $TemplateDir "analytics_task_plan.md"
if ($Template -eq "analytics" -and (Test-Path $AnalyticsPlan)) {
Copy-Item -LiteralPath $AnalyticsPlan -Destination $TaskPlanPath
Copy-Item -LiteralPath $AnalyticsPlan -Destination $TaskPlanPath -ErrorAction Stop
} else {
@"
# Task Plan: [Brief Description]
@@ -226,7 +255,7 @@ Phase 1
## Errors Encountered
| Error | Resolution |
|-------|------------|
"@ | Out-File -LiteralPath $TaskPlanPath -Encoding UTF8
"@ | Out-File -LiteralPath $TaskPlanPath -Encoding UTF8 -ErrorAction Stop
}
Write-Host "Created $TaskPlanDisplay"
} else {
@@ -237,7 +266,7 @@ Phase 1
if (-not (Test-Path -LiteralPath $FindingsPath)) {
$AnalyticsFindings = Join-Path $TemplateDir "analytics_findings.md"
if ($Template -eq "analytics" -and (Test-Path $AnalyticsFindings)) {
Copy-Item -LiteralPath $AnalyticsFindings -Destination $FindingsPath
Copy-Item -LiteralPath $AnalyticsFindings -Destination $FindingsPath -ErrorAction Stop
} else {
@"
# Findings & Decisions
@@ -258,7 +287,7 @@ if (-not (Test-Path -LiteralPath $FindingsPath)) {
## Resources
-
"@ | Out-File -LiteralPath $FindingsPath -Encoding UTF8
"@ | Out-File -LiteralPath $FindingsPath -Encoding UTF8 -ErrorAction Stop
}
Write-Host "Created $FindingsDisplay"
} else {
@@ -287,7 +316,7 @@ if (-not (Test-Path -LiteralPath $ProgressPath)) {
### Errors
| Error | Resolution |
|-------|------------|
"@ | Out-File -LiteralPath $ProgressPath -Encoding UTF8
"@ | Out-File -LiteralPath $ProgressPath -Encoding UTF8 -ErrorAction Stop
} else {
@"
# Progress Log
@@ -308,12 +337,56 @@ if (-not (Test-Path -LiteralPath $ProgressPath)) {
### Errors
| Error | Resolution |
|-------|------------|
"@ | Out-File -LiteralPath $ProgressPath -Encoding UTF8
"@ | Out-File -LiteralPath $ProgressPath -Encoding UTF8 -ErrorAction Stop
}
Write-Host "Created $ProgressDisplay"
} else {
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.
$pointerSet = $false
for ($attempt = 1; $attempt -le 5; $attempt++) {
$global:LASTEXITCODE = 0
try {
$selectorResult = & $PlanSelector $PlanId 2>&1
} catch {
$selectorResult = $_
$global:LASTEXITCODE = 1
}
if ($LASTEXITCODE -eq 0) {
$pointerSet = $true
break
}
# Another writer can replace the pointer between the selector's
# Get-Item and final-path check. Retry only that transient result.
$transientPointerRace = $selectorResult -is [System.Management.Automation.ErrorRecord] -and
$selectorResult.Exception.Message -ceq
'Error: could not set the active plan pointer: the active plan pointer became unsafe during replacement'
if ($attempt -eq 5 -or -not $transientPointerRace) {
break
}
Start-Sleep -Milliseconds 50
$global:LASTEXITCODE = 0
try {
& $PlanSelector -VerifyRoot *> $null
} catch {
$global:LASTEXITCODE = 1
}
if ($LASTEXITCODE -ne 0) { break }
}
if (-not $pointerSet) {
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!"
@@ -350,42 +423,94 @@ if ($Mode -ne "") {
# (c) auto-attest (attestation default-on in v3 modes, security strand rec 1).
# attest-plan.ps1 intentionally refuses non-Windows hosts because its secure
# no-follow implementation uses Win32 handles. On Unix, use the POSIX
# attester instead. Bind slug mode to the plan we just created so an
# inherited PLAN_ID cannot redirect attestation to another plan.
# 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 $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 {
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) {
$AttestPs1 = Join-Path $ScriptDir "attest-plan.ps1"
if (Test-Path -LiteralPath $AttestPs1) {
& $AttestPs1 *> $null
$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 {
$AttestSh = Join-Path $ScriptDir "attest-plan.sh"
$AttestationCommand = "attest-plan.sh"
$AttestSh = Join-Path $ScriptDir $AttestationCommand
$Sh = Get-Command sh -ErrorAction SilentlyContinue
if ($Sh -and (Test-Path -LiteralPath $AttestSh)) {
& $Sh.Path $AttestSh *> $null
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)"
}
}
@@ -103,6 +103,7 @@ slugify() {
# Lowercase, non-alphanumerics → '-', collapse repeats, trim leading/trailing '-'
printf '%s' "$1" \
| tr '[:upper:]' '[:lower:]' \
| tr '\r\n' '--' \
| sed -e 's/[^a-z0-9]/-/g' -e 's/-\{2,\}/-/g' -e 's/^-//' -e 's/-$//' \
| cut -c1-40
}
@@ -185,6 +186,10 @@ apply_v3_mode() {
_mode_plan="$2"
[ -z "$MODE" ] && return 0
ATTESTATION_OK=0
ATTESTATION_COMMAND="attest-plan.sh"
ATTESTATION_REASON="task_plan.md was not available for attestation"
# (a) reset the gate block counter and drop any stale gate ledger so a prior
# run's high block count cannot let the next run stop instantly.
printf '0\n' > "${_mode_dir}/.stop_blocks"
@@ -202,12 +207,61 @@ apply_v3_mode() {
# (c) auto-attest the plan (attestation default-on in v3 modes, security
# strand rec 1). attest-plan.sh resolves the same way init-session just
# pinned things: in slug mode PLAN_ID points at this plan dir; in legacy
# mode it is empty and the script falls back to ./task_plan.md at root.
# Run from the project root (CWD here) so both resolutions land.
_attest="${SCRIPT_DIR}/attest-plan.sh"
if [ -f "${_attest}" ] && [ -f "${_mode_plan}" ]; then
PLAN_ID="${PLAN_ID:-}" sh "${_attest}" >/dev/null 2>&1 || true
# pinned things. Slug mode binds both selectors to the plan that was
# just created, so an inherited PWF_PLAN_ROOT or PLAN_ID 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. Run from the project root (CWD here) so both
# resolutions land.
_attest="${SCRIPT_DIR}/${ATTESTATION_COMMAND}"
if [ ! -f "${_attest}" ]; then
ATTESTATION_REASON="${ATTESTATION_COMMAND} was not found beside init-session.sh"
return 0
fi
if [ ! -f "${_mode_plan}" ]; then
return 0
fi
if [ "$SLUG_MODE" -eq 1 ]; then
if _attest_output="$(PWF_PLAN_ROOT="$PWD" PLAN_ID="${PLAN_ID}" sh "${_attest}" 2>&1)"; then
ATTESTATION_OK=1
ATTESTATION_REASON=""
return 0
else
_attest_rc=$?
fi
else
if _attest_output="$(PWF_PLAN_ROOT="" PLAN_ID="" sh "${_attest}" 2>&1)"; then
ATTESTATION_OK=1
ATTESTATION_REASON=""
return 0
else
_attest_rc=$?
fi
fi
_attest_reason="$(
printf '%s\n' "${_attest_output}" |
sed -n '/[^[:space:]]/ { s/[[:space:]][[:space:]]*/ /g; s/^ //; s/ $//; p; q; }' |
cut -c1-300
)"
if [ -n "${_attest_reason}" ]; then
ATTESTATION_REASON="${_attest_reason}"
else
ATTESTATION_REASON="${ATTESTATION_COMMAND} exited with code ${_attest_rc}"
fi
return 0
}
print_v3_mode_status() {
_status_dir="$1"
_marker="$(cat "${_status_dir}/.mode")"
if [ "${ATTESTATION_OK:-0}" -eq 1 ]; then
printf 'Mode: %s (attested, gate counter reset)\n' "${_marker}"
else
printf 'Mode: %s (NOT attested: %s; run %s before the first hook fire)\n' \
"${_marker}" "${ATTESTATION_REASON:-attestation failed}" "${ATTESTATION_COMMAND:-attest-plan.sh}"
fi
}
@@ -422,7 +476,7 @@ if [ "$SLUG_MODE" -eq 1 ]; then
echo "Pin this terminal to the plan for parallel sessions:"
echo " export PLAN_ID=$PLAN_ID"
if [ -n "$MODE" ]; then
echo "Mode: $(cat "${PLAN_DIR}/.mode") (attested, gate counter reset)"
print_v3_mode_status "${PLAN_DIR}"
fi
else
PROJECT_NAME="${PROJECT_NAME:-project}"
@@ -433,6 +487,6 @@ else
echo "Planning files initialized!"
echo "Files: task_plan.md, findings.md, progress.md"
if [ -n "$MODE" ]; then
echo "Mode: $(cat "$(pwd)/.mode") (attested, gate counter reset)"
print_v3_mode_status "$(pwd)"
fi
fi
@@ -845,7 +845,10 @@ class Injector(object):
)
raise Bail()
if plan_id:
if slug_is_valid(plan_id) and is_dir(plan_prefix + ".planning/" + plan_id):
# A linked plan directory is never selectable (#270): the same
# `[ ! -L ]` the reference applies on every branch below.
if (slug_is_valid(plan_id) and is_dir(plan_prefix + ".planning/" + plan_id)
and not is_link(plan_prefix + ".planning/" + plan_id)):
resolved = plan_prefix + ".planning/" + plan_id
scope = "scoped"
explicit = True
@@ -864,7 +867,7 @@ class Injector(object):
active = b""
if active and slug_is_valid(active):
slug = active.decode("ascii")
if is_dir(plan_prefix + ".planning/" + slug):
if is_dir(plan_prefix + ".planning/" + slug) and not is_link(plan_prefix + ".planning/" + slug):
resolved = plan_prefix + ".planning/" + slug
scope = "scoped"
if not resolved and is_dir(plan_prefix + ".planning"):
@@ -880,6 +883,8 @@ class Injector(object):
candidate = plan_prefix + ".planning/" + name
if not is_dir(candidate):
continue
if is_link(candidate):
continue
if not slug_is_valid(name):
continue
if not is_file(candidate + "/task_plan.md"):
@@ -1327,7 +1332,12 @@ def plan_is_ambiguous(plan_root, project_root, plan_id=""):
except OSError:
names = []
for name in names:
if slug_is_valid(name) and is_file(plan_root + "/" + name + "/task_plan.md"):
candidate_dir = plan_root + "/" + name
# A linked plan directory is not selectable, so it never counts (#270):
# the reference tests `[ -L "$plan_candidate_dir" ]` before `-f`.
if is_link(candidate_dir):
continue
if slug_is_valid(name) and is_file(candidate_dir + "/task_plan.md"):
count += 1
if count > 1:
return True
@@ -1364,7 +1374,7 @@ def resolve_plan_dir(env=None):
if plan_id:
if slug_is_valid(plan_id):
candidate = fs_root + "/" + plan_id
if is_dir(candidate) and within(candidate):
if is_dir(candidate) and not is_link(candidate) and within(candidate):
return found(plan_id)
return ("", "")
@@ -1382,7 +1392,7 @@ def resolve_plan_dir(env=None):
if slug_is_valid(active):
slug = active.decode("ascii")
candidate = fs_root + "/" + slug
if is_dir(candidate) and within(candidate):
if is_dir(candidate) and not is_link(candidate) and within(candidate):
return found(slug)
if is_dir(fs_root):
@@ -1398,6 +1408,8 @@ def resolve_plan_dir(env=None):
continue
if name.startswith("."):
continue
if is_link(candidate):
continue
if not slug_is_valid(name):
continue
if not is_file(candidate + "/task_plan.md"):
@@ -263,8 +263,9 @@ if [ -z "${PLAN_ID:-}" ]; then
PLAN_COUNT=1
fi
for plan_candidate in "${PLAN_PREFIX}".planning/*/task_plan.md; do
[ -f "$plan_candidate" ] || continue
plan_candidate_dir="${plan_candidate%/task_plan.md}"
[ -L "$plan_candidate_dir" ] && continue
[ -f "$plan_candidate" ] || continue
slug_is_valid "${plan_candidate_dir##*/}" || continue
PLAN_COUNT=$((PLAN_COUNT + 1))
if [ "$PLAN_COUNT" -gt 1 ]; then PLAN_AMBIGUOUS=1; break; fi
@@ -295,7 +296,9 @@ if [ -n "${PLAN_ID:-}" ]; then
# printing on those would spam the transcript with the same line. The
# userprompt fire is also the one plan-doctor.sh drives, so /plan-doctor
# still sees and reports the state.
if slug_is_valid "$PLAN_ID" && [ -d "${PLAN_PREFIX}.planning/${PLAN_ID}" ]; then
# A linked plan directory is never selectable (#270): same `-L` rule as
# the counter above and as resolve-plan-dir.sh, on every branch below.
if slug_is_valid "$PLAN_ID" && [ -d "${PLAN_PREFIX}.planning/${PLAN_ID}" ] && [ ! -L "${PLAN_PREFIX}.planning/${PLAN_ID}" ]; then
RESOLVED="${PLAN_PREFIX}.planning/${PLAN_ID}"; SCOPE="scoped"; EXPLICIT=1
else
if [ "$CONTEXT" = "userprompt" ]; then
@@ -305,7 +308,7 @@ if [ -n "${PLAN_ID:-}" ]; then
fi
elif [ -f "${PLAN_PREFIX}.planning/.active_plan" ]; then
AP=$(tr -d '\r\n[:space:]' < "${PLAN_PREFIX}.planning/.active_plan" 2>/dev/null)
if [ -n "$AP" ] && slug_is_valid "$AP" && [ -d "${PLAN_PREFIX}.planning/${AP}" ]; then
if [ -n "$AP" ] && slug_is_valid "$AP" && [ -d "${PLAN_PREFIX}.planning/${AP}" ] && [ ! -L "${PLAN_PREFIX}.planning/${AP}" ]; then
RESOLVED="${PLAN_PREFIX}.planning/${AP}"; SCOPE="scoped"
fi
fi
@@ -314,6 +317,7 @@ if [ -z "$RESOLVED" ] && [ -d "${PLAN_PREFIX}.planning" ]; then
for d in "${PLAN_PREFIX}".planning/*/; do
d="${d%/}"; n="${d##*/}"
case "$n" in .*) continue;; esac
[ -L "$d" ] && continue
slug_is_valid "$n" || continue
[ -f "$d/task_plan.md" ] || continue
m=$(stat -c '%Y' "$d" 2>/dev/null || stat -f '%m' "$d" 2>/dev/null || date -r "$d" +%s 2>/dev/null || echo 0)
@@ -7,9 +7,10 @@
The ONLY sanctioned concurrent-safe writer of task_plan.md status lines. The
orchestrator owns task_plan.md; workers NEVER edit it directly. The edit is
a read-modify-write under the portable
<plan-dir>\.pwf-locks\phase-status.lock directory lock, with an atomic
temp-file + move swap so a torn write can never leave a half-rewritten plan
on disk (architecture C4).
<plan-dir>\.pwf-locks\phase-status.lock namespace. Ownership is granted by
atomically creating its .owner file, rather than trusting an external mkdir
exit status. The plan rewrite uses an atomic temp-file + move swap so a torn
write can never leave a half-rewritten plan on disk (architecture C4).
Editing task_plan.md changes its SHA, so the orchestrator must re-attest at
phase boundaries (see attest-plan.ps1).
@@ -102,18 +103,44 @@ function Enter-PwfDirectoryLock {
$wait = [Diagnostics.Stopwatch]::StartNew()
while ($wait.Elapsed.TotalSeconds -lt 5) {
$createdByUs = $false
try {
New-Item -Path $LockDir -ItemType Directory -ErrorAction Stop | Out-Null
$createdByUs = $true
[System.IO.File]::WriteAllText($ownerFile, $token + "`n", $utf8NoBom)
[void][System.IO.Directory]::CreateDirectory($LockDir)
} catch {
Start-Sleep -Milliseconds 100
continue
}
$stream = $null
$createdOwner = $false
$claimed = $false
try {
# FileMode.CreateNew is the cross-runtime ownership decision. It
# fails atomically when either the shell or PowerShell writer has
# already claimed .owner, even if both observed mkdir success.
$stream = [System.IO.File]::Open(
$ownerFile,
[System.IO.FileMode]::CreateNew,
[System.IO.FileAccess]::Write,
[System.IO.FileShare]::None
)
$createdOwner = $true
$bytes = $utf8NoBom.GetBytes($token + "`n")
$stream.Write($bytes, 0, $bytes.Length)
$stream.Flush()
$claimed = $true
return [PSCustomObject]@{
Directory = $LockDir
OwnerFile = $ownerFile
Token = $token
}
} catch {
if ($createdByUs) {
# Existing ownership is the normal contention path. Other failures
# remain fail-closed and are retried only within the bounded wait.
} finally {
if ($stream) {
$stream.Dispose()
}
if ($createdOwner -and -not $claimed) {
try {
if ([System.IO.File]::Exists($ownerFile)) {
$ownerValue = [System.IO.File]::ReadAllText($ownerFile).Trim()
@@ -121,13 +148,12 @@ function Enter-PwfDirectoryLock {
[System.IO.File]::Delete($ownerFile)
}
}
[System.IO.Directory]::Delete($LockDir, $false)
} catch {
# Leave any directory we cannot prove is still ours intact.
# Leave any owner file we cannot prove is still ours intact.
}
}
Start-Sleep -Milliseconds 100
}
Start-Sleep -Milliseconds 100
}
return $null
@@ -174,7 +200,7 @@ $planDir = Split-Path -Parent $planFile
$lockRoot = Join-Path $planDir ".pwf-locks"
$lockDir = Join-Path $lockRoot "phase-status.lock"
# Atomic directory creation is the common lock primitive used by both the sh
# Exclusive .owner creation is the common lock primitive used by both the sh
# and PowerShell implementations. Failure to acquire within about five seconds
# is fail-closed: no plan read/rewrite is attempted.
$lock = Enter-PwfDirectoryLock -LockRoot $lockRoot -LockDir $lockDir
@@ -4,9 +4,12 @@
# This is the ONLY sanctioned concurrent-safe writer of task_plan.md status
# lines. The orchestrator owns task_plan.md; workers NEVER edit it directly.
# All status edits go through this read-modify-write under the portable
# <plan-dir>/.pwf-locks/phase-status.lock directory lock, with an atomic
# temp-file + mv swap so a torn write can never leave a half-rewritten plan on
# disk (architecture C4).
# <plan-dir>/.pwf-locks/phase-status.lock namespace. Lock ownership is the
# atomic no-clobber creation of its .owner file; the directory's mkdir exit
# status is only provisional because some Windows-native implementations can
# report success to two simultaneous creators. The plan rewrite still uses an
# atomic temp-file + mv swap so a torn write can never leave a half-rewritten
# plan on disk (architecture C4).
#
# Note: editing task_plan.md changes its SHA, so the orchestrator must
# re-attest at phase boundaries (see attest-plan.sh).
@@ -106,6 +109,22 @@ release_lock() {
LOCK_ACQUIRED=0
}
claim_lock_owner() {
owner_file="${LOCK_DIR}/.owner"
# POSIX noclobber makes this redirection an exclusive create. This is the
# actual ownership decision: a Windows-native mkdir may report success
# after another process won the directory-creation race (issue #281).
if (
umask 077
set -C
printf '%s\n' "${LOCK_TOKEN}" > "${owner_file}"
) 2>/dev/null; then
LOCK_ACQUIRED=1
return 0
fi
return 1
}
acquire_lock() {
mkdir -p "${LOCK_ROOT}" 2>/dev/null || {
printf "[phase-status] Cannot create lock root %s.\n" "${LOCK_ROOT}" >&2
@@ -114,7 +133,13 @@ acquire_lock() {
LOCK_TOKEN="phase-status-$$-$(date +%s 2>/dev/null || printf 0)"
started_at="$(date +%s 2>/dev/null || printf 0)"
attempts=0
while ! mkdir "${LOCK_DIR}" 2>/dev/null; do
while :; do
# Directory creation is intentionally idempotent. The exclusive owner
# file below, not this external utility's exit status, grants the lock.
mkdir "${LOCK_DIR}" 2>/dev/null || true
if [ -d "${LOCK_DIR}" ] && claim_lock_owner; then
return 0
fi
attempts=$((attempts + 1))
now="$(date +%s 2>/dev/null || printf 0)"
if { [ "${started_at}" -gt 0 ] 2>/dev/null \
@@ -125,13 +150,6 @@ acquire_lock() {
fi
sleep 0.1
done
if ! printf '%s\n' "${LOCK_TOKEN}" > "${LOCK_DIR}/.owner" 2>/dev/null; then
rmdir "${LOCK_DIR}" 2>/dev/null || true
printf "[phase-status] Cannot record lock ownership in %s.\n" "${LOCK_DIR}" >&2
return 1
fi
LOCK_ACQUIRED=1
return 0
}
trap 'release_lock' EXIT
@@ -139,6 +139,24 @@ function Test-WithinRoot {
return $candNorm.StartsWith($rootNorm + [System.IO.Path]::DirectorySeparatorChar, [System.StringComparison]::OrdinalIgnoreCase)
}
# A linked plan directory (symlink or junction) is never selectable: not by
# PLAN_ID, not by the pointer, not by the newest scan, and it never counts
# (#270). This is `[ -L ]` of resolve-plan-dir.sh and is_link of the Python
# twin: LinkType names symlinks and junctions only. The ReparsePoint
# attribute alone would also match OneDrive Files On-Demand placeholders,
# which every synced directory and file carries and which are not links to
# sh. The same predicate guards the pointer file below (#275).
function Test-LinkedDirectory {
param($PathOrItem)
if ($PathOrItem -is [string]) {
$item = Get-Item -LiteralPath $PathOrItem -Force -ErrorAction SilentlyContinue
} else {
$item = $PathOrItem
}
if (-not $item) { return $false }
return ([string]$item.LinkType) -in @('SymbolicLink', 'Junction')
}
$activeFile = Join-Path $PlanRoot ".active_plan"
# A set PLAN_ID is a BINDING, not a hint (issue #237). A selector that names
@@ -158,6 +176,9 @@ if (-not $env:PLAN_ID) {
}
if (Test-Path -LiteralPath $PlanRoot -PathType Container) {
foreach ($entry in (Get-ChildItem -LiteralPath $PlanRoot -Directory -ErrorAction SilentlyContinue)) {
# A linked plan directory (symlink, junction) is not selectable and
# never counts, matching `[ -L ]` in resolve-plan-dir.sh (#270).
if (Test-LinkedDirectory $entry) { continue }
if ((Test-ValidSlug $entry.Name) -and
(Test-Path -LiteralPath (Join-Path $entry.FullName "task_plan.md") -PathType Leaf)) {
$planCount++
@@ -175,7 +196,7 @@ if ($planCount -gt 1) { exit 0 }
if ($env:PLAN_ID) {
if (Test-ValidSlug $env:PLAN_ID) {
$candidate = Join-Path $PlanRoot $env:PLAN_ID
if ((Test-Path -LiteralPath $candidate -PathType Container) -and (Test-WithinRoot $candidate)) {
if ((Test-Path -LiteralPath $candidate -PathType Container) -and -not (Test-LinkedDirectory $candidate) -and (Test-WithinRoot $candidate)) {
Write-Output $candidate
exit 0
}
@@ -185,12 +206,14 @@ if ($env:PLAN_ID) {
# Get-Item observes the link object even when its target is missing, unlike
# Test-Path which follows the target. An active pointer that is a directory or
# reparse point is an unsafe/ambiguous selector and must terminate resolution;
# a symlink is an unsafe/ambiguous selector and must terminate resolution;
# falling through would silently select and expose the newest unrelated plan.
# LinkType, not the ReparsePoint attribute: OneDrive Files On-Demand marks
# every synced file as a reparse point, and such a pointer is a plain file
# to every other route (#275).
$activeItem = Get-Item -LiteralPath $activeFile -Force -ErrorAction SilentlyContinue
if ($activeItem) {
if ($activeItem.PSIsContainer -or
(($activeItem.Attributes -band [IO.FileAttributes]::ReparsePoint) -ne 0)) {
if ($activeItem.PSIsContainer -or (Test-LinkedDirectory $activeItem)) {
exit 0
}
# Get-Content -Raw returns $null for a zero-byte pointer; an empty pointer
@@ -198,7 +221,7 @@ if ($activeItem) {
$planId = "$(Get-Content -LiteralPath $activeFile -Raw -ErrorAction SilentlyContinue)".Trim()
if ($planId -and (Test-ValidSlug $planId)) {
$candidate = Join-Path $PlanRoot $planId
if ((Test-Path -LiteralPath $candidate -PathType Container) -and (Test-WithinRoot $candidate)) {
if ((Test-Path -LiteralPath $candidate -PathType Container) -and -not (Test-LinkedDirectory $candidate) -and (Test-WithinRoot $candidate)) {
Write-Output $candidate
exit 0
}
@@ -211,6 +234,7 @@ if ($activeItem) {
if (Test-Path -LiteralPath $PlanRoot -PathType Container) {
$latest = Get-ChildItem -LiteralPath $PlanRoot -Directory |
Where-Object { -not $_.Name.StartsWith('.') } |
Where-Object { -not (Test-LinkedDirectory $_) } |
Where-Object { Test-ValidSlug $_.Name } |
Where-Object { Test-Path -LiteralPath (Join-Path $_.FullName "task_plan.md") -PathType Leaf } |
Where-Object { Test-WithinRoot $_.FullName } |
@@ -246,10 +246,16 @@ mtime_of() {
printf "0\n"
}
# A linked plan directory (symlink or junction; `-L` sees both under Git
# Bash) is never selectable: not by PLAN_ID, not by the pointer, not by the
# newest-mtime scan, and it never counts below (#270). Containment alone let
# a link that stays inside the root be selected while the counter skipped
# it, so one real plan plus a newer linked one became an mtime guess again.
resolve_from_env() {
plan_id="${PLAN_ID:-}"
slug_is_valid "${plan_id}" || return 1
candidate="${PLAN_ROOT}/${plan_id}"
[ -L "${candidate}" ] && return 1
if [ -d "${candidate}" ] && is_within_root "${candidate}"; then
printf "%s\n" "${candidate}"
return 0
@@ -268,6 +274,7 @@ resolve_from_active_file() {
esac
slug_is_valid "${plan_id}" || return 1
candidate="${PLAN_ROOT}/${plan_id}"
[ -L "${candidate}" ] && return 1
if [ -d "${candidate}" ] && is_within_root "${candidate}"; then
printf "%s\n" "${candidate}"
return 0
@@ -288,6 +295,7 @@ resolve_latest_dir() {
case "${name}" in
.*) continue ;;
esac
[ -L "${clean}" ] && continue
slug_is_valid "${name}" || continue
[ -f "${clean}/task_plan.md" ] || continue
is_within_root "${clean}" || continue
@@ -338,8 +346,9 @@ if [ -z "${PLAN_ID:-}" ]; then
PLAN_COUNT=1
fi
for plan_candidate in "${PLAN_ROOT}"/*/task_plan.md; do
[ -f "$plan_candidate" ] || continue
plan_candidate_dir="${plan_candidate%/task_plan.md}"
[ -L "$plan_candidate_dir" ] && continue
[ -f "$plan_candidate" ] || continue
slug_is_valid "${plan_candidate_dir##*/}" || continue
PLAN_COUNT=$((PLAN_COUNT + 1))
if [ "$PLAN_COUNT" -gt 1 ]; then PLAN_AMBIGUOUS=1; break; fi
@@ -468,13 +468,16 @@ def _opencode_state_annotation(state: Any) -> str:
def _format_opencode_part(data: Dict[str, Any], session_id: str) -> Optional[Dict[str, Any]]:
"""Print-ready summary for one OpenCode part row."""
if not isinstance(data, dict):
return None
ptype = data.get('type')
short = safe_session_label(session_id)
if ptype == 'tool':
tool = (data.get('tool') or '').lower()
tool_value = data.get('tool')
tool = tool_value.lower() if isinstance(tool_value, str) else ''
state = data.get('state') or {}
input_ = state.get('input') if isinstance(state, dict) else None
input_ = input_ or {}
input_ = input_ if isinstance(input_, dict) else {}
outcome = _opencode_state_annotation(state)
if tool in ('write', 'edit'):
fp = input_.get('filePath', '')
@@ -486,7 +489,8 @@ def _format_opencode_part(data: Dict[str, Any], session_id: str) -> Optional[Dic
return {'session': short, 'summary': f"Tool bash: {cmd}{outcome}"}
return {'session': short, 'summary': f"Tool {tool}{outcome}"}
if ptype == 'text':
text = (data.get('text') or '')[:300]
text_value = data.get('text')
text = text_value[:300] if isinstance(text_value, str) else ''
if text.strip():
return {'session': short, 'summary': f"text: {text}"}
return None
@@ -577,6 +581,7 @@ def opencode_catchup(project_path: str, mode: str = 'no-history') -> None:
"""
SELECT time_created, data FROM part
WHERE session_id = ?
AND json_valid(data)
AND json_extract(data, '$.type') = 'tool'
AND lower(json_extract(data, '$.tool')) IN ('write', 'edit', 'patch')
AND (
@@ -121,9 +121,14 @@ function Test-SafeActiveFile {
param([switch]$AllowLink)
$item = Get-Item -LiteralPath $ActiveFile -Force -ErrorAction SilentlyContinue
if (-not $item) { return $false }
# Reading may follow a verified in-project link; writing must not.
# Reading may follow a verified in-project link; writing must not. A link
# is a symlink or junction by LinkType, never the bare ReparsePoint
# attribute: OneDrive Files On-Demand marks every synced file as a
# reparse point, and the pointer must stay writable there (#275).
$linked = ([string]$item.LinkType) -in @('SymbolicLink', 'Junction')
return -not $item.PSIsContainer -and
($AllowLink -or (($item.Attributes -band [IO.FileAttributes]::ReparsePoint) -eq 0)) -and
($AllowLink -or -not $linked) -and
($AllowLink -or -not $item.IsReadOnly) -and
(Test-WithinRoot $ActiveFile)
}
@@ -204,6 +209,8 @@ function Show-PlanList {
Write-Output "[active] marks the shared .active_plan pointer; listing does not bind this session."
$found = $false
foreach ($plan in (Get-ChildItem -LiteralPath $PlanRoot -Directory -ErrorAction SilentlyContinue | Sort-Object Name)) {
# A linked plan directory is never a plan (#270): no resolver selects it.
if (([string]$plan.LinkType) -in @('SymbolicLink', 'Junction')) { continue }
if (-not (Test-ValidSlug $plan.Name) -or -not (Test-WithinRoot $plan.FullName)) { continue }
$planFile = Join-Path $plan.FullName "task_plan.md"
if (-not (Test-Path -LiteralPath $planFile -PathType Leaf) -or -not (Test-WithinRoot $planFile)) { continue }
@@ -281,6 +288,11 @@ if (-not (Test-Path -LiteralPath $PlanDir -PathType Container)) {
Write-Error "Run: init-session.sh `"$PlanId`" to create it, or check .planning\ for available plans."
exit 1
}
$planDirItem = Get-Item -LiteralPath $PlanDir -Force -ErrorAction SilentlyContinue
if ($planDirItem -and (([string]$planDirItem.LinkType) -in @('SymbolicLink', 'Junction'))) {
Write-Error "Error: plan directory is a symlink or junction and no route selects it: $PlanDir"
exit 1
}
if (-not (Test-WithinRoot $PlanRoot) -or -not (Test-WithinRoot $PlanDir)) {
Write-Error "Error: plan directory must remain within the project."
exit 1
@@ -305,10 +317,23 @@ try {
$stream.Write($bytes, 0, $bytes.Length)
$stream.Flush()
} finally { $stream.Dispose() }
if ($activeItem) {
[IO.File]::Replace($tempFile, $ActiveFile, [NullString]::Value)
} else {
[IO.File]::Move($tempFile, $ActiveFile)
$maxAttempts = 20
for ($attempt = 1; $attempt -le $maxAttempts; $attempt++) {
try {
$currentActive = Get-Item -LiteralPath $ActiveFile -Force -ErrorAction SilentlyContinue
if ($currentActive) {
if (-not (Test-SafeActiveFile)) {
throw [InvalidOperationException]::new("the active plan pointer became unsafe during replacement")
}
[IO.File]::Replace($tempFile, $ActiveFile, [NullString]::Value)
} else {
[IO.File]::Move($tempFile, $ActiveFile)
}
break
} catch [IO.IOException] {
if ($attempt -eq $maxAttempts) { throw }
Start-Sleep -Milliseconds 25
}
}
} catch {
Write-Error "Error: could not set the active plan pointer: $($_.Exception.Message)"
@@ -272,6 +272,9 @@ list_plans() {
printf '%s\n' 'Available plans:'
for _dir in "${PLAN_ROOT}"/*; do
[ -d "${_dir}" ] || continue
# A linked plan directory is never a plan (#270): no resolver selects
# it, so listing it would advertise a PLAN_ID every route refuses.
[ -L "${_dir}" ] && continue
_id="${_dir##*/}"
slug_is_valid "${_id}" || continue
is_within_root "${_dir}" || continue
@@ -312,7 +315,7 @@ if [ "${1:-}" = '' ]; then
exit 1
fi
plan_id="$(current_active)"
if [ -n "${plan_id}" ] && [ -d "${PLAN_ROOT}/${plan_id}" ] && is_within_root "${PLAN_ROOT}/${plan_id}"; then
if [ -n "${plan_id}" ] && [ -d "${PLAN_ROOT}/${plan_id}" ] && [ ! -L "${PLAN_ROOT}/${plan_id}" ] && is_within_root "${PLAN_ROOT}/${plan_id}"; then
printf '%s\n' "Active plan: ${plan_id}" "Path: ${PLAN_ROOT}/${plan_id}"
elif [ -n "${plan_id}" ]; then
printf '%s\n' "Active plan pointer: ${plan_id} (directory not found or outside project - stale pointer)"
@@ -333,6 +336,10 @@ if [ ! -d "${PLAN_DIR}" ]; then
"Run: init-session.sh \"${PLAN_ID}\" to create it, or use --list to see available plans." >&2
exit 1
fi
if [ -L "${PLAN_DIR}" ]; then
printf '%s\n' "Error: plan directory is a symlink or junction and no route selects it: ${PLAN_DIR}" >&2
exit 1
fi
if ! is_within_root "${PLAN_ROOT}" || ! is_within_root "${PLAN_DIR}"; then
printf '%s\n' 'Error: plan directory is outside the project or cannot be verified.' >&2
exit 1
@@ -8,6 +8,12 @@ State the analytical question or intended deliverable in one clear sentence.
[One sentence describing the analytical objective]
## Next Step
Record the single analytical action that should happen next. Update it whenever the active phase or immediate action changes.
[The single next analytical action. Update whenever phase status changes.]
## Current Phase
Name the phase currently being worked on.
@@ -76,6 +82,6 @@ Record each distinct error, the attempt number, and the resolution. Change the a
## Notes
- Update phase status as work progresses: `pending` to `in_progress` to `complete`.
- Re-read the goal and current phase before major analytical decisions.
- Re-read the goal, next step, and current phase before major analytical decisions.
- Log errors promptly so failed approaches are not repeated.
- Record query results and visual evidence in findings.md.
+1 -1
View File
@@ -10,7 +10,7 @@
"name": "planning-with-files",
"source": "./",
"description": "Persistent project planning files with lifecycle hooks that inject selected plan context. Automatic recovery uses project files only. Explicit catchup modes may read same-project local session records to emit aggregate counts or bounded nonce-framed excerpts. Optional gated mode can request continuation on capable hosts and never runs commands declared in Markdown. No network upload path. Installs across 60+ agents.",
"version": "3.20.0"
"version": "3.20.7"
}
]
}
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "planning-with-files",
"version": "3.20.0",
"version": "3.20.7",
"description": "Persistent project planning files with lifecycle hooks that inject selected plan context. Automatic recovery uses project files only. Explicit catchup modes may read same-project local session records to emit aggregate counts or bounded nonce-framed excerpts. Optional gated mode can request continuation on capable hosts and never runs commands declared in Markdown. No network upload path. Works across 60+ agents and includes Arabic, German, Spanish, Simplified Chinese, and Traditional Chinese.",
"author": {
"name": "OthmanAdi",
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/skill-hook.sh\" \"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\" \"${CODEBUDDY_PLUGIN_ROOT}/scripts/skill-hook.sh\" \"$HOME/.codebuddy/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
metadata:
version: "3.20.0"
version: "3.20.7"
---
@@ -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.");
@@ -18,6 +18,27 @@ param(
[switch]$Gated
)
# Windows PowerShell 5.1 can silently relocate a -File invocation when the
# inherited cwd contains wildcard characters such as [ or ]. Recover the
# physical cwd for a direct invocation before any project-relative paths are
# resolved.
if ($PSVersionTable.PSVersion.Major -eq 5 -and
[System.Management.Automation.WildcardPattern]::ContainsWildcardCharacters([Environment]::CurrentDirectory)) {
$processArgs = [Environment]::GetCommandLineArgs()
for ($index = 0; $index -lt ($processArgs.Length - 1); $index++) {
if ($processArgs[$index] -ieq '-File') {
$entryScript = $processArgs[$index + 1]
if (-not [IO.Path]::IsPathRooted($entryScript)) {
$entryScript = Join-Path ([Environment]::CurrentDirectory) $entryScript
}
if ([IO.Path]::GetFullPath($entryScript) -eq [IO.Path]::GetFullPath($PSCommandPath)) {
Set-Location -LiteralPath ([Environment]::CurrentDirectory)
}
break
}
}
}
$DATE = Get-Date -Format "yyyy-MM-dd"
# Resolve v3 opt-in mode. -Gated implies autonomous and is the stronger marker.
@@ -80,6 +101,26 @@ function Get-InheritedMode([string]$CurrentMode) {
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") {
Write-Host "Unknown template: $Template (available: default, analytics). Using default."
@@ -136,20 +177,7 @@ if ($UsePlanDir) {
$Counter++
}
$TargetDir = Join-Path $PlanningRoot $PlanId
New-Item -ItemType Directory -Path $TargetDir -Force | Out-Null
# Reuse the selector's contained, atomic pointer replacement. Set-Content
# would follow a reparse point and truncate a hardlinked pointer in place,
# overwriting whichever file shares that inode.
$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
}
New-Item -ItemType Directory -Path $TargetDir -Force -ErrorAction Stop | Out-Null
$Mode = Get-InheritedMode $Mode
} else {
$TargetDir = (Get-Location).Path
@@ -173,11 +201,12 @@ if ($UsePlanDir) {
Write-Host "PLAN_ID=$PlanId"
}
try {
# Create task_plan.md if it doesn't exist
if (-not (Test-Path -LiteralPath $TaskPlanPath)) {
$AnalyticsPlan = Join-Path $TemplateDir "analytics_task_plan.md"
if ($Template -eq "analytics" -and (Test-Path $AnalyticsPlan)) {
Copy-Item -LiteralPath $AnalyticsPlan -Destination $TaskPlanPath
Copy-Item -LiteralPath $AnalyticsPlan -Destination $TaskPlanPath -ErrorAction Stop
} else {
@"
# Task Plan: [Brief Description]
@@ -226,7 +255,7 @@ Phase 1
## Errors Encountered
| Error | Resolution |
|-------|------------|
"@ | Out-File -LiteralPath $TaskPlanPath -Encoding UTF8
"@ | Out-File -LiteralPath $TaskPlanPath -Encoding UTF8 -ErrorAction Stop
}
Write-Host "Created $TaskPlanDisplay"
} else {
@@ -237,7 +266,7 @@ Phase 1
if (-not (Test-Path -LiteralPath $FindingsPath)) {
$AnalyticsFindings = Join-Path $TemplateDir "analytics_findings.md"
if ($Template -eq "analytics" -and (Test-Path $AnalyticsFindings)) {
Copy-Item -LiteralPath $AnalyticsFindings -Destination $FindingsPath
Copy-Item -LiteralPath $AnalyticsFindings -Destination $FindingsPath -ErrorAction Stop
} else {
@"
# Findings & Decisions
@@ -258,7 +287,7 @@ if (-not (Test-Path -LiteralPath $FindingsPath)) {
## Resources
-
"@ | Out-File -LiteralPath $FindingsPath -Encoding UTF8
"@ | Out-File -LiteralPath $FindingsPath -Encoding UTF8 -ErrorAction Stop
}
Write-Host "Created $FindingsDisplay"
} else {
@@ -287,7 +316,7 @@ if (-not (Test-Path -LiteralPath $ProgressPath)) {
### Errors
| Error | Resolution |
|-------|------------|
"@ | Out-File -LiteralPath $ProgressPath -Encoding UTF8
"@ | Out-File -LiteralPath $ProgressPath -Encoding UTF8 -ErrorAction Stop
} else {
@"
# Progress Log
@@ -308,12 +337,56 @@ if (-not (Test-Path -LiteralPath $ProgressPath)) {
### Errors
| Error | Resolution |
|-------|------------|
"@ | Out-File -LiteralPath $ProgressPath -Encoding UTF8
"@ | Out-File -LiteralPath $ProgressPath -Encoding UTF8 -ErrorAction Stop
}
Write-Host "Created $ProgressDisplay"
} else {
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.
$pointerSet = $false
for ($attempt = 1; $attempt -le 5; $attempt++) {
$global:LASTEXITCODE = 0
try {
$selectorResult = & $PlanSelector $PlanId 2>&1
} catch {
$selectorResult = $_
$global:LASTEXITCODE = 1
}
if ($LASTEXITCODE -eq 0) {
$pointerSet = $true
break
}
# Another writer can replace the pointer between the selector's
# Get-Item and final-path check. Retry only that transient result.
$transientPointerRace = $selectorResult -is [System.Management.Automation.ErrorRecord] -and
$selectorResult.Exception.Message -ceq
'Error: could not set the active plan pointer: the active plan pointer became unsafe during replacement'
if ($attempt -eq 5 -or -not $transientPointerRace) {
break
}
Start-Sleep -Milliseconds 50
$global:LASTEXITCODE = 0
try {
& $PlanSelector -VerifyRoot *> $null
} catch {
$global:LASTEXITCODE = 1
}
if ($LASTEXITCODE -ne 0) { break }
}
if (-not $pointerSet) {
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!"
@@ -350,42 +423,94 @@ if ($Mode -ne "") {
# (c) auto-attest (attestation default-on in v3 modes, security strand rec 1).
# attest-plan.ps1 intentionally refuses non-Windows hosts because its secure
# no-follow implementation uses Win32 handles. On Unix, use the POSIX
# attester instead. Bind slug mode to the plan we just created so an
# inherited PLAN_ID cannot redirect attestation to another plan.
# 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 $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 {
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) {
$AttestPs1 = Join-Path $ScriptDir "attest-plan.ps1"
if (Test-Path -LiteralPath $AttestPs1) {
& $AttestPs1 *> $null
$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 {
$AttestSh = Join-Path $ScriptDir "attest-plan.sh"
$AttestationCommand = "attest-plan.sh"
$AttestSh = Join-Path $ScriptDir $AttestationCommand
$Sh = Get-Command sh -ErrorAction SilentlyContinue
if ($Sh -and (Test-Path -LiteralPath $AttestSh)) {
& $Sh.Path $AttestSh *> $null
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)"
}
}
@@ -103,6 +103,7 @@ slugify() {
# Lowercase, non-alphanumerics → '-', collapse repeats, trim leading/trailing '-'
printf '%s' "$1" \
| tr '[:upper:]' '[:lower:]' \
| tr '\r\n' '--' \
| sed -e 's/[^a-z0-9]/-/g' -e 's/-\{2,\}/-/g' -e 's/^-//' -e 's/-$//' \
| cut -c1-40
}
@@ -185,6 +186,10 @@ apply_v3_mode() {
_mode_plan="$2"
[ -z "$MODE" ] && return 0
ATTESTATION_OK=0
ATTESTATION_COMMAND="attest-plan.sh"
ATTESTATION_REASON="task_plan.md was not available for attestation"
# (a) reset the gate block counter and drop any stale gate ledger so a prior
# run's high block count cannot let the next run stop instantly.
printf '0\n' > "${_mode_dir}/.stop_blocks"
@@ -202,12 +207,61 @@ apply_v3_mode() {
# (c) auto-attest the plan (attestation default-on in v3 modes, security
# strand rec 1). attest-plan.sh resolves the same way init-session just
# pinned things: in slug mode PLAN_ID points at this plan dir; in legacy
# mode it is empty and the script falls back to ./task_plan.md at root.
# Run from the project root (CWD here) so both resolutions land.
_attest="${SCRIPT_DIR}/attest-plan.sh"
if [ -f "${_attest}" ] && [ -f "${_mode_plan}" ]; then
PLAN_ID="${PLAN_ID:-}" sh "${_attest}" >/dev/null 2>&1 || true
# pinned things. Slug mode binds both selectors to the plan that was
# just created, so an inherited PWF_PLAN_ROOT or PLAN_ID 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. Run from the project root (CWD here) so both
# resolutions land.
_attest="${SCRIPT_DIR}/${ATTESTATION_COMMAND}"
if [ ! -f "${_attest}" ]; then
ATTESTATION_REASON="${ATTESTATION_COMMAND} was not found beside init-session.sh"
return 0
fi
if [ ! -f "${_mode_plan}" ]; then
return 0
fi
if [ "$SLUG_MODE" -eq 1 ]; then
if _attest_output="$(PWF_PLAN_ROOT="$PWD" PLAN_ID="${PLAN_ID}" sh "${_attest}" 2>&1)"; then
ATTESTATION_OK=1
ATTESTATION_REASON=""
return 0
else
_attest_rc=$?
fi
else
if _attest_output="$(PWF_PLAN_ROOT="" PLAN_ID="" sh "${_attest}" 2>&1)"; then
ATTESTATION_OK=1
ATTESTATION_REASON=""
return 0
else
_attest_rc=$?
fi
fi
_attest_reason="$(
printf '%s\n' "${_attest_output}" |
sed -n '/[^[:space:]]/ { s/[[:space:]][[:space:]]*/ /g; s/^ //; s/ $//; p; q; }' |
cut -c1-300
)"
if [ -n "${_attest_reason}" ]; then
ATTESTATION_REASON="${_attest_reason}"
else
ATTESTATION_REASON="${ATTESTATION_COMMAND} exited with code ${_attest_rc}"
fi
return 0
}
print_v3_mode_status() {
_status_dir="$1"
_marker="$(cat "${_status_dir}/.mode")"
if [ "${ATTESTATION_OK:-0}" -eq 1 ]; then
printf 'Mode: %s (attested, gate counter reset)\n' "${_marker}"
else
printf 'Mode: %s (NOT attested: %s; run %s before the first hook fire)\n' \
"${_marker}" "${ATTESTATION_REASON:-attestation failed}" "${ATTESTATION_COMMAND:-attest-plan.sh}"
fi
}
@@ -422,7 +476,7 @@ if [ "$SLUG_MODE" -eq 1 ]; then
echo "Pin this terminal to the plan for parallel sessions:"
echo " export PLAN_ID=$PLAN_ID"
if [ -n "$MODE" ]; then
echo "Mode: $(cat "${PLAN_DIR}/.mode") (attested, gate counter reset)"
print_v3_mode_status "${PLAN_DIR}"
fi
else
PROJECT_NAME="${PROJECT_NAME:-project}"
@@ -433,6 +487,6 @@ else
echo "Planning files initialized!"
echo "Files: task_plan.md, findings.md, progress.md"
if [ -n "$MODE" ]; then
echo "Mode: $(cat "$(pwd)/.mode") (attested, gate counter reset)"
print_v3_mode_status "$(pwd)"
fi
fi
@@ -845,7 +845,10 @@ class Injector(object):
)
raise Bail()
if plan_id:
if slug_is_valid(plan_id) and is_dir(plan_prefix + ".planning/" + plan_id):
# A linked plan directory is never selectable (#270): the same
# `[ ! -L ]` the reference applies on every branch below.
if (slug_is_valid(plan_id) and is_dir(plan_prefix + ".planning/" + plan_id)
and not is_link(plan_prefix + ".planning/" + plan_id)):
resolved = plan_prefix + ".planning/" + plan_id
scope = "scoped"
explicit = True
@@ -864,7 +867,7 @@ class Injector(object):
active = b""
if active and slug_is_valid(active):
slug = active.decode("ascii")
if is_dir(plan_prefix + ".planning/" + slug):
if is_dir(plan_prefix + ".planning/" + slug) and not is_link(plan_prefix + ".planning/" + slug):
resolved = plan_prefix + ".planning/" + slug
scope = "scoped"
if not resolved and is_dir(plan_prefix + ".planning"):
@@ -880,6 +883,8 @@ class Injector(object):
candidate = plan_prefix + ".planning/" + name
if not is_dir(candidate):
continue
if is_link(candidate):
continue
if not slug_is_valid(name):
continue
if not is_file(candidate + "/task_plan.md"):
@@ -1327,7 +1332,12 @@ def plan_is_ambiguous(plan_root, project_root, plan_id=""):
except OSError:
names = []
for name in names:
if slug_is_valid(name) and is_file(plan_root + "/" + name + "/task_plan.md"):
candidate_dir = plan_root + "/" + name
# A linked plan directory is not selectable, so it never counts (#270):
# the reference tests `[ -L "$plan_candidate_dir" ]` before `-f`.
if is_link(candidate_dir):
continue
if slug_is_valid(name) and is_file(candidate_dir + "/task_plan.md"):
count += 1
if count > 1:
return True
@@ -1364,7 +1374,7 @@ def resolve_plan_dir(env=None):
if plan_id:
if slug_is_valid(plan_id):
candidate = fs_root + "/" + plan_id
if is_dir(candidate) and within(candidate):
if is_dir(candidate) and not is_link(candidate) and within(candidate):
return found(plan_id)
return ("", "")
@@ -1382,7 +1392,7 @@ def resolve_plan_dir(env=None):
if slug_is_valid(active):
slug = active.decode("ascii")
candidate = fs_root + "/" + slug
if is_dir(candidate) and within(candidate):
if is_dir(candidate) and not is_link(candidate) and within(candidate):
return found(slug)
if is_dir(fs_root):
@@ -1398,6 +1408,8 @@ def resolve_plan_dir(env=None):
continue
if name.startswith("."):
continue
if is_link(candidate):
continue
if not slug_is_valid(name):
continue
if not is_file(candidate + "/task_plan.md"):
@@ -263,8 +263,9 @@ if [ -z "${PLAN_ID:-}" ]; then
PLAN_COUNT=1
fi
for plan_candidate in "${PLAN_PREFIX}".planning/*/task_plan.md; do
[ -f "$plan_candidate" ] || continue
plan_candidate_dir="${plan_candidate%/task_plan.md}"
[ -L "$plan_candidate_dir" ] && continue
[ -f "$plan_candidate" ] || continue
slug_is_valid "${plan_candidate_dir##*/}" || continue
PLAN_COUNT=$((PLAN_COUNT + 1))
if [ "$PLAN_COUNT" -gt 1 ]; then PLAN_AMBIGUOUS=1; break; fi
@@ -295,7 +296,9 @@ if [ -n "${PLAN_ID:-}" ]; then
# printing on those would spam the transcript with the same line. The
# userprompt fire is also the one plan-doctor.sh drives, so /plan-doctor
# still sees and reports the state.
if slug_is_valid "$PLAN_ID" && [ -d "${PLAN_PREFIX}.planning/${PLAN_ID}" ]; then
# A linked plan directory is never selectable (#270): same `-L` rule as
# the counter above and as resolve-plan-dir.sh, on every branch below.
if slug_is_valid "$PLAN_ID" && [ -d "${PLAN_PREFIX}.planning/${PLAN_ID}" ] && [ ! -L "${PLAN_PREFIX}.planning/${PLAN_ID}" ]; then
RESOLVED="${PLAN_PREFIX}.planning/${PLAN_ID}"; SCOPE="scoped"; EXPLICIT=1
else
if [ "$CONTEXT" = "userprompt" ]; then
@@ -305,7 +308,7 @@ if [ -n "${PLAN_ID:-}" ]; then
fi
elif [ -f "${PLAN_PREFIX}.planning/.active_plan" ]; then
AP=$(tr -d '\r\n[:space:]' < "${PLAN_PREFIX}.planning/.active_plan" 2>/dev/null)
if [ -n "$AP" ] && slug_is_valid "$AP" && [ -d "${PLAN_PREFIX}.planning/${AP}" ]; then
if [ -n "$AP" ] && slug_is_valid "$AP" && [ -d "${PLAN_PREFIX}.planning/${AP}" ] && [ ! -L "${PLAN_PREFIX}.planning/${AP}" ]; then
RESOLVED="${PLAN_PREFIX}.planning/${AP}"; SCOPE="scoped"
fi
fi
@@ -314,6 +317,7 @@ if [ -z "$RESOLVED" ] && [ -d "${PLAN_PREFIX}.planning" ]; then
for d in "${PLAN_PREFIX}".planning/*/; do
d="${d%/}"; n="${d##*/}"
case "$n" in .*) continue;; esac
[ -L "$d" ] && continue
slug_is_valid "$n" || continue
[ -f "$d/task_plan.md" ] || continue
m=$(stat -c '%Y' "$d" 2>/dev/null || stat -f '%m' "$d" 2>/dev/null || date -r "$d" +%s 2>/dev/null || echo 0)
@@ -139,6 +139,24 @@ function Test-WithinRoot {
return $candNorm.StartsWith($rootNorm + [System.IO.Path]::DirectorySeparatorChar, [System.StringComparison]::OrdinalIgnoreCase)
}
# A linked plan directory (symlink or junction) is never selectable: not by
# PLAN_ID, not by the pointer, not by the newest scan, and it never counts
# (#270). This is `[ -L ]` of resolve-plan-dir.sh and is_link of the Python
# twin: LinkType names symlinks and junctions only. The ReparsePoint
# attribute alone would also match OneDrive Files On-Demand placeholders,
# which every synced directory and file carries and which are not links to
# sh. The same predicate guards the pointer file below (#275).
function Test-LinkedDirectory {
param($PathOrItem)
if ($PathOrItem -is [string]) {
$item = Get-Item -LiteralPath $PathOrItem -Force -ErrorAction SilentlyContinue
} else {
$item = $PathOrItem
}
if (-not $item) { return $false }
return ([string]$item.LinkType) -in @('SymbolicLink', 'Junction')
}
$activeFile = Join-Path $PlanRoot ".active_plan"
# A set PLAN_ID is a BINDING, not a hint (issue #237). A selector that names
@@ -158,6 +176,9 @@ if (-not $env:PLAN_ID) {
}
if (Test-Path -LiteralPath $PlanRoot -PathType Container) {
foreach ($entry in (Get-ChildItem -LiteralPath $PlanRoot -Directory -ErrorAction SilentlyContinue)) {
# A linked plan directory (symlink, junction) is not selectable and
# never counts, matching `[ -L ]` in resolve-plan-dir.sh (#270).
if (Test-LinkedDirectory $entry) { continue }
if ((Test-ValidSlug $entry.Name) -and
(Test-Path -LiteralPath (Join-Path $entry.FullName "task_plan.md") -PathType Leaf)) {
$planCount++
@@ -175,7 +196,7 @@ if ($planCount -gt 1) { exit 0 }
if ($env:PLAN_ID) {
if (Test-ValidSlug $env:PLAN_ID) {
$candidate = Join-Path $PlanRoot $env:PLAN_ID
if ((Test-Path -LiteralPath $candidate -PathType Container) -and (Test-WithinRoot $candidate)) {
if ((Test-Path -LiteralPath $candidate -PathType Container) -and -not (Test-LinkedDirectory $candidate) -and (Test-WithinRoot $candidate)) {
Write-Output $candidate
exit 0
}
@@ -185,12 +206,14 @@ if ($env:PLAN_ID) {
# Get-Item observes the link object even when its target is missing, unlike
# Test-Path which follows the target. An active pointer that is a directory or
# reparse point is an unsafe/ambiguous selector and must terminate resolution;
# a symlink is an unsafe/ambiguous selector and must terminate resolution;
# falling through would silently select and expose the newest unrelated plan.
# LinkType, not the ReparsePoint attribute: OneDrive Files On-Demand marks
# every synced file as a reparse point, and such a pointer is a plain file
# to every other route (#275).
$activeItem = Get-Item -LiteralPath $activeFile -Force -ErrorAction SilentlyContinue
if ($activeItem) {
if ($activeItem.PSIsContainer -or
(($activeItem.Attributes -band [IO.FileAttributes]::ReparsePoint) -ne 0)) {
if ($activeItem.PSIsContainer -or (Test-LinkedDirectory $activeItem)) {
exit 0
}
# Get-Content -Raw returns $null for a zero-byte pointer; an empty pointer
@@ -198,7 +221,7 @@ if ($activeItem) {
$planId = "$(Get-Content -LiteralPath $activeFile -Raw -ErrorAction SilentlyContinue)".Trim()
if ($planId -and (Test-ValidSlug $planId)) {
$candidate = Join-Path $PlanRoot $planId
if ((Test-Path -LiteralPath $candidate -PathType Container) -and (Test-WithinRoot $candidate)) {
if ((Test-Path -LiteralPath $candidate -PathType Container) -and -not (Test-LinkedDirectory $candidate) -and (Test-WithinRoot $candidate)) {
Write-Output $candidate
exit 0
}
@@ -211,6 +234,7 @@ if ($activeItem) {
if (Test-Path -LiteralPath $PlanRoot -PathType Container) {
$latest = Get-ChildItem -LiteralPath $PlanRoot -Directory |
Where-Object { -not $_.Name.StartsWith('.') } |
Where-Object { -not (Test-LinkedDirectory $_) } |
Where-Object { Test-ValidSlug $_.Name } |
Where-Object { Test-Path -LiteralPath (Join-Path $_.FullName "task_plan.md") -PathType Leaf } |
Where-Object { Test-WithinRoot $_.FullName } |
@@ -246,10 +246,16 @@ mtime_of() {
printf "0\n"
}
# A linked plan directory (symlink or junction; `-L` sees both under Git
# Bash) is never selectable: not by PLAN_ID, not by the pointer, not by the
# newest-mtime scan, and it never counts below (#270). Containment alone let
# a link that stays inside the root be selected while the counter skipped
# it, so one real plan plus a newer linked one became an mtime guess again.
resolve_from_env() {
plan_id="${PLAN_ID:-}"
slug_is_valid "${plan_id}" || return 1
candidate="${PLAN_ROOT}/${plan_id}"
[ -L "${candidate}" ] && return 1
if [ -d "${candidate}" ] && is_within_root "${candidate}"; then
printf "%s\n" "${candidate}"
return 0
@@ -268,6 +274,7 @@ resolve_from_active_file() {
esac
slug_is_valid "${plan_id}" || return 1
candidate="${PLAN_ROOT}/${plan_id}"
[ -L "${candidate}" ] && return 1
if [ -d "${candidate}" ] && is_within_root "${candidate}"; then
printf "%s\n" "${candidate}"
return 0
@@ -288,6 +295,7 @@ resolve_latest_dir() {
case "${name}" in
.*) continue ;;
esac
[ -L "${clean}" ] && continue
slug_is_valid "${name}" || continue
[ -f "${clean}/task_plan.md" ] || continue
is_within_root "${clean}" || continue
@@ -338,8 +346,9 @@ if [ -z "${PLAN_ID:-}" ]; then
PLAN_COUNT=1
fi
for plan_candidate in "${PLAN_ROOT}"/*/task_plan.md; do
[ -f "$plan_candidate" ] || continue
plan_candidate_dir="${plan_candidate%/task_plan.md}"
[ -L "$plan_candidate_dir" ] && continue
[ -f "$plan_candidate" ] || continue
slug_is_valid "${plan_candidate_dir##*/}" || continue
PLAN_COUNT=$((PLAN_COUNT + 1))
if [ "$PLAN_COUNT" -gt 1 ]; then PLAN_AMBIGUOUS=1; break; fi
@@ -468,13 +468,16 @@ def _opencode_state_annotation(state: Any) -> str:
def _format_opencode_part(data: Dict[str, Any], session_id: str) -> Optional[Dict[str, Any]]:
"""Print-ready summary for one OpenCode part row."""
if not isinstance(data, dict):
return None
ptype = data.get('type')
short = safe_session_label(session_id)
if ptype == 'tool':
tool = (data.get('tool') or '').lower()
tool_value = data.get('tool')
tool = tool_value.lower() if isinstance(tool_value, str) else ''
state = data.get('state') or {}
input_ = state.get('input') if isinstance(state, dict) else None
input_ = input_ or {}
input_ = input_ if isinstance(input_, dict) else {}
outcome = _opencode_state_annotation(state)
if tool in ('write', 'edit'):
fp = input_.get('filePath', '')
@@ -486,7 +489,8 @@ def _format_opencode_part(data: Dict[str, Any], session_id: str) -> Optional[Dic
return {'session': short, 'summary': f"Tool bash: {cmd}{outcome}"}
return {'session': short, 'summary': f"Tool {tool}{outcome}"}
if ptype == 'text':
text = (data.get('text') or '')[:300]
text_value = data.get('text')
text = text_value[:300] if isinstance(text_value, str) else ''
if text.strip():
return {'session': short, 'summary': f"text: {text}"}
return None
@@ -577,6 +581,7 @@ def opencode_catchup(project_path: str, mode: str = 'no-history') -> None:
"""
SELECT time_created, data FROM part
WHERE session_id = ?
AND json_valid(data)
AND json_extract(data, '$.type') = 'tool'
AND lower(json_extract(data, '$.tool')) IN ('write', 'edit', 'patch')
AND (
@@ -121,9 +121,14 @@ function Test-SafeActiveFile {
param([switch]$AllowLink)
$item = Get-Item -LiteralPath $ActiveFile -Force -ErrorAction SilentlyContinue
if (-not $item) { return $false }
# Reading may follow a verified in-project link; writing must not.
# Reading may follow a verified in-project link; writing must not. A link
# is a symlink or junction by LinkType, never the bare ReparsePoint
# attribute: OneDrive Files On-Demand marks every synced file as a
# reparse point, and the pointer must stay writable there (#275).
$linked = ([string]$item.LinkType) -in @('SymbolicLink', 'Junction')
return -not $item.PSIsContainer -and
($AllowLink -or (($item.Attributes -band [IO.FileAttributes]::ReparsePoint) -eq 0)) -and
($AllowLink -or -not $linked) -and
($AllowLink -or -not $item.IsReadOnly) -and
(Test-WithinRoot $ActiveFile)
}
@@ -204,6 +209,8 @@ function Show-PlanList {
Write-Output "[active] marks the shared .active_plan pointer; listing does not bind this session."
$found = $false
foreach ($plan in (Get-ChildItem -LiteralPath $PlanRoot -Directory -ErrorAction SilentlyContinue | Sort-Object Name)) {
# A linked plan directory is never a plan (#270): no resolver selects it.
if (([string]$plan.LinkType) -in @('SymbolicLink', 'Junction')) { continue }
if (-not (Test-ValidSlug $plan.Name) -or -not (Test-WithinRoot $plan.FullName)) { continue }
$planFile = Join-Path $plan.FullName "task_plan.md"
if (-not (Test-Path -LiteralPath $planFile -PathType Leaf) -or -not (Test-WithinRoot $planFile)) { continue }
@@ -281,6 +288,11 @@ if (-not (Test-Path -LiteralPath $PlanDir -PathType Container)) {
Write-Error "Run: init-session.sh `"$PlanId`" to create it, or check .planning\ for available plans."
exit 1
}
$planDirItem = Get-Item -LiteralPath $PlanDir -Force -ErrorAction SilentlyContinue
if ($planDirItem -and (([string]$planDirItem.LinkType) -in @('SymbolicLink', 'Junction'))) {
Write-Error "Error: plan directory is a symlink or junction and no route selects it: $PlanDir"
exit 1
}
if (-not (Test-WithinRoot $PlanRoot) -or -not (Test-WithinRoot $PlanDir)) {
Write-Error "Error: plan directory must remain within the project."
exit 1
@@ -305,10 +317,23 @@ try {
$stream.Write($bytes, 0, $bytes.Length)
$stream.Flush()
} finally { $stream.Dispose() }
if ($activeItem) {
[IO.File]::Replace($tempFile, $ActiveFile, [NullString]::Value)
} else {
[IO.File]::Move($tempFile, $ActiveFile)
$maxAttempts = 20
for ($attempt = 1; $attempt -le $maxAttempts; $attempt++) {
try {
$currentActive = Get-Item -LiteralPath $ActiveFile -Force -ErrorAction SilentlyContinue
if ($currentActive) {
if (-not (Test-SafeActiveFile)) {
throw [InvalidOperationException]::new("the active plan pointer became unsafe during replacement")
}
[IO.File]::Replace($tempFile, $ActiveFile, [NullString]::Value)
} else {
[IO.File]::Move($tempFile, $ActiveFile)
}
break
} catch [IO.IOException] {
if ($attempt -eq $maxAttempts) { throw }
Start-Sleep -Milliseconds 25
}
}
} catch {
Write-Error "Error: could not set the active plan pointer: $($_.Exception.Message)"
@@ -272,6 +272,9 @@ list_plans() {
printf '%s\n' 'Available plans:'
for _dir in "${PLAN_ROOT}"/*; do
[ -d "${_dir}" ] || continue
# A linked plan directory is never a plan (#270): no resolver selects
# it, so listing it would advertise a PLAN_ID every route refuses.
[ -L "${_dir}" ] && continue
_id="${_dir##*/}"
slug_is_valid "${_id}" || continue
is_within_root "${_dir}" || continue
@@ -312,7 +315,7 @@ if [ "${1:-}" = '' ]; then
exit 1
fi
plan_id="$(current_active)"
if [ -n "${plan_id}" ] && [ -d "${PLAN_ROOT}/${plan_id}" ] && is_within_root "${PLAN_ROOT}/${plan_id}"; then
if [ -n "${plan_id}" ] && [ -d "${PLAN_ROOT}/${plan_id}" ] && [ ! -L "${PLAN_ROOT}/${plan_id}" ] && is_within_root "${PLAN_ROOT}/${plan_id}"; then
printf '%s\n' "Active plan: ${plan_id}" "Path: ${PLAN_ROOT}/${plan_id}"
elif [ -n "${plan_id}" ]; then
printf '%s\n' "Active plan pointer: ${plan_id} (directory not found or outside project - stale pointer)"
@@ -333,6 +336,10 @@ if [ ! -d "${PLAN_DIR}" ]; then
"Run: init-session.sh \"${PLAN_ID}\" to create it, or use --list to see available plans." >&2
exit 1
fi
if [ -L "${PLAN_DIR}" ]; then
printf '%s\n' "Error: plan directory is a symlink or junction and no route selects it: ${PLAN_DIR}" >&2
exit 1
fi
if ! is_within_root "${PLAN_ROOT}" || ! is_within_root "${PLAN_DIR}"; then
printf '%s\n' 'Error: plan directory is outside the project or cannot be verified.' >&2
exit 1
@@ -8,6 +8,12 @@ State the analytical question or intended deliverable in one clear sentence.
[One sentence describing the analytical objective]
## Next Step
Record the single analytical action that should happen next. Update it whenever the active phase or immediate action changes.
[The single next analytical action. Update whenever phase status changes.]
## Current Phase
Name the phase currently being worked on.
@@ -76,6 +82,6 @@ Record each distinct error, the attempt number, and the resolution. Change the a
## Notes
- Update phase status as work progresses: `pending` to `in_progress` to `complete`.
- Re-read the goal and current phase before major analytical decisions.
- Re-read the goal, next step, and current phase before major analytical decisions.
- Log errors promptly so failed approaches are not repeated.
- Record query results and visual evidence in findings.md.
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "planning-with-files",
"version": "3.20.0",
"version": "3.20.7",
"description": "Persistent project planning for Codex. Opt-in lifecycle hooks inject selected plan context; automatic recovery uses project files only. Explicit catchup modes may read same-project local session records to emit aggregate counts or bounded nonce-framed excerpts. Optional gated mode can request continuation on capable hosts and never runs Markdown-declared commands. No network upload path.",
"author": {
"name": "OthmanAdi",
+25
View File
@@ -90,6 +90,27 @@ def _is_reparse_or_link(path: Path) -> bool:
return bool(attrs & reparse)
_LINK_REPARSE_TAGS = (0xA000000C, 0xA0000003) # IO_REPARSE_TAG_SYMLINK, _MOUNT_POINT
def _is_linked_directory(path: Path) -> bool:
"""`[ -L ]` of the shell scripts: a symlink, or a junction on Windows.
Narrower than _is_reparse_or_link on purpose: OneDrive Files On-Demand
marks every synced directory as a reparse point, and those are plans.
"""
try:
info = path.lstat()
except OSError:
return False
if stat.S_ISLNK(info.st_mode):
return True
reparse = getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0x400)
if getattr(info, "st_file_attributes", 0) & reparse:
return getattr(info, "st_reparse_tag", 0) in _LINK_REPARSE_TAGS
return False
def _is_trusted_darwin_system_alias(path: Path) -> bool:
"""Admit only macOS's fixed root aliases after verifying their targets."""
if sys.platform != "darwin":
@@ -243,6 +264,10 @@ def session_plan_requires_binding(root: Path) -> bool:
for child in planning_dir.iterdir():
if not _PLAN_SLUG.fullmatch(child.name) or not child.is_dir():
continue
# A linked plan directory is not selectable and never counts,
# matching `[ -L ]` in the shell counters (#270).
if _is_linked_directory(child):
continue
if (child / "task_plan.md").is_file():
candidates += 1
if candidates > 1:
+1 -1
View File
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/skill-hook.sh\" \"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\" \"$HOME/.codex/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
metadata:
version: "3.20.0"
version: "3.20.7"
---
@@ -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.");
@@ -18,6 +18,27 @@ param(
[switch]$Gated
)
# Windows PowerShell 5.1 can silently relocate a -File invocation when the
# inherited cwd contains wildcard characters such as [ or ]. Recover the
# physical cwd for a direct invocation before any project-relative paths are
# resolved.
if ($PSVersionTable.PSVersion.Major -eq 5 -and
[System.Management.Automation.WildcardPattern]::ContainsWildcardCharacters([Environment]::CurrentDirectory)) {
$processArgs = [Environment]::GetCommandLineArgs()
for ($index = 0; $index -lt ($processArgs.Length - 1); $index++) {
if ($processArgs[$index] -ieq '-File') {
$entryScript = $processArgs[$index + 1]
if (-not [IO.Path]::IsPathRooted($entryScript)) {
$entryScript = Join-Path ([Environment]::CurrentDirectory) $entryScript
}
if ([IO.Path]::GetFullPath($entryScript) -eq [IO.Path]::GetFullPath($PSCommandPath)) {
Set-Location -LiteralPath ([Environment]::CurrentDirectory)
}
break
}
}
}
$DATE = Get-Date -Format "yyyy-MM-dd"
# Resolve v3 opt-in mode. -Gated implies autonomous and is the stronger marker.
@@ -80,6 +101,26 @@ function Get-InheritedMode([string]$CurrentMode) {
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") {
Write-Host "Unknown template: $Template (available: default, analytics). Using default."
@@ -136,20 +177,7 @@ if ($UsePlanDir) {
$Counter++
}
$TargetDir = Join-Path $PlanningRoot $PlanId
New-Item -ItemType Directory -Path $TargetDir -Force | Out-Null
# Reuse the selector's contained, atomic pointer replacement. Set-Content
# would follow a reparse point and truncate a hardlinked pointer in place,
# overwriting whichever file shares that inode.
$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
}
New-Item -ItemType Directory -Path $TargetDir -Force -ErrorAction Stop | Out-Null
$Mode = Get-InheritedMode $Mode
} else {
$TargetDir = (Get-Location).Path
@@ -173,11 +201,12 @@ if ($UsePlanDir) {
Write-Host "PLAN_ID=$PlanId"
}
try {
# Create task_plan.md if it doesn't exist
if (-not (Test-Path -LiteralPath $TaskPlanPath)) {
$AnalyticsPlan = Join-Path $TemplateDir "analytics_task_plan.md"
if ($Template -eq "analytics" -and (Test-Path $AnalyticsPlan)) {
Copy-Item -LiteralPath $AnalyticsPlan -Destination $TaskPlanPath
Copy-Item -LiteralPath $AnalyticsPlan -Destination $TaskPlanPath -ErrorAction Stop
} else {
@"
# Task Plan: [Brief Description]
@@ -226,7 +255,7 @@ Phase 1
## Errors Encountered
| Error | Resolution |
|-------|------------|
"@ | Out-File -LiteralPath $TaskPlanPath -Encoding UTF8
"@ | Out-File -LiteralPath $TaskPlanPath -Encoding UTF8 -ErrorAction Stop
}
Write-Host "Created $TaskPlanDisplay"
} else {
@@ -237,7 +266,7 @@ Phase 1
if (-not (Test-Path -LiteralPath $FindingsPath)) {
$AnalyticsFindings = Join-Path $TemplateDir "analytics_findings.md"
if ($Template -eq "analytics" -and (Test-Path $AnalyticsFindings)) {
Copy-Item -LiteralPath $AnalyticsFindings -Destination $FindingsPath
Copy-Item -LiteralPath $AnalyticsFindings -Destination $FindingsPath -ErrorAction Stop
} else {
@"
# Findings & Decisions
@@ -258,7 +287,7 @@ if (-not (Test-Path -LiteralPath $FindingsPath)) {
## Resources
-
"@ | Out-File -LiteralPath $FindingsPath -Encoding UTF8
"@ | Out-File -LiteralPath $FindingsPath -Encoding UTF8 -ErrorAction Stop
}
Write-Host "Created $FindingsDisplay"
} else {
@@ -287,7 +316,7 @@ if (-not (Test-Path -LiteralPath $ProgressPath)) {
### Errors
| Error | Resolution |
|-------|------------|
"@ | Out-File -LiteralPath $ProgressPath -Encoding UTF8
"@ | Out-File -LiteralPath $ProgressPath -Encoding UTF8 -ErrorAction Stop
} else {
@"
# Progress Log
@@ -308,12 +337,56 @@ if (-not (Test-Path -LiteralPath $ProgressPath)) {
### Errors
| Error | Resolution |
|-------|------------|
"@ | Out-File -LiteralPath $ProgressPath -Encoding UTF8
"@ | Out-File -LiteralPath $ProgressPath -Encoding UTF8 -ErrorAction Stop
}
Write-Host "Created $ProgressDisplay"
} else {
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.
$pointerSet = $false
for ($attempt = 1; $attempt -le 5; $attempt++) {
$global:LASTEXITCODE = 0
try {
$selectorResult = & $PlanSelector $PlanId 2>&1
} catch {
$selectorResult = $_
$global:LASTEXITCODE = 1
}
if ($LASTEXITCODE -eq 0) {
$pointerSet = $true
break
}
# Another writer can replace the pointer between the selector's
# Get-Item and final-path check. Retry only that transient result.
$transientPointerRace = $selectorResult -is [System.Management.Automation.ErrorRecord] -and
$selectorResult.Exception.Message -ceq
'Error: could not set the active plan pointer: the active plan pointer became unsafe during replacement'
if ($attempt -eq 5 -or -not $transientPointerRace) {
break
}
Start-Sleep -Milliseconds 50
$global:LASTEXITCODE = 0
try {
& $PlanSelector -VerifyRoot *> $null
} catch {
$global:LASTEXITCODE = 1
}
if ($LASTEXITCODE -ne 0) { break }
}
if (-not $pointerSet) {
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!"
@@ -350,42 +423,94 @@ if ($Mode -ne "") {
# (c) auto-attest (attestation default-on in v3 modes, security strand rec 1).
# attest-plan.ps1 intentionally refuses non-Windows hosts because its secure
# no-follow implementation uses Win32 handles. On Unix, use the POSIX
# attester instead. Bind slug mode to the plan we just created so an
# inherited PLAN_ID cannot redirect attestation to another plan.
# 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 $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 {
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) {
$AttestPs1 = Join-Path $ScriptDir "attest-plan.ps1"
if (Test-Path -LiteralPath $AttestPs1) {
& $AttestPs1 *> $null
$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 {
$AttestSh = Join-Path $ScriptDir "attest-plan.sh"
$AttestationCommand = "attest-plan.sh"
$AttestSh = Join-Path $ScriptDir $AttestationCommand
$Sh = Get-Command sh -ErrorAction SilentlyContinue
if ($Sh -and (Test-Path -LiteralPath $AttestSh)) {
& $Sh.Path $AttestSh *> $null
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)"
}
}
@@ -103,6 +103,7 @@ slugify() {
# Lowercase, non-alphanumerics → '-', collapse repeats, trim leading/trailing '-'
printf '%s' "$1" \
| tr '[:upper:]' '[:lower:]' \
| tr '\r\n' '--' \
| sed -e 's/[^a-z0-9]/-/g' -e 's/-\{2,\}/-/g' -e 's/^-//' -e 's/-$//' \
| cut -c1-40
}
@@ -185,6 +186,10 @@ apply_v3_mode() {
_mode_plan="$2"
[ -z "$MODE" ] && return 0
ATTESTATION_OK=0
ATTESTATION_COMMAND="attest-plan.sh"
ATTESTATION_REASON="task_plan.md was not available for attestation"
# (a) reset the gate block counter and drop any stale gate ledger so a prior
# run's high block count cannot let the next run stop instantly.
printf '0\n' > "${_mode_dir}/.stop_blocks"
@@ -202,12 +207,61 @@ apply_v3_mode() {
# (c) auto-attest the plan (attestation default-on in v3 modes, security
# strand rec 1). attest-plan.sh resolves the same way init-session just
# pinned things: in slug mode PLAN_ID points at this plan dir; in legacy
# mode it is empty and the script falls back to ./task_plan.md at root.
# Run from the project root (CWD here) so both resolutions land.
_attest="${SCRIPT_DIR}/attest-plan.sh"
if [ -f "${_attest}" ] && [ -f "${_mode_plan}" ]; then
PLAN_ID="${PLAN_ID:-}" sh "${_attest}" >/dev/null 2>&1 || true
# pinned things. Slug mode binds both selectors to the plan that was
# just created, so an inherited PWF_PLAN_ROOT or PLAN_ID 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. Run from the project root (CWD here) so both
# resolutions land.
_attest="${SCRIPT_DIR}/${ATTESTATION_COMMAND}"
if [ ! -f "${_attest}" ]; then
ATTESTATION_REASON="${ATTESTATION_COMMAND} was not found beside init-session.sh"
return 0
fi
if [ ! -f "${_mode_plan}" ]; then
return 0
fi
if [ "$SLUG_MODE" -eq 1 ]; then
if _attest_output="$(PWF_PLAN_ROOT="$PWD" PLAN_ID="${PLAN_ID}" sh "${_attest}" 2>&1)"; then
ATTESTATION_OK=1
ATTESTATION_REASON=""
return 0
else
_attest_rc=$?
fi
else
if _attest_output="$(PWF_PLAN_ROOT="" PLAN_ID="" sh "${_attest}" 2>&1)"; then
ATTESTATION_OK=1
ATTESTATION_REASON=""
return 0
else
_attest_rc=$?
fi
fi
_attest_reason="$(
printf '%s\n' "${_attest_output}" |
sed -n '/[^[:space:]]/ { s/[[:space:]][[:space:]]*/ /g; s/^ //; s/ $//; p; q; }' |
cut -c1-300
)"
if [ -n "${_attest_reason}" ]; then
ATTESTATION_REASON="${_attest_reason}"
else
ATTESTATION_REASON="${ATTESTATION_COMMAND} exited with code ${_attest_rc}"
fi
return 0
}
print_v3_mode_status() {
_status_dir="$1"
_marker="$(cat "${_status_dir}/.mode")"
if [ "${ATTESTATION_OK:-0}" -eq 1 ]; then
printf 'Mode: %s (attested, gate counter reset)\n' "${_marker}"
else
printf 'Mode: %s (NOT attested: %s; run %s before the first hook fire)\n' \
"${_marker}" "${ATTESTATION_REASON:-attestation failed}" "${ATTESTATION_COMMAND:-attest-plan.sh}"
fi
}
@@ -422,7 +476,7 @@ if [ "$SLUG_MODE" -eq 1 ]; then
echo "Pin this terminal to the plan for parallel sessions:"
echo " export PLAN_ID=$PLAN_ID"
if [ -n "$MODE" ]; then
echo "Mode: $(cat "${PLAN_DIR}/.mode") (attested, gate counter reset)"
print_v3_mode_status "${PLAN_DIR}"
fi
else
PROJECT_NAME="${PROJECT_NAME:-project}"
@@ -433,6 +487,6 @@ else
echo "Planning files initialized!"
echo "Files: task_plan.md, findings.md, progress.md"
if [ -n "$MODE" ]; then
echo "Mode: $(cat "$(pwd)/.mode") (attested, gate counter reset)"
print_v3_mode_status "$(pwd)"
fi
fi
@@ -845,7 +845,10 @@ class Injector(object):
)
raise Bail()
if plan_id:
if slug_is_valid(plan_id) and is_dir(plan_prefix + ".planning/" + plan_id):
# A linked plan directory is never selectable (#270): the same
# `[ ! -L ]` the reference applies on every branch below.
if (slug_is_valid(plan_id) and is_dir(plan_prefix + ".planning/" + plan_id)
and not is_link(plan_prefix + ".planning/" + plan_id)):
resolved = plan_prefix + ".planning/" + plan_id
scope = "scoped"
explicit = True
@@ -864,7 +867,7 @@ class Injector(object):
active = b""
if active and slug_is_valid(active):
slug = active.decode("ascii")
if is_dir(plan_prefix + ".planning/" + slug):
if is_dir(plan_prefix + ".planning/" + slug) and not is_link(plan_prefix + ".planning/" + slug):
resolved = plan_prefix + ".planning/" + slug
scope = "scoped"
if not resolved and is_dir(plan_prefix + ".planning"):
@@ -880,6 +883,8 @@ class Injector(object):
candidate = plan_prefix + ".planning/" + name
if not is_dir(candidate):
continue
if is_link(candidate):
continue
if not slug_is_valid(name):
continue
if not is_file(candidate + "/task_plan.md"):
@@ -1327,7 +1332,12 @@ def plan_is_ambiguous(plan_root, project_root, plan_id=""):
except OSError:
names = []
for name in names:
if slug_is_valid(name) and is_file(plan_root + "/" + name + "/task_plan.md"):
candidate_dir = plan_root + "/" + name
# A linked plan directory is not selectable, so it never counts (#270):
# the reference tests `[ -L "$plan_candidate_dir" ]` before `-f`.
if is_link(candidate_dir):
continue
if slug_is_valid(name) and is_file(candidate_dir + "/task_plan.md"):
count += 1
if count > 1:
return True
@@ -1364,7 +1374,7 @@ def resolve_plan_dir(env=None):
if plan_id:
if slug_is_valid(plan_id):
candidate = fs_root + "/" + plan_id
if is_dir(candidate) and within(candidate):
if is_dir(candidate) and not is_link(candidate) and within(candidate):
return found(plan_id)
return ("", "")
@@ -1382,7 +1392,7 @@ def resolve_plan_dir(env=None):
if slug_is_valid(active):
slug = active.decode("ascii")
candidate = fs_root + "/" + slug
if is_dir(candidate) and within(candidate):
if is_dir(candidate) and not is_link(candidate) and within(candidate):
return found(slug)
if is_dir(fs_root):
@@ -1398,6 +1408,8 @@ def resolve_plan_dir(env=None):
continue
if name.startswith("."):
continue
if is_link(candidate):
continue
if not slug_is_valid(name):
continue
if not is_file(candidate + "/task_plan.md"):
@@ -263,8 +263,9 @@ if [ -z "${PLAN_ID:-}" ]; then
PLAN_COUNT=1
fi
for plan_candidate in "${PLAN_PREFIX}".planning/*/task_plan.md; do
[ -f "$plan_candidate" ] || continue
plan_candidate_dir="${plan_candidate%/task_plan.md}"
[ -L "$plan_candidate_dir" ] && continue
[ -f "$plan_candidate" ] || continue
slug_is_valid "${plan_candidate_dir##*/}" || continue
PLAN_COUNT=$((PLAN_COUNT + 1))
if [ "$PLAN_COUNT" -gt 1 ]; then PLAN_AMBIGUOUS=1; break; fi
@@ -295,7 +296,9 @@ if [ -n "${PLAN_ID:-}" ]; then
# printing on those would spam the transcript with the same line. The
# userprompt fire is also the one plan-doctor.sh drives, so /plan-doctor
# still sees and reports the state.
if slug_is_valid "$PLAN_ID" && [ -d "${PLAN_PREFIX}.planning/${PLAN_ID}" ]; then
# A linked plan directory is never selectable (#270): same `-L` rule as
# the counter above and as resolve-plan-dir.sh, on every branch below.
if slug_is_valid "$PLAN_ID" && [ -d "${PLAN_PREFIX}.planning/${PLAN_ID}" ] && [ ! -L "${PLAN_PREFIX}.planning/${PLAN_ID}" ]; then
RESOLVED="${PLAN_PREFIX}.planning/${PLAN_ID}"; SCOPE="scoped"; EXPLICIT=1
else
if [ "$CONTEXT" = "userprompt" ]; then
@@ -305,7 +308,7 @@ if [ -n "${PLAN_ID:-}" ]; then
fi
elif [ -f "${PLAN_PREFIX}.planning/.active_plan" ]; then
AP=$(tr -d '\r\n[:space:]' < "${PLAN_PREFIX}.planning/.active_plan" 2>/dev/null)
if [ -n "$AP" ] && slug_is_valid "$AP" && [ -d "${PLAN_PREFIX}.planning/${AP}" ]; then
if [ -n "$AP" ] && slug_is_valid "$AP" && [ -d "${PLAN_PREFIX}.planning/${AP}" ] && [ ! -L "${PLAN_PREFIX}.planning/${AP}" ]; then
RESOLVED="${PLAN_PREFIX}.planning/${AP}"; SCOPE="scoped"
fi
fi
@@ -314,6 +317,7 @@ if [ -z "$RESOLVED" ] && [ -d "${PLAN_PREFIX}.planning" ]; then
for d in "${PLAN_PREFIX}".planning/*/; do
d="${d%/}"; n="${d##*/}"
case "$n" in .*) continue;; esac
[ -L "$d" ] && continue
slug_is_valid "$n" || continue
[ -f "$d/task_plan.md" ] || continue
m=$(stat -c '%Y' "$d" 2>/dev/null || stat -f '%m' "$d" 2>/dev/null || date -r "$d" +%s 2>/dev/null || echo 0)
@@ -139,6 +139,24 @@ function Test-WithinRoot {
return $candNorm.StartsWith($rootNorm + [System.IO.Path]::DirectorySeparatorChar, [System.StringComparison]::OrdinalIgnoreCase)
}
# A linked plan directory (symlink or junction) is never selectable: not by
# PLAN_ID, not by the pointer, not by the newest scan, and it never counts
# (#270). This is `[ -L ]` of resolve-plan-dir.sh and is_link of the Python
# twin: LinkType names symlinks and junctions only. The ReparsePoint
# attribute alone would also match OneDrive Files On-Demand placeholders,
# which every synced directory and file carries and which are not links to
# sh. The same predicate guards the pointer file below (#275).
function Test-LinkedDirectory {
param($PathOrItem)
if ($PathOrItem -is [string]) {
$item = Get-Item -LiteralPath $PathOrItem -Force -ErrorAction SilentlyContinue
} else {
$item = $PathOrItem
}
if (-not $item) { return $false }
return ([string]$item.LinkType) -in @('SymbolicLink', 'Junction')
}
$activeFile = Join-Path $PlanRoot ".active_plan"
# A set PLAN_ID is a BINDING, not a hint (issue #237). A selector that names
@@ -158,6 +176,9 @@ if (-not $env:PLAN_ID) {
}
if (Test-Path -LiteralPath $PlanRoot -PathType Container) {
foreach ($entry in (Get-ChildItem -LiteralPath $PlanRoot -Directory -ErrorAction SilentlyContinue)) {
# A linked plan directory (symlink, junction) is not selectable and
# never counts, matching `[ -L ]` in resolve-plan-dir.sh (#270).
if (Test-LinkedDirectory $entry) { continue }
if ((Test-ValidSlug $entry.Name) -and
(Test-Path -LiteralPath (Join-Path $entry.FullName "task_plan.md") -PathType Leaf)) {
$planCount++
@@ -175,7 +196,7 @@ if ($planCount -gt 1) { exit 0 }
if ($env:PLAN_ID) {
if (Test-ValidSlug $env:PLAN_ID) {
$candidate = Join-Path $PlanRoot $env:PLAN_ID
if ((Test-Path -LiteralPath $candidate -PathType Container) -and (Test-WithinRoot $candidate)) {
if ((Test-Path -LiteralPath $candidate -PathType Container) -and -not (Test-LinkedDirectory $candidate) -and (Test-WithinRoot $candidate)) {
Write-Output $candidate
exit 0
}
@@ -185,12 +206,14 @@ if ($env:PLAN_ID) {
# Get-Item observes the link object even when its target is missing, unlike
# Test-Path which follows the target. An active pointer that is a directory or
# reparse point is an unsafe/ambiguous selector and must terminate resolution;
# a symlink is an unsafe/ambiguous selector and must terminate resolution;
# falling through would silently select and expose the newest unrelated plan.
# LinkType, not the ReparsePoint attribute: OneDrive Files On-Demand marks
# every synced file as a reparse point, and such a pointer is a plain file
# to every other route (#275).
$activeItem = Get-Item -LiteralPath $activeFile -Force -ErrorAction SilentlyContinue
if ($activeItem) {
if ($activeItem.PSIsContainer -or
(($activeItem.Attributes -band [IO.FileAttributes]::ReparsePoint) -ne 0)) {
if ($activeItem.PSIsContainer -or (Test-LinkedDirectory $activeItem)) {
exit 0
}
# Get-Content -Raw returns $null for a zero-byte pointer; an empty pointer
@@ -198,7 +221,7 @@ if ($activeItem) {
$planId = "$(Get-Content -LiteralPath $activeFile -Raw -ErrorAction SilentlyContinue)".Trim()
if ($planId -and (Test-ValidSlug $planId)) {
$candidate = Join-Path $PlanRoot $planId
if ((Test-Path -LiteralPath $candidate -PathType Container) -and (Test-WithinRoot $candidate)) {
if ((Test-Path -LiteralPath $candidate -PathType Container) -and -not (Test-LinkedDirectory $candidate) -and (Test-WithinRoot $candidate)) {
Write-Output $candidate
exit 0
}
@@ -211,6 +234,7 @@ if ($activeItem) {
if (Test-Path -LiteralPath $PlanRoot -PathType Container) {
$latest = Get-ChildItem -LiteralPath $PlanRoot -Directory |
Where-Object { -not $_.Name.StartsWith('.') } |
Where-Object { -not (Test-LinkedDirectory $_) } |
Where-Object { Test-ValidSlug $_.Name } |
Where-Object { Test-Path -LiteralPath (Join-Path $_.FullName "task_plan.md") -PathType Leaf } |
Where-Object { Test-WithinRoot $_.FullName } |
@@ -246,10 +246,16 @@ mtime_of() {
printf "0\n"
}
# A linked plan directory (symlink or junction; `-L` sees both under Git
# Bash) is never selectable: not by PLAN_ID, not by the pointer, not by the
# newest-mtime scan, and it never counts below (#270). Containment alone let
# a link that stays inside the root be selected while the counter skipped
# it, so one real plan plus a newer linked one became an mtime guess again.
resolve_from_env() {
plan_id="${PLAN_ID:-}"
slug_is_valid "${plan_id}" || return 1
candidate="${PLAN_ROOT}/${plan_id}"
[ -L "${candidate}" ] && return 1
if [ -d "${candidate}" ] && is_within_root "${candidate}"; then
printf "%s\n" "${candidate}"
return 0
@@ -268,6 +274,7 @@ resolve_from_active_file() {
esac
slug_is_valid "${plan_id}" || return 1
candidate="${PLAN_ROOT}/${plan_id}"
[ -L "${candidate}" ] && return 1
if [ -d "${candidate}" ] && is_within_root "${candidate}"; then
printf "%s\n" "${candidate}"
return 0
@@ -288,6 +295,7 @@ resolve_latest_dir() {
case "${name}" in
.*) continue ;;
esac
[ -L "${clean}" ] && continue
slug_is_valid "${name}" || continue
[ -f "${clean}/task_plan.md" ] || continue
is_within_root "${clean}" || continue
@@ -338,8 +346,9 @@ if [ -z "${PLAN_ID:-}" ]; then
PLAN_COUNT=1
fi
for plan_candidate in "${PLAN_ROOT}"/*/task_plan.md; do
[ -f "$plan_candidate" ] || continue
plan_candidate_dir="${plan_candidate%/task_plan.md}"
[ -L "$plan_candidate_dir" ] && continue
[ -f "$plan_candidate" ] || continue
slug_is_valid "${plan_candidate_dir##*/}" || continue
PLAN_COUNT=$((PLAN_COUNT + 1))
if [ "$PLAN_COUNT" -gt 1 ]; then PLAN_AMBIGUOUS=1; break; fi
@@ -468,13 +468,16 @@ def _opencode_state_annotation(state: Any) -> str:
def _format_opencode_part(data: Dict[str, Any], session_id: str) -> Optional[Dict[str, Any]]:
"""Print-ready summary for one OpenCode part row."""
if not isinstance(data, dict):
return None
ptype = data.get('type')
short = safe_session_label(session_id)
if ptype == 'tool':
tool = (data.get('tool') or '').lower()
tool_value = data.get('tool')
tool = tool_value.lower() if isinstance(tool_value, str) else ''
state = data.get('state') or {}
input_ = state.get('input') if isinstance(state, dict) else None
input_ = input_ or {}
input_ = input_ if isinstance(input_, dict) else {}
outcome = _opencode_state_annotation(state)
if tool in ('write', 'edit'):
fp = input_.get('filePath', '')
@@ -486,7 +489,8 @@ def _format_opencode_part(data: Dict[str, Any], session_id: str) -> Optional[Dic
return {'session': short, 'summary': f"Tool bash: {cmd}{outcome}"}
return {'session': short, 'summary': f"Tool {tool}{outcome}"}
if ptype == 'text':
text = (data.get('text') or '')[:300]
text_value = data.get('text')
text = text_value[:300] if isinstance(text_value, str) else ''
if text.strip():
return {'session': short, 'summary': f"text: {text}"}
return None
@@ -577,6 +581,7 @@ def opencode_catchup(project_path: str, mode: str = 'no-history') -> None:
"""
SELECT time_created, data FROM part
WHERE session_id = ?
AND json_valid(data)
AND json_extract(data, '$.type') = 'tool'
AND lower(json_extract(data, '$.tool')) IN ('write', 'edit', 'patch')
AND (
@@ -121,9 +121,14 @@ function Test-SafeActiveFile {
param([switch]$AllowLink)
$item = Get-Item -LiteralPath $ActiveFile -Force -ErrorAction SilentlyContinue
if (-not $item) { return $false }
# Reading may follow a verified in-project link; writing must not.
# Reading may follow a verified in-project link; writing must not. A link
# is a symlink or junction by LinkType, never the bare ReparsePoint
# attribute: OneDrive Files On-Demand marks every synced file as a
# reparse point, and the pointer must stay writable there (#275).
$linked = ([string]$item.LinkType) -in @('SymbolicLink', 'Junction')
return -not $item.PSIsContainer -and
($AllowLink -or (($item.Attributes -band [IO.FileAttributes]::ReparsePoint) -eq 0)) -and
($AllowLink -or -not $linked) -and
($AllowLink -or -not $item.IsReadOnly) -and
(Test-WithinRoot $ActiveFile)
}
@@ -204,6 +209,8 @@ function Show-PlanList {
Write-Output "[active] marks the shared .active_plan pointer; listing does not bind this session."
$found = $false
foreach ($plan in (Get-ChildItem -LiteralPath $PlanRoot -Directory -ErrorAction SilentlyContinue | Sort-Object Name)) {
# A linked plan directory is never a plan (#270): no resolver selects it.
if (([string]$plan.LinkType) -in @('SymbolicLink', 'Junction')) { continue }
if (-not (Test-ValidSlug $plan.Name) -or -not (Test-WithinRoot $plan.FullName)) { continue }
$planFile = Join-Path $plan.FullName "task_plan.md"
if (-not (Test-Path -LiteralPath $planFile -PathType Leaf) -or -not (Test-WithinRoot $planFile)) { continue }
@@ -281,6 +288,11 @@ if (-not (Test-Path -LiteralPath $PlanDir -PathType Container)) {
Write-Error "Run: init-session.sh `"$PlanId`" to create it, or check .planning\ for available plans."
exit 1
}
$planDirItem = Get-Item -LiteralPath $PlanDir -Force -ErrorAction SilentlyContinue
if ($planDirItem -and (([string]$planDirItem.LinkType) -in @('SymbolicLink', 'Junction'))) {
Write-Error "Error: plan directory is a symlink or junction and no route selects it: $PlanDir"
exit 1
}
if (-not (Test-WithinRoot $PlanRoot) -or -not (Test-WithinRoot $PlanDir)) {
Write-Error "Error: plan directory must remain within the project."
exit 1
@@ -305,10 +317,23 @@ try {
$stream.Write($bytes, 0, $bytes.Length)
$stream.Flush()
} finally { $stream.Dispose() }
if ($activeItem) {
[IO.File]::Replace($tempFile, $ActiveFile, [NullString]::Value)
} else {
[IO.File]::Move($tempFile, $ActiveFile)
$maxAttempts = 20
for ($attempt = 1; $attempt -le $maxAttempts; $attempt++) {
try {
$currentActive = Get-Item -LiteralPath $ActiveFile -Force -ErrorAction SilentlyContinue
if ($currentActive) {
if (-not (Test-SafeActiveFile)) {
throw [InvalidOperationException]::new("the active plan pointer became unsafe during replacement")
}
[IO.File]::Replace($tempFile, $ActiveFile, [NullString]::Value)
} else {
[IO.File]::Move($tempFile, $ActiveFile)
}
break
} catch [IO.IOException] {
if ($attempt -eq $maxAttempts) { throw }
Start-Sleep -Milliseconds 25
}
}
} catch {
Write-Error "Error: could not set the active plan pointer: $($_.Exception.Message)"
@@ -272,6 +272,9 @@ list_plans() {
printf '%s\n' 'Available plans:'
for _dir in "${PLAN_ROOT}"/*; do
[ -d "${_dir}" ] || continue
# A linked plan directory is never a plan (#270): no resolver selects
# it, so listing it would advertise a PLAN_ID every route refuses.
[ -L "${_dir}" ] && continue
_id="${_dir##*/}"
slug_is_valid "${_id}" || continue
is_within_root "${_dir}" || continue
@@ -312,7 +315,7 @@ if [ "${1:-}" = '' ]; then
exit 1
fi
plan_id="$(current_active)"
if [ -n "${plan_id}" ] && [ -d "${PLAN_ROOT}/${plan_id}" ] && is_within_root "${PLAN_ROOT}/${plan_id}"; then
if [ -n "${plan_id}" ] && [ -d "${PLAN_ROOT}/${plan_id}" ] && [ ! -L "${PLAN_ROOT}/${plan_id}" ] && is_within_root "${PLAN_ROOT}/${plan_id}"; then
printf '%s\n' "Active plan: ${plan_id}" "Path: ${PLAN_ROOT}/${plan_id}"
elif [ -n "${plan_id}" ]; then
printf '%s\n' "Active plan pointer: ${plan_id} (directory not found or outside project - stale pointer)"
@@ -333,6 +336,10 @@ if [ ! -d "${PLAN_DIR}" ]; then
"Run: init-session.sh \"${PLAN_ID}\" to create it, or use --list to see available plans." >&2
exit 1
fi
if [ -L "${PLAN_DIR}" ]; then
printf '%s\n' "Error: plan directory is a symlink or junction and no route selects it: ${PLAN_DIR}" >&2
exit 1
fi
if ! is_within_root "${PLAN_ROOT}" || ! is_within_root "${PLAN_DIR}"; then
printf '%s\n' 'Error: plan directory is outside the project or cannot be verified.' >&2
exit 1
@@ -8,6 +8,12 @@ State the analytical question or intended deliverable in one clear sentence.
[One sentence describing the analytical objective]
## Next Step
Record the single analytical action that should happen next. Update it whenever the active phase or immediate action changes.
[The single next analytical action. Update whenever phase status changes.]
## Current Phase
Name the phase currently being worked on.
@@ -76,6 +82,6 @@ Record each distinct error, the attempt number, and the resolution. Change the a
## Notes
- Update phase status as work progresses: `pending` to `in_progress` to `complete`.
- Re-read the goal and current phase before major analytical decisions.
- Re-read the goal, next step, and current phase before major analytical decisions.
- Log errors promptly so failed approaches are not repeated.
- Record query results and visual evidence in findings.md.
@@ -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.");
@@ -18,6 +18,27 @@ param(
[switch]$Gated
)
# Windows PowerShell 5.1 can silently relocate a -File invocation when the
# inherited cwd contains wildcard characters such as [ or ]. Recover the
# physical cwd for a direct invocation before any project-relative paths are
# resolved.
if ($PSVersionTable.PSVersion.Major -eq 5 -and
[System.Management.Automation.WildcardPattern]::ContainsWildcardCharacters([Environment]::CurrentDirectory)) {
$processArgs = [Environment]::GetCommandLineArgs()
for ($index = 0; $index -lt ($processArgs.Length - 1); $index++) {
if ($processArgs[$index] -ieq '-File') {
$entryScript = $processArgs[$index + 1]
if (-not [IO.Path]::IsPathRooted($entryScript)) {
$entryScript = Join-Path ([Environment]::CurrentDirectory) $entryScript
}
if ([IO.Path]::GetFullPath($entryScript) -eq [IO.Path]::GetFullPath($PSCommandPath)) {
Set-Location -LiteralPath ([Environment]::CurrentDirectory)
}
break
}
}
}
$DATE = Get-Date -Format "yyyy-MM-dd"
# Resolve v3 opt-in mode. -Gated implies autonomous and is the stronger marker.
@@ -80,6 +101,26 @@ function Get-InheritedMode([string]$CurrentMode) {
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") {
Write-Host "Unknown template: $Template (available: default, analytics). Using default."
@@ -136,20 +177,7 @@ if ($UsePlanDir) {
$Counter++
}
$TargetDir = Join-Path $PlanningRoot $PlanId
New-Item -ItemType Directory -Path $TargetDir -Force | Out-Null
# Reuse the selector's contained, atomic pointer replacement. Set-Content
# would follow a reparse point and truncate a hardlinked pointer in place,
# overwriting whichever file shares that inode.
$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
}
New-Item -ItemType Directory -Path $TargetDir -Force -ErrorAction Stop | Out-Null
$Mode = Get-InheritedMode $Mode
} else {
$TargetDir = (Get-Location).Path
@@ -173,11 +201,12 @@ if ($UsePlanDir) {
Write-Host "PLAN_ID=$PlanId"
}
try {
# Create task_plan.md if it doesn't exist
if (-not (Test-Path -LiteralPath $TaskPlanPath)) {
$AnalyticsPlan = Join-Path $TemplateDir "analytics_task_plan.md"
if ($Template -eq "analytics" -and (Test-Path $AnalyticsPlan)) {
Copy-Item -LiteralPath $AnalyticsPlan -Destination $TaskPlanPath
Copy-Item -LiteralPath $AnalyticsPlan -Destination $TaskPlanPath -ErrorAction Stop
} else {
@"
# Task Plan: [Brief Description]
@@ -226,7 +255,7 @@ Phase 1
## Errors Encountered
| Error | Resolution |
|-------|------------|
"@ | Out-File -LiteralPath $TaskPlanPath -Encoding UTF8
"@ | Out-File -LiteralPath $TaskPlanPath -Encoding UTF8 -ErrorAction Stop
}
Write-Host "Created $TaskPlanDisplay"
} else {
@@ -237,7 +266,7 @@ Phase 1
if (-not (Test-Path -LiteralPath $FindingsPath)) {
$AnalyticsFindings = Join-Path $TemplateDir "analytics_findings.md"
if ($Template -eq "analytics" -and (Test-Path $AnalyticsFindings)) {
Copy-Item -LiteralPath $AnalyticsFindings -Destination $FindingsPath
Copy-Item -LiteralPath $AnalyticsFindings -Destination $FindingsPath -ErrorAction Stop
} else {
@"
# Findings & Decisions
@@ -258,7 +287,7 @@ if (-not (Test-Path -LiteralPath $FindingsPath)) {
## Resources
-
"@ | Out-File -LiteralPath $FindingsPath -Encoding UTF8
"@ | Out-File -LiteralPath $FindingsPath -Encoding UTF8 -ErrorAction Stop
}
Write-Host "Created $FindingsDisplay"
} else {
@@ -287,7 +316,7 @@ if (-not (Test-Path -LiteralPath $ProgressPath)) {
### Errors
| Error | Resolution |
|-------|------------|
"@ | Out-File -LiteralPath $ProgressPath -Encoding UTF8
"@ | Out-File -LiteralPath $ProgressPath -Encoding UTF8 -ErrorAction Stop
} else {
@"
# Progress Log
@@ -308,12 +337,56 @@ if (-not (Test-Path -LiteralPath $ProgressPath)) {
### Errors
| Error | Resolution |
|-------|------------|
"@ | Out-File -LiteralPath $ProgressPath -Encoding UTF8
"@ | Out-File -LiteralPath $ProgressPath -Encoding UTF8 -ErrorAction Stop
}
Write-Host "Created $ProgressDisplay"
} else {
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.
$pointerSet = $false
for ($attempt = 1; $attempt -le 5; $attempt++) {
$global:LASTEXITCODE = 0
try {
$selectorResult = & $PlanSelector $PlanId 2>&1
} catch {
$selectorResult = $_
$global:LASTEXITCODE = 1
}
if ($LASTEXITCODE -eq 0) {
$pointerSet = $true
break
}
# Another writer can replace the pointer between the selector's
# Get-Item and final-path check. Retry only that transient result.
$transientPointerRace = $selectorResult -is [System.Management.Automation.ErrorRecord] -and
$selectorResult.Exception.Message -ceq
'Error: could not set the active plan pointer: the active plan pointer became unsafe during replacement'
if ($attempt -eq 5 -or -not $transientPointerRace) {
break
}
Start-Sleep -Milliseconds 50
$global:LASTEXITCODE = 0
try {
& $PlanSelector -VerifyRoot *> $null
} catch {
$global:LASTEXITCODE = 1
}
if ($LASTEXITCODE -ne 0) { break }
}
if (-not $pointerSet) {
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!"
@@ -350,42 +423,94 @@ if ($Mode -ne "") {
# (c) auto-attest (attestation default-on in v3 modes, security strand rec 1).
# attest-plan.ps1 intentionally refuses non-Windows hosts because its secure
# no-follow implementation uses Win32 handles. On Unix, use the POSIX
# attester instead. Bind slug mode to the plan we just created so an
# inherited PLAN_ID cannot redirect attestation to another plan.
# 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 $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 {
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) {
$AttestPs1 = Join-Path $ScriptDir "attest-plan.ps1"
if (Test-Path -LiteralPath $AttestPs1) {
& $AttestPs1 *> $null
$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 {
$AttestSh = Join-Path $ScriptDir "attest-plan.sh"
$AttestationCommand = "attest-plan.sh"
$AttestSh = Join-Path $ScriptDir $AttestationCommand
$Sh = Get-Command sh -ErrorAction SilentlyContinue
if ($Sh -and (Test-Path -LiteralPath $AttestSh)) {
& $Sh.Path $AttestSh *> $null
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)"
}
}
@@ -103,6 +103,7 @@ slugify() {
# Lowercase, non-alphanumerics → '-', collapse repeats, trim leading/trailing '-'
printf '%s' "$1" \
| tr '[:upper:]' '[:lower:]' \
| tr '\r\n' '--' \
| sed -e 's/[^a-z0-9]/-/g' -e 's/-\{2,\}/-/g' -e 's/^-//' -e 's/-$//' \
| cut -c1-40
}
@@ -185,6 +186,10 @@ apply_v3_mode() {
_mode_plan="$2"
[ -z "$MODE" ] && return 0
ATTESTATION_OK=0
ATTESTATION_COMMAND="attest-plan.sh"
ATTESTATION_REASON="task_plan.md was not available for attestation"
# (a) reset the gate block counter and drop any stale gate ledger so a prior
# run's high block count cannot let the next run stop instantly.
printf '0\n' > "${_mode_dir}/.stop_blocks"
@@ -202,12 +207,61 @@ apply_v3_mode() {
# (c) auto-attest the plan (attestation default-on in v3 modes, security
# strand rec 1). attest-plan.sh resolves the same way init-session just
# pinned things: in slug mode PLAN_ID points at this plan dir; in legacy
# mode it is empty and the script falls back to ./task_plan.md at root.
# Run from the project root (CWD here) so both resolutions land.
_attest="${SCRIPT_DIR}/attest-plan.sh"
if [ -f "${_attest}" ] && [ -f "${_mode_plan}" ]; then
PLAN_ID="${PLAN_ID:-}" sh "${_attest}" >/dev/null 2>&1 || true
# pinned things. Slug mode binds both selectors to the plan that was
# just created, so an inherited PWF_PLAN_ROOT or PLAN_ID 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. Run from the project root (CWD here) so both
# resolutions land.
_attest="${SCRIPT_DIR}/${ATTESTATION_COMMAND}"
if [ ! -f "${_attest}" ]; then
ATTESTATION_REASON="${ATTESTATION_COMMAND} was not found beside init-session.sh"
return 0
fi
if [ ! -f "${_mode_plan}" ]; then
return 0
fi
if [ "$SLUG_MODE" -eq 1 ]; then
if _attest_output="$(PWF_PLAN_ROOT="$PWD" PLAN_ID="${PLAN_ID}" sh "${_attest}" 2>&1)"; then
ATTESTATION_OK=1
ATTESTATION_REASON=""
return 0
else
_attest_rc=$?
fi
else
if _attest_output="$(PWF_PLAN_ROOT="" PLAN_ID="" sh "${_attest}" 2>&1)"; then
ATTESTATION_OK=1
ATTESTATION_REASON=""
return 0
else
_attest_rc=$?
fi
fi
_attest_reason="$(
printf '%s\n' "${_attest_output}" |
sed -n '/[^[:space:]]/ { s/[[:space:]][[:space:]]*/ /g; s/^ //; s/ $//; p; q; }' |
cut -c1-300
)"
if [ -n "${_attest_reason}" ]; then
ATTESTATION_REASON="${_attest_reason}"
else
ATTESTATION_REASON="${ATTESTATION_COMMAND} exited with code ${_attest_rc}"
fi
return 0
}
print_v3_mode_status() {
_status_dir="$1"
_marker="$(cat "${_status_dir}/.mode")"
if [ "${ATTESTATION_OK:-0}" -eq 1 ]; then
printf 'Mode: %s (attested, gate counter reset)\n' "${_marker}"
else
printf 'Mode: %s (NOT attested: %s; run %s before the first hook fire)\n' \
"${_marker}" "${ATTESTATION_REASON:-attestation failed}" "${ATTESTATION_COMMAND:-attest-plan.sh}"
fi
}
@@ -422,7 +476,7 @@ if [ "$SLUG_MODE" -eq 1 ]; then
echo "Pin this terminal to the plan for parallel sessions:"
echo " export PLAN_ID=$PLAN_ID"
if [ -n "$MODE" ]; then
echo "Mode: $(cat "${PLAN_DIR}/.mode") (attested, gate counter reset)"
print_v3_mode_status "${PLAN_DIR}"
fi
else
PROJECT_NAME="${PROJECT_NAME:-project}"
@@ -433,6 +487,6 @@ else
echo "Planning files initialized!"
echo "Files: task_plan.md, findings.md, progress.md"
if [ -n "$MODE" ]; then
echo "Mode: $(cat "$(pwd)/.mode") (attested, gate counter reset)"
print_v3_mode_status "$(pwd)"
fi
fi
@@ -139,6 +139,24 @@ function Test-WithinRoot {
return $candNorm.StartsWith($rootNorm + [System.IO.Path]::DirectorySeparatorChar, [System.StringComparison]::OrdinalIgnoreCase)
}
# A linked plan directory (symlink or junction) is never selectable: not by
# PLAN_ID, not by the pointer, not by the newest scan, and it never counts
# (#270). This is `[ -L ]` of resolve-plan-dir.sh and is_link of the Python
# twin: LinkType names symlinks and junctions only. The ReparsePoint
# attribute alone would also match OneDrive Files On-Demand placeholders,
# which every synced directory and file carries and which are not links to
# sh. The same predicate guards the pointer file below (#275).
function Test-LinkedDirectory {
param($PathOrItem)
if ($PathOrItem -is [string]) {
$item = Get-Item -LiteralPath $PathOrItem -Force -ErrorAction SilentlyContinue
} else {
$item = $PathOrItem
}
if (-not $item) { return $false }
return ([string]$item.LinkType) -in @('SymbolicLink', 'Junction')
}
$activeFile = Join-Path $PlanRoot ".active_plan"
# A set PLAN_ID is a BINDING, not a hint (issue #237). A selector that names
@@ -158,6 +176,9 @@ if (-not $env:PLAN_ID) {
}
if (Test-Path -LiteralPath $PlanRoot -PathType Container) {
foreach ($entry in (Get-ChildItem -LiteralPath $PlanRoot -Directory -ErrorAction SilentlyContinue)) {
# A linked plan directory (symlink, junction) is not selectable and
# never counts, matching `[ -L ]` in resolve-plan-dir.sh (#270).
if (Test-LinkedDirectory $entry) { continue }
if ((Test-ValidSlug $entry.Name) -and
(Test-Path -LiteralPath (Join-Path $entry.FullName "task_plan.md") -PathType Leaf)) {
$planCount++
@@ -175,7 +196,7 @@ if ($planCount -gt 1) { exit 0 }
if ($env:PLAN_ID) {
if (Test-ValidSlug $env:PLAN_ID) {
$candidate = Join-Path $PlanRoot $env:PLAN_ID
if ((Test-Path -LiteralPath $candidate -PathType Container) -and (Test-WithinRoot $candidate)) {
if ((Test-Path -LiteralPath $candidate -PathType Container) -and -not (Test-LinkedDirectory $candidate) -and (Test-WithinRoot $candidate)) {
Write-Output $candidate
exit 0
}
@@ -185,12 +206,14 @@ if ($env:PLAN_ID) {
# Get-Item observes the link object even when its target is missing, unlike
# Test-Path which follows the target. An active pointer that is a directory or
# reparse point is an unsafe/ambiguous selector and must terminate resolution;
# a symlink is an unsafe/ambiguous selector and must terminate resolution;
# falling through would silently select and expose the newest unrelated plan.
# LinkType, not the ReparsePoint attribute: OneDrive Files On-Demand marks
# every synced file as a reparse point, and such a pointer is a plain file
# to every other route (#275).
$activeItem = Get-Item -LiteralPath $activeFile -Force -ErrorAction SilentlyContinue
if ($activeItem) {
if ($activeItem.PSIsContainer -or
(($activeItem.Attributes -band [IO.FileAttributes]::ReparsePoint) -ne 0)) {
if ($activeItem.PSIsContainer -or (Test-LinkedDirectory $activeItem)) {
exit 0
}
# Get-Content -Raw returns $null for a zero-byte pointer; an empty pointer
@@ -198,7 +221,7 @@ if ($activeItem) {
$planId = "$(Get-Content -LiteralPath $activeFile -Raw -ErrorAction SilentlyContinue)".Trim()
if ($planId -and (Test-ValidSlug $planId)) {
$candidate = Join-Path $PlanRoot $planId
if ((Test-Path -LiteralPath $candidate -PathType Container) -and (Test-WithinRoot $candidate)) {
if ((Test-Path -LiteralPath $candidate -PathType Container) -and -not (Test-LinkedDirectory $candidate) -and (Test-WithinRoot $candidate)) {
Write-Output $candidate
exit 0
}
@@ -211,6 +234,7 @@ if ($activeItem) {
if (Test-Path -LiteralPath $PlanRoot -PathType Container) {
$latest = Get-ChildItem -LiteralPath $PlanRoot -Directory |
Where-Object { -not $_.Name.StartsWith('.') } |
Where-Object { -not (Test-LinkedDirectory $_) } |
Where-Object { Test-ValidSlug $_.Name } |
Where-Object { Test-Path -LiteralPath (Join-Path $_.FullName "task_plan.md") -PathType Leaf } |
Where-Object { Test-WithinRoot $_.FullName } |
@@ -246,10 +246,16 @@ mtime_of() {
printf "0\n"
}
# A linked plan directory (symlink or junction; `-L` sees both under Git
# Bash) is never selectable: not by PLAN_ID, not by the pointer, not by the
# newest-mtime scan, and it never counts below (#270). Containment alone let
# a link that stays inside the root be selected while the counter skipped
# it, so one real plan plus a newer linked one became an mtime guess again.
resolve_from_env() {
plan_id="${PLAN_ID:-}"
slug_is_valid "${plan_id}" || return 1
candidate="${PLAN_ROOT}/${plan_id}"
[ -L "${candidate}" ] && return 1
if [ -d "${candidate}" ] && is_within_root "${candidate}"; then
printf "%s\n" "${candidate}"
return 0
@@ -268,6 +274,7 @@ resolve_from_active_file() {
esac
slug_is_valid "${plan_id}" || return 1
candidate="${PLAN_ROOT}/${plan_id}"
[ -L "${candidate}" ] && return 1
if [ -d "${candidate}" ] && is_within_root "${candidate}"; then
printf "%s\n" "${candidate}"
return 0
@@ -288,6 +295,7 @@ resolve_latest_dir() {
case "${name}" in
.*) continue ;;
esac
[ -L "${clean}" ] && continue
slug_is_valid "${name}" || continue
[ -f "${clean}/task_plan.md" ] || continue
is_within_root "${clean}" || continue
@@ -338,8 +346,9 @@ if [ -z "${PLAN_ID:-}" ]; then
PLAN_COUNT=1
fi
for plan_candidate in "${PLAN_ROOT}"/*/task_plan.md; do
[ -f "$plan_candidate" ] || continue
plan_candidate_dir="${plan_candidate%/task_plan.md}"
[ -L "$plan_candidate_dir" ] && continue
[ -f "$plan_candidate" ] || continue
slug_is_valid "${plan_candidate_dir##*/}" || continue
PLAN_COUNT=$((PLAN_COUNT + 1))
if [ "$PLAN_COUNT" -gt 1 ]; then PLAN_AMBIGUOUS=1; break; fi
@@ -468,13 +468,16 @@ def _opencode_state_annotation(state: Any) -> str:
def _format_opencode_part(data: Dict[str, Any], session_id: str) -> Optional[Dict[str, Any]]:
"""Print-ready summary for one OpenCode part row."""
if not isinstance(data, dict):
return None
ptype = data.get('type')
short = safe_session_label(session_id)
if ptype == 'tool':
tool = (data.get('tool') or '').lower()
tool_value = data.get('tool')
tool = tool_value.lower() if isinstance(tool_value, str) else ''
state = data.get('state') or {}
input_ = state.get('input') if isinstance(state, dict) else None
input_ = input_ or {}
input_ = input_ if isinstance(input_, dict) else {}
outcome = _opencode_state_annotation(state)
if tool in ('write', 'edit'):
fp = input_.get('filePath', '')
@@ -486,7 +489,8 @@ def _format_opencode_part(data: Dict[str, Any], session_id: str) -> Optional[Dic
return {'session': short, 'summary': f"Tool bash: {cmd}{outcome}"}
return {'session': short, 'summary': f"Tool {tool}{outcome}"}
if ptype == 'text':
text = (data.get('text') or '')[:300]
text_value = data.get('text')
text = text_value[:300] if isinstance(text_value, str) else ''
if text.strip():
return {'session': short, 'summary': f"text: {text}"}
return None
@@ -577,6 +581,7 @@ def opencode_catchup(project_path: str, mode: str = 'no-history') -> None:
"""
SELECT time_created, data FROM part
WHERE session_id = ?
AND json_valid(data)
AND json_extract(data, '$.type') = 'tool'
AND lower(json_extract(data, '$.tool')) IN ('write', 'edit', 'patch')
AND (
@@ -121,9 +121,14 @@ function Test-SafeActiveFile {
param([switch]$AllowLink)
$item = Get-Item -LiteralPath $ActiveFile -Force -ErrorAction SilentlyContinue
if (-not $item) { return $false }
# Reading may follow a verified in-project link; writing must not.
# Reading may follow a verified in-project link; writing must not. A link
# is a symlink or junction by LinkType, never the bare ReparsePoint
# attribute: OneDrive Files On-Demand marks every synced file as a
# reparse point, and the pointer must stay writable there (#275).
$linked = ([string]$item.LinkType) -in @('SymbolicLink', 'Junction')
return -not $item.PSIsContainer -and
($AllowLink -or (($item.Attributes -band [IO.FileAttributes]::ReparsePoint) -eq 0)) -and
($AllowLink -or -not $linked) -and
($AllowLink -or -not $item.IsReadOnly) -and
(Test-WithinRoot $ActiveFile)
}
@@ -204,6 +209,8 @@ function Show-PlanList {
Write-Output "[active] marks the shared .active_plan pointer; listing does not bind this session."
$found = $false
foreach ($plan in (Get-ChildItem -LiteralPath $PlanRoot -Directory -ErrorAction SilentlyContinue | Sort-Object Name)) {
# A linked plan directory is never a plan (#270): no resolver selects it.
if (([string]$plan.LinkType) -in @('SymbolicLink', 'Junction')) { continue }
if (-not (Test-ValidSlug $plan.Name) -or -not (Test-WithinRoot $plan.FullName)) { continue }
$planFile = Join-Path $plan.FullName "task_plan.md"
if (-not (Test-Path -LiteralPath $planFile -PathType Leaf) -or -not (Test-WithinRoot $planFile)) { continue }
@@ -281,6 +288,11 @@ if (-not (Test-Path -LiteralPath $PlanDir -PathType Container)) {
Write-Error "Run: init-session.sh `"$PlanId`" to create it, or check .planning\ for available plans."
exit 1
}
$planDirItem = Get-Item -LiteralPath $PlanDir -Force -ErrorAction SilentlyContinue
if ($planDirItem -and (([string]$planDirItem.LinkType) -in @('SymbolicLink', 'Junction'))) {
Write-Error "Error: plan directory is a symlink or junction and no route selects it: $PlanDir"
exit 1
}
if (-not (Test-WithinRoot $PlanRoot) -or -not (Test-WithinRoot $PlanDir)) {
Write-Error "Error: plan directory must remain within the project."
exit 1
@@ -305,10 +317,23 @@ try {
$stream.Write($bytes, 0, $bytes.Length)
$stream.Flush()
} finally { $stream.Dispose() }
if ($activeItem) {
[IO.File]::Replace($tempFile, $ActiveFile, [NullString]::Value)
} else {
[IO.File]::Move($tempFile, $ActiveFile)
$maxAttempts = 20
for ($attempt = 1; $attempt -le $maxAttempts; $attempt++) {
try {
$currentActive = Get-Item -LiteralPath $ActiveFile -Force -ErrorAction SilentlyContinue
if ($currentActive) {
if (-not (Test-SafeActiveFile)) {
throw [InvalidOperationException]::new("the active plan pointer became unsafe during replacement")
}
[IO.File]::Replace($tempFile, $ActiveFile, [NullString]::Value)
} else {
[IO.File]::Move($tempFile, $ActiveFile)
}
break
} catch [IO.IOException] {
if ($attempt -eq $maxAttempts) { throw }
Start-Sleep -Milliseconds 25
}
}
} catch {
Write-Error "Error: could not set the active plan pointer: $($_.Exception.Message)"
@@ -272,6 +272,9 @@ list_plans() {
printf '%s\n' 'Available plans:'
for _dir in "${PLAN_ROOT}"/*; do
[ -d "${_dir}" ] || continue
# A linked plan directory is never a plan (#270): no resolver selects
# it, so listing it would advertise a PLAN_ID every route refuses.
[ -L "${_dir}" ] && continue
_id="${_dir##*/}"
slug_is_valid "${_id}" || continue
is_within_root "${_dir}" || continue
@@ -312,7 +315,7 @@ if [ "${1:-}" = '' ]; then
exit 1
fi
plan_id="$(current_active)"
if [ -n "${plan_id}" ] && [ -d "${PLAN_ROOT}/${plan_id}" ] && is_within_root "${PLAN_ROOT}/${plan_id}"; then
if [ -n "${plan_id}" ] && [ -d "${PLAN_ROOT}/${plan_id}" ] && [ ! -L "${PLAN_ROOT}/${plan_id}" ] && is_within_root "${PLAN_ROOT}/${plan_id}"; then
printf '%s\n' "Active plan: ${plan_id}" "Path: ${PLAN_ROOT}/${plan_id}"
elif [ -n "${plan_id}" ]; then
printf '%s\n' "Active plan pointer: ${plan_id} (directory not found or outside project - stale pointer)"
@@ -333,6 +336,10 @@ if [ ! -d "${PLAN_DIR}" ]; then
"Run: init-session.sh \"${PLAN_ID}\" to create it, or use --list to see available plans." >&2
exit 1
fi
if [ -L "${PLAN_DIR}" ]; then
printf '%s\n' "Error: plan directory is a symlink or junction and no route selects it: ${PLAN_DIR}" >&2
exit 1
fi
if ! is_within_root "${PLAN_ROOT}" || ! is_within_root "${PLAN_DIR}"; then
printf '%s\n' 'Error: plan directory is outside the project or cannot be verified.' >&2
exit 1
+5 -1
View File
@@ -88,9 +88,13 @@ function Resolve-CursorPlanContext {
# inject-plan.sh is. A stale pointer text, a dot-named directory or an
# invalid slug is ignored the way inject-plan.sh ignores it, so the legacy
# root applies, as on every other route.
# A pointer that is a directory or a symlink is unsafe. LinkType, not the
# ReparsePoint attribute: OneDrive Files On-Demand marks every synced file
# as a reparse point and such a pointer is a plain file to every other
# route; the attribute test made this hook go silent on OneDrive (#275).
$activeItem = Get-Item -LiteralPath (Join-Path $planRoot '.active_plan') -Force -ErrorAction SilentlyContinue
if ($activeItem -and ($activeItem.PSIsContainer -or
(($activeItem.Attributes -band [IO.FileAttributes]::ReparsePoint) -ne 0))) {
(([string]$activeItem.LinkType) -in @('SymbolicLink', 'Junction')))) {
return (New-CursorPlanContext $null 'invalid' 'unsafe-pointer')
}
if ($planRootExists) {
+1 -1
View File
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/skill-hook.sh\" \"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\" \"$HOME/.cursor/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
metadata:
version: "3.20.0"
version: "3.20.7"
---
@@ -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.");
@@ -18,6 +18,27 @@ param(
[switch]$Gated
)
# Windows PowerShell 5.1 can silently relocate a -File invocation when the
# inherited cwd contains wildcard characters such as [ or ]. Recover the
# physical cwd for a direct invocation before any project-relative paths are
# resolved.
if ($PSVersionTable.PSVersion.Major -eq 5 -and
[System.Management.Automation.WildcardPattern]::ContainsWildcardCharacters([Environment]::CurrentDirectory)) {
$processArgs = [Environment]::GetCommandLineArgs()
for ($index = 0; $index -lt ($processArgs.Length - 1); $index++) {
if ($processArgs[$index] -ieq '-File') {
$entryScript = $processArgs[$index + 1]
if (-not [IO.Path]::IsPathRooted($entryScript)) {
$entryScript = Join-Path ([Environment]::CurrentDirectory) $entryScript
}
if ([IO.Path]::GetFullPath($entryScript) -eq [IO.Path]::GetFullPath($PSCommandPath)) {
Set-Location -LiteralPath ([Environment]::CurrentDirectory)
}
break
}
}
}
$DATE = Get-Date -Format "yyyy-MM-dd"
# Resolve v3 opt-in mode. -Gated implies autonomous and is the stronger marker.
@@ -80,6 +101,26 @@ function Get-InheritedMode([string]$CurrentMode) {
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") {
Write-Host "Unknown template: $Template (available: default, analytics). Using default."
@@ -136,20 +177,7 @@ if ($UsePlanDir) {
$Counter++
}
$TargetDir = Join-Path $PlanningRoot $PlanId
New-Item -ItemType Directory -Path $TargetDir -Force | Out-Null
# Reuse the selector's contained, atomic pointer replacement. Set-Content
# would follow a reparse point and truncate a hardlinked pointer in place,
# overwriting whichever file shares that inode.
$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
}
New-Item -ItemType Directory -Path $TargetDir -Force -ErrorAction Stop | Out-Null
$Mode = Get-InheritedMode $Mode
} else {
$TargetDir = (Get-Location).Path
@@ -173,11 +201,12 @@ if ($UsePlanDir) {
Write-Host "PLAN_ID=$PlanId"
}
try {
# Create task_plan.md if it doesn't exist
if (-not (Test-Path -LiteralPath $TaskPlanPath)) {
$AnalyticsPlan = Join-Path $TemplateDir "analytics_task_plan.md"
if ($Template -eq "analytics" -and (Test-Path $AnalyticsPlan)) {
Copy-Item -LiteralPath $AnalyticsPlan -Destination $TaskPlanPath
Copy-Item -LiteralPath $AnalyticsPlan -Destination $TaskPlanPath -ErrorAction Stop
} else {
@"
# Task Plan: [Brief Description]
@@ -226,7 +255,7 @@ Phase 1
## Errors Encountered
| Error | Resolution |
|-------|------------|
"@ | Out-File -LiteralPath $TaskPlanPath -Encoding UTF8
"@ | Out-File -LiteralPath $TaskPlanPath -Encoding UTF8 -ErrorAction Stop
}
Write-Host "Created $TaskPlanDisplay"
} else {
@@ -237,7 +266,7 @@ Phase 1
if (-not (Test-Path -LiteralPath $FindingsPath)) {
$AnalyticsFindings = Join-Path $TemplateDir "analytics_findings.md"
if ($Template -eq "analytics" -and (Test-Path $AnalyticsFindings)) {
Copy-Item -LiteralPath $AnalyticsFindings -Destination $FindingsPath
Copy-Item -LiteralPath $AnalyticsFindings -Destination $FindingsPath -ErrorAction Stop
} else {
@"
# Findings & Decisions
@@ -258,7 +287,7 @@ if (-not (Test-Path -LiteralPath $FindingsPath)) {
## Resources
-
"@ | Out-File -LiteralPath $FindingsPath -Encoding UTF8
"@ | Out-File -LiteralPath $FindingsPath -Encoding UTF8 -ErrorAction Stop
}
Write-Host "Created $FindingsDisplay"
} else {
@@ -287,7 +316,7 @@ if (-not (Test-Path -LiteralPath $ProgressPath)) {
### Errors
| Error | Resolution |
|-------|------------|
"@ | Out-File -LiteralPath $ProgressPath -Encoding UTF8
"@ | Out-File -LiteralPath $ProgressPath -Encoding UTF8 -ErrorAction Stop
} else {
@"
# Progress Log
@@ -308,12 +337,56 @@ if (-not (Test-Path -LiteralPath $ProgressPath)) {
### Errors
| Error | Resolution |
|-------|------------|
"@ | Out-File -LiteralPath $ProgressPath -Encoding UTF8
"@ | Out-File -LiteralPath $ProgressPath -Encoding UTF8 -ErrorAction Stop
}
Write-Host "Created $ProgressDisplay"
} else {
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.
$pointerSet = $false
for ($attempt = 1; $attempt -le 5; $attempt++) {
$global:LASTEXITCODE = 0
try {
$selectorResult = & $PlanSelector $PlanId 2>&1
} catch {
$selectorResult = $_
$global:LASTEXITCODE = 1
}
if ($LASTEXITCODE -eq 0) {
$pointerSet = $true
break
}
# Another writer can replace the pointer between the selector's
# Get-Item and final-path check. Retry only that transient result.
$transientPointerRace = $selectorResult -is [System.Management.Automation.ErrorRecord] -and
$selectorResult.Exception.Message -ceq
'Error: could not set the active plan pointer: the active plan pointer became unsafe during replacement'
if ($attempt -eq 5 -or -not $transientPointerRace) {
break
}
Start-Sleep -Milliseconds 50
$global:LASTEXITCODE = 0
try {
& $PlanSelector -VerifyRoot *> $null
} catch {
$global:LASTEXITCODE = 1
}
if ($LASTEXITCODE -ne 0) { break }
}
if (-not $pointerSet) {
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!"
@@ -350,42 +423,94 @@ if ($Mode -ne "") {
# (c) auto-attest (attestation default-on in v3 modes, security strand rec 1).
# attest-plan.ps1 intentionally refuses non-Windows hosts because its secure
# no-follow implementation uses Win32 handles. On Unix, use the POSIX
# attester instead. Bind slug mode to the plan we just created so an
# inherited PLAN_ID cannot redirect attestation to another plan.
# 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 $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 {
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) {
$AttestPs1 = Join-Path $ScriptDir "attest-plan.ps1"
if (Test-Path -LiteralPath $AttestPs1) {
& $AttestPs1 *> $null
$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 {
$AttestSh = Join-Path $ScriptDir "attest-plan.sh"
$AttestationCommand = "attest-plan.sh"
$AttestSh = Join-Path $ScriptDir $AttestationCommand
$Sh = Get-Command sh -ErrorAction SilentlyContinue
if ($Sh -and (Test-Path -LiteralPath $AttestSh)) {
& $Sh.Path $AttestSh *> $null
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)"
}
}
@@ -103,6 +103,7 @@ slugify() {
# Lowercase, non-alphanumerics → '-', collapse repeats, trim leading/trailing '-'
printf '%s' "$1" \
| tr '[:upper:]' '[:lower:]' \
| tr '\r\n' '--' \
| sed -e 's/[^a-z0-9]/-/g' -e 's/-\{2,\}/-/g' -e 's/^-//' -e 's/-$//' \
| cut -c1-40
}
@@ -185,6 +186,10 @@ apply_v3_mode() {
_mode_plan="$2"
[ -z "$MODE" ] && return 0
ATTESTATION_OK=0
ATTESTATION_COMMAND="attest-plan.sh"
ATTESTATION_REASON="task_plan.md was not available for attestation"
# (a) reset the gate block counter and drop any stale gate ledger so a prior
# run's high block count cannot let the next run stop instantly.
printf '0\n' > "${_mode_dir}/.stop_blocks"
@@ -202,12 +207,61 @@ apply_v3_mode() {
# (c) auto-attest the plan (attestation default-on in v3 modes, security
# strand rec 1). attest-plan.sh resolves the same way init-session just
# pinned things: in slug mode PLAN_ID points at this plan dir; in legacy
# mode it is empty and the script falls back to ./task_plan.md at root.
# Run from the project root (CWD here) so both resolutions land.
_attest="${SCRIPT_DIR}/attest-plan.sh"
if [ -f "${_attest}" ] && [ -f "${_mode_plan}" ]; then
PLAN_ID="${PLAN_ID:-}" sh "${_attest}" >/dev/null 2>&1 || true
# pinned things. Slug mode binds both selectors to the plan that was
# just created, so an inherited PWF_PLAN_ROOT or PLAN_ID 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. Run from the project root (CWD here) so both
# resolutions land.
_attest="${SCRIPT_DIR}/${ATTESTATION_COMMAND}"
if [ ! -f "${_attest}" ]; then
ATTESTATION_REASON="${ATTESTATION_COMMAND} was not found beside init-session.sh"
return 0
fi
if [ ! -f "${_mode_plan}" ]; then
return 0
fi
if [ "$SLUG_MODE" -eq 1 ]; then
if _attest_output="$(PWF_PLAN_ROOT="$PWD" PLAN_ID="${PLAN_ID}" sh "${_attest}" 2>&1)"; then
ATTESTATION_OK=1
ATTESTATION_REASON=""
return 0
else
_attest_rc=$?
fi
else
if _attest_output="$(PWF_PLAN_ROOT="" PLAN_ID="" sh "${_attest}" 2>&1)"; then
ATTESTATION_OK=1
ATTESTATION_REASON=""
return 0
else
_attest_rc=$?
fi
fi
_attest_reason="$(
printf '%s\n' "${_attest_output}" |
sed -n '/[^[:space:]]/ { s/[[:space:]][[:space:]]*/ /g; s/^ //; s/ $//; p; q; }' |
cut -c1-300
)"
if [ -n "${_attest_reason}" ]; then
ATTESTATION_REASON="${_attest_reason}"
else
ATTESTATION_REASON="${ATTESTATION_COMMAND} exited with code ${_attest_rc}"
fi
return 0
}
print_v3_mode_status() {
_status_dir="$1"
_marker="$(cat "${_status_dir}/.mode")"
if [ "${ATTESTATION_OK:-0}" -eq 1 ]; then
printf 'Mode: %s (attested, gate counter reset)\n' "${_marker}"
else
printf 'Mode: %s (NOT attested: %s; run %s before the first hook fire)\n' \
"${_marker}" "${ATTESTATION_REASON:-attestation failed}" "${ATTESTATION_COMMAND:-attest-plan.sh}"
fi
}
@@ -422,7 +476,7 @@ if [ "$SLUG_MODE" -eq 1 ]; then
echo "Pin this terminal to the plan for parallel sessions:"
echo " export PLAN_ID=$PLAN_ID"
if [ -n "$MODE" ]; then
echo "Mode: $(cat "${PLAN_DIR}/.mode") (attested, gate counter reset)"
print_v3_mode_status "${PLAN_DIR}"
fi
else
PROJECT_NAME="${PROJECT_NAME:-project}"
@@ -433,6 +487,6 @@ else
echo "Planning files initialized!"
echo "Files: task_plan.md, findings.md, progress.md"
if [ -n "$MODE" ]; then
echo "Mode: $(cat "$(pwd)/.mode") (attested, gate counter reset)"
print_v3_mode_status "$(pwd)"
fi
fi
@@ -845,7 +845,10 @@ class Injector(object):
)
raise Bail()
if plan_id:
if slug_is_valid(plan_id) and is_dir(plan_prefix + ".planning/" + plan_id):
# A linked plan directory is never selectable (#270): the same
# `[ ! -L ]` the reference applies on every branch below.
if (slug_is_valid(plan_id) and is_dir(plan_prefix + ".planning/" + plan_id)
and not is_link(plan_prefix + ".planning/" + plan_id)):
resolved = plan_prefix + ".planning/" + plan_id
scope = "scoped"
explicit = True
@@ -864,7 +867,7 @@ class Injector(object):
active = b""
if active and slug_is_valid(active):
slug = active.decode("ascii")
if is_dir(plan_prefix + ".planning/" + slug):
if is_dir(plan_prefix + ".planning/" + slug) and not is_link(plan_prefix + ".planning/" + slug):
resolved = plan_prefix + ".planning/" + slug
scope = "scoped"
if not resolved and is_dir(plan_prefix + ".planning"):
@@ -880,6 +883,8 @@ class Injector(object):
candidate = plan_prefix + ".planning/" + name
if not is_dir(candidate):
continue
if is_link(candidate):
continue
if not slug_is_valid(name):
continue
if not is_file(candidate + "/task_plan.md"):
@@ -1327,7 +1332,12 @@ def plan_is_ambiguous(plan_root, project_root, plan_id=""):
except OSError:
names = []
for name in names:
if slug_is_valid(name) and is_file(plan_root + "/" + name + "/task_plan.md"):
candidate_dir = plan_root + "/" + name
# A linked plan directory is not selectable, so it never counts (#270):
# the reference tests `[ -L "$plan_candidate_dir" ]` before `-f`.
if is_link(candidate_dir):
continue
if slug_is_valid(name) and is_file(candidate_dir + "/task_plan.md"):
count += 1
if count > 1:
return True
@@ -1364,7 +1374,7 @@ def resolve_plan_dir(env=None):
if plan_id:
if slug_is_valid(plan_id):
candidate = fs_root + "/" + plan_id
if is_dir(candidate) and within(candidate):
if is_dir(candidate) and not is_link(candidate) and within(candidate):
return found(plan_id)
return ("", "")
@@ -1382,7 +1392,7 @@ def resolve_plan_dir(env=None):
if slug_is_valid(active):
slug = active.decode("ascii")
candidate = fs_root + "/" + slug
if is_dir(candidate) and within(candidate):
if is_dir(candidate) and not is_link(candidate) and within(candidate):
return found(slug)
if is_dir(fs_root):
@@ -1398,6 +1408,8 @@ def resolve_plan_dir(env=None):
continue
if name.startswith("."):
continue
if is_link(candidate):
continue
if not slug_is_valid(name):
continue
if not is_file(candidate + "/task_plan.md"):
@@ -263,8 +263,9 @@ if [ -z "${PLAN_ID:-}" ]; then
PLAN_COUNT=1
fi
for plan_candidate in "${PLAN_PREFIX}".planning/*/task_plan.md; do
[ -f "$plan_candidate" ] || continue
plan_candidate_dir="${plan_candidate%/task_plan.md}"
[ -L "$plan_candidate_dir" ] && continue
[ -f "$plan_candidate" ] || continue
slug_is_valid "${plan_candidate_dir##*/}" || continue
PLAN_COUNT=$((PLAN_COUNT + 1))
if [ "$PLAN_COUNT" -gt 1 ]; then PLAN_AMBIGUOUS=1; break; fi
@@ -295,7 +296,9 @@ if [ -n "${PLAN_ID:-}" ]; then
# printing on those would spam the transcript with the same line. The
# userprompt fire is also the one plan-doctor.sh drives, so /plan-doctor
# still sees and reports the state.
if slug_is_valid "$PLAN_ID" && [ -d "${PLAN_PREFIX}.planning/${PLAN_ID}" ]; then
# A linked plan directory is never selectable (#270): same `-L` rule as
# the counter above and as resolve-plan-dir.sh, on every branch below.
if slug_is_valid "$PLAN_ID" && [ -d "${PLAN_PREFIX}.planning/${PLAN_ID}" ] && [ ! -L "${PLAN_PREFIX}.planning/${PLAN_ID}" ]; then
RESOLVED="${PLAN_PREFIX}.planning/${PLAN_ID}"; SCOPE="scoped"; EXPLICIT=1
else
if [ "$CONTEXT" = "userprompt" ]; then
@@ -305,7 +308,7 @@ if [ -n "${PLAN_ID:-}" ]; then
fi
elif [ -f "${PLAN_PREFIX}.planning/.active_plan" ]; then
AP=$(tr -d '\r\n[:space:]' < "${PLAN_PREFIX}.planning/.active_plan" 2>/dev/null)
if [ -n "$AP" ] && slug_is_valid "$AP" && [ -d "${PLAN_PREFIX}.planning/${AP}" ]; then
if [ -n "$AP" ] && slug_is_valid "$AP" && [ -d "${PLAN_PREFIX}.planning/${AP}" ] && [ ! -L "${PLAN_PREFIX}.planning/${AP}" ]; then
RESOLVED="${PLAN_PREFIX}.planning/${AP}"; SCOPE="scoped"
fi
fi
@@ -314,6 +317,7 @@ if [ -z "$RESOLVED" ] && [ -d "${PLAN_PREFIX}.planning" ]; then
for d in "${PLAN_PREFIX}".planning/*/; do
d="${d%/}"; n="${d##*/}"
case "$n" in .*) continue;; esac
[ -L "$d" ] && continue
slug_is_valid "$n" || continue
[ -f "$d/task_plan.md" ] || continue
m=$(stat -c '%Y' "$d" 2>/dev/null || stat -f '%m' "$d" 2>/dev/null || date -r "$d" +%s 2>/dev/null || echo 0)
@@ -139,6 +139,24 @@ function Test-WithinRoot {
return $candNorm.StartsWith($rootNorm + [System.IO.Path]::DirectorySeparatorChar, [System.StringComparison]::OrdinalIgnoreCase)
}
# A linked plan directory (symlink or junction) is never selectable: not by
# PLAN_ID, not by the pointer, not by the newest scan, and it never counts
# (#270). This is `[ -L ]` of resolve-plan-dir.sh and is_link of the Python
# twin: LinkType names symlinks and junctions only. The ReparsePoint
# attribute alone would also match OneDrive Files On-Demand placeholders,
# which every synced directory and file carries and which are not links to
# sh. The same predicate guards the pointer file below (#275).
function Test-LinkedDirectory {
param($PathOrItem)
if ($PathOrItem -is [string]) {
$item = Get-Item -LiteralPath $PathOrItem -Force -ErrorAction SilentlyContinue
} else {
$item = $PathOrItem
}
if (-not $item) { return $false }
return ([string]$item.LinkType) -in @('SymbolicLink', 'Junction')
}
$activeFile = Join-Path $PlanRoot ".active_plan"
# A set PLAN_ID is a BINDING, not a hint (issue #237). A selector that names
@@ -158,6 +176,9 @@ if (-not $env:PLAN_ID) {
}
if (Test-Path -LiteralPath $PlanRoot -PathType Container) {
foreach ($entry in (Get-ChildItem -LiteralPath $PlanRoot -Directory -ErrorAction SilentlyContinue)) {
# A linked plan directory (symlink, junction) is not selectable and
# never counts, matching `[ -L ]` in resolve-plan-dir.sh (#270).
if (Test-LinkedDirectory $entry) { continue }
if ((Test-ValidSlug $entry.Name) -and
(Test-Path -LiteralPath (Join-Path $entry.FullName "task_plan.md") -PathType Leaf)) {
$planCount++
@@ -175,7 +196,7 @@ if ($planCount -gt 1) { exit 0 }
if ($env:PLAN_ID) {
if (Test-ValidSlug $env:PLAN_ID) {
$candidate = Join-Path $PlanRoot $env:PLAN_ID
if ((Test-Path -LiteralPath $candidate -PathType Container) -and (Test-WithinRoot $candidate)) {
if ((Test-Path -LiteralPath $candidate -PathType Container) -and -not (Test-LinkedDirectory $candidate) -and (Test-WithinRoot $candidate)) {
Write-Output $candidate
exit 0
}
@@ -185,12 +206,14 @@ if ($env:PLAN_ID) {
# Get-Item observes the link object even when its target is missing, unlike
# Test-Path which follows the target. An active pointer that is a directory or
# reparse point is an unsafe/ambiguous selector and must terminate resolution;
# a symlink is an unsafe/ambiguous selector and must terminate resolution;
# falling through would silently select and expose the newest unrelated plan.
# LinkType, not the ReparsePoint attribute: OneDrive Files On-Demand marks
# every synced file as a reparse point, and such a pointer is a plain file
# to every other route (#275).
$activeItem = Get-Item -LiteralPath $activeFile -Force -ErrorAction SilentlyContinue
if ($activeItem) {
if ($activeItem.PSIsContainer -or
(($activeItem.Attributes -band [IO.FileAttributes]::ReparsePoint) -ne 0)) {
if ($activeItem.PSIsContainer -or (Test-LinkedDirectory $activeItem)) {
exit 0
}
# Get-Content -Raw returns $null for a zero-byte pointer; an empty pointer
@@ -198,7 +221,7 @@ if ($activeItem) {
$planId = "$(Get-Content -LiteralPath $activeFile -Raw -ErrorAction SilentlyContinue)".Trim()
if ($planId -and (Test-ValidSlug $planId)) {
$candidate = Join-Path $PlanRoot $planId
if ((Test-Path -LiteralPath $candidate -PathType Container) -and (Test-WithinRoot $candidate)) {
if ((Test-Path -LiteralPath $candidate -PathType Container) -and -not (Test-LinkedDirectory $candidate) -and (Test-WithinRoot $candidate)) {
Write-Output $candidate
exit 0
}
@@ -211,6 +234,7 @@ if ($activeItem) {
if (Test-Path -LiteralPath $PlanRoot -PathType Container) {
$latest = Get-ChildItem -LiteralPath $PlanRoot -Directory |
Where-Object { -not $_.Name.StartsWith('.') } |
Where-Object { -not (Test-LinkedDirectory $_) } |
Where-Object { Test-ValidSlug $_.Name } |
Where-Object { Test-Path -LiteralPath (Join-Path $_.FullName "task_plan.md") -PathType Leaf } |
Where-Object { Test-WithinRoot $_.FullName } |
@@ -246,10 +246,16 @@ mtime_of() {
printf "0\n"
}
# A linked plan directory (symlink or junction; `-L` sees both under Git
# Bash) is never selectable: not by PLAN_ID, not by the pointer, not by the
# newest-mtime scan, and it never counts below (#270). Containment alone let
# a link that stays inside the root be selected while the counter skipped
# it, so one real plan plus a newer linked one became an mtime guess again.
resolve_from_env() {
plan_id="${PLAN_ID:-}"
slug_is_valid "${plan_id}" || return 1
candidate="${PLAN_ROOT}/${plan_id}"
[ -L "${candidate}" ] && return 1
if [ -d "${candidate}" ] && is_within_root "${candidate}"; then
printf "%s\n" "${candidate}"
return 0
@@ -268,6 +274,7 @@ resolve_from_active_file() {
esac
slug_is_valid "${plan_id}" || return 1
candidate="${PLAN_ROOT}/${plan_id}"
[ -L "${candidate}" ] && return 1
if [ -d "${candidate}" ] && is_within_root "${candidate}"; then
printf "%s\n" "${candidate}"
return 0
@@ -288,6 +295,7 @@ resolve_latest_dir() {
case "${name}" in
.*) continue ;;
esac
[ -L "${clean}" ] && continue
slug_is_valid "${name}" || continue
[ -f "${clean}/task_plan.md" ] || continue
is_within_root "${clean}" || continue
@@ -338,8 +346,9 @@ if [ -z "${PLAN_ID:-}" ]; then
PLAN_COUNT=1
fi
for plan_candidate in "${PLAN_ROOT}"/*/task_plan.md; do
[ -f "$plan_candidate" ] || continue
plan_candidate_dir="${plan_candidate%/task_plan.md}"
[ -L "$plan_candidate_dir" ] && continue
[ -f "$plan_candidate" ] || continue
slug_is_valid "${plan_candidate_dir##*/}" || continue
PLAN_COUNT=$((PLAN_COUNT + 1))
if [ "$PLAN_COUNT" -gt 1 ]; then PLAN_AMBIGUOUS=1; break; fi
@@ -468,13 +468,16 @@ def _opencode_state_annotation(state: Any) -> str:
def _format_opencode_part(data: Dict[str, Any], session_id: str) -> Optional[Dict[str, Any]]:
"""Print-ready summary for one OpenCode part row."""
if not isinstance(data, dict):
return None
ptype = data.get('type')
short = safe_session_label(session_id)
if ptype == 'tool':
tool = (data.get('tool') or '').lower()
tool_value = data.get('tool')
tool = tool_value.lower() if isinstance(tool_value, str) else ''
state = data.get('state') or {}
input_ = state.get('input') if isinstance(state, dict) else None
input_ = input_ or {}
input_ = input_ if isinstance(input_, dict) else {}
outcome = _opencode_state_annotation(state)
if tool in ('write', 'edit'):
fp = input_.get('filePath', '')
@@ -486,7 +489,8 @@ def _format_opencode_part(data: Dict[str, Any], session_id: str) -> Optional[Dic
return {'session': short, 'summary': f"Tool bash: {cmd}{outcome}"}
return {'session': short, 'summary': f"Tool {tool}{outcome}"}
if ptype == 'text':
text = (data.get('text') or '')[:300]
text_value = data.get('text')
text = text_value[:300] if isinstance(text_value, str) else ''
if text.strip():
return {'session': short, 'summary': f"text: {text}"}
return None
@@ -577,6 +581,7 @@ def opencode_catchup(project_path: str, mode: str = 'no-history') -> None:
"""
SELECT time_created, data FROM part
WHERE session_id = ?
AND json_valid(data)
AND json_extract(data, '$.type') = 'tool'
AND lower(json_extract(data, '$.tool')) IN ('write', 'edit', 'patch')
AND (
@@ -121,9 +121,14 @@ function Test-SafeActiveFile {
param([switch]$AllowLink)
$item = Get-Item -LiteralPath $ActiveFile -Force -ErrorAction SilentlyContinue
if (-not $item) { return $false }
# Reading may follow a verified in-project link; writing must not.
# Reading may follow a verified in-project link; writing must not. A link
# is a symlink or junction by LinkType, never the bare ReparsePoint
# attribute: OneDrive Files On-Demand marks every synced file as a
# reparse point, and the pointer must stay writable there (#275).
$linked = ([string]$item.LinkType) -in @('SymbolicLink', 'Junction')
return -not $item.PSIsContainer -and
($AllowLink -or (($item.Attributes -band [IO.FileAttributes]::ReparsePoint) -eq 0)) -and
($AllowLink -or -not $linked) -and
($AllowLink -or -not $item.IsReadOnly) -and
(Test-WithinRoot $ActiveFile)
}
@@ -204,6 +209,8 @@ function Show-PlanList {
Write-Output "[active] marks the shared .active_plan pointer; listing does not bind this session."
$found = $false
foreach ($plan in (Get-ChildItem -LiteralPath $PlanRoot -Directory -ErrorAction SilentlyContinue | Sort-Object Name)) {
# A linked plan directory is never a plan (#270): no resolver selects it.
if (([string]$plan.LinkType) -in @('SymbolicLink', 'Junction')) { continue }
if (-not (Test-ValidSlug $plan.Name) -or -not (Test-WithinRoot $plan.FullName)) { continue }
$planFile = Join-Path $plan.FullName "task_plan.md"
if (-not (Test-Path -LiteralPath $planFile -PathType Leaf) -or -not (Test-WithinRoot $planFile)) { continue }
@@ -281,6 +288,11 @@ if (-not (Test-Path -LiteralPath $PlanDir -PathType Container)) {
Write-Error "Run: init-session.sh `"$PlanId`" to create it, or check .planning\ for available plans."
exit 1
}
$planDirItem = Get-Item -LiteralPath $PlanDir -Force -ErrorAction SilentlyContinue
if ($planDirItem -and (([string]$planDirItem.LinkType) -in @('SymbolicLink', 'Junction'))) {
Write-Error "Error: plan directory is a symlink or junction and no route selects it: $PlanDir"
exit 1
}
if (-not (Test-WithinRoot $PlanRoot) -or -not (Test-WithinRoot $PlanDir)) {
Write-Error "Error: plan directory must remain within the project."
exit 1
@@ -305,10 +317,23 @@ try {
$stream.Write($bytes, 0, $bytes.Length)
$stream.Flush()
} finally { $stream.Dispose() }
if ($activeItem) {
[IO.File]::Replace($tempFile, $ActiveFile, [NullString]::Value)
} else {
[IO.File]::Move($tempFile, $ActiveFile)
$maxAttempts = 20
for ($attempt = 1; $attempt -le $maxAttempts; $attempt++) {
try {
$currentActive = Get-Item -LiteralPath $ActiveFile -Force -ErrorAction SilentlyContinue
if ($currentActive) {
if (-not (Test-SafeActiveFile)) {
throw [InvalidOperationException]::new("the active plan pointer became unsafe during replacement")
}
[IO.File]::Replace($tempFile, $ActiveFile, [NullString]::Value)
} else {
[IO.File]::Move($tempFile, $ActiveFile)
}
break
} catch [IO.IOException] {
if ($attempt -eq $maxAttempts) { throw }
Start-Sleep -Milliseconds 25
}
}
} catch {
Write-Error "Error: could not set the active plan pointer: $($_.Exception.Message)"
@@ -272,6 +272,9 @@ list_plans() {
printf '%s\n' 'Available plans:'
for _dir in "${PLAN_ROOT}"/*; do
[ -d "${_dir}" ] || continue
# A linked plan directory is never a plan (#270): no resolver selects
# it, so listing it would advertise a PLAN_ID every route refuses.
[ -L "${_dir}" ] && continue
_id="${_dir##*/}"
slug_is_valid "${_id}" || continue
is_within_root "${_dir}" || continue
@@ -312,7 +315,7 @@ if [ "${1:-}" = '' ]; then
exit 1
fi
plan_id="$(current_active)"
if [ -n "${plan_id}" ] && [ -d "${PLAN_ROOT}/${plan_id}" ] && is_within_root "${PLAN_ROOT}/${plan_id}"; then
if [ -n "${plan_id}" ] && [ -d "${PLAN_ROOT}/${plan_id}" ] && [ ! -L "${PLAN_ROOT}/${plan_id}" ] && is_within_root "${PLAN_ROOT}/${plan_id}"; then
printf '%s\n' "Active plan: ${plan_id}" "Path: ${PLAN_ROOT}/${plan_id}"
elif [ -n "${plan_id}" ]; then
printf '%s\n' "Active plan pointer: ${plan_id} (directory not found or outside project - stale pointer)"
@@ -333,6 +336,10 @@ if [ ! -d "${PLAN_DIR}" ]; then
"Run: init-session.sh \"${PLAN_ID}\" to create it, or use --list to see available plans." >&2
exit 1
fi
if [ -L "${PLAN_DIR}" ]; then
printf '%s\n' "Error: plan directory is a symlink or junction and no route selects it: ${PLAN_DIR}" >&2
exit 1
fi
if ! is_within_root "${PLAN_ROOT}" || ! is_within_root "${PLAN_DIR}"; then
printf '%s\n' 'Error: plan directory is outside the project or cannot be verified.' >&2
exit 1
@@ -8,6 +8,12 @@ State the analytical question or intended deliverable in one clear sentence.
[One sentence describing the analytical objective]
## Next Step
Record the single analytical action that should happen next. Update it whenever the active phase or immediate action changes.
[The single next analytical action. Update whenever phase status changes.]
## Current Phase
Name the phase currently being worked on.
@@ -76,6 +82,6 @@ Record each distinct error, the attempt number, and the resolution. Change the a
## Notes
- Update phase status as work progresses: `pending` to `in_progress` to `complete`.
- Re-read the goal and current phase before major analytical decisions.
- Re-read the goal, next step, and current phase before major analytical decisions.
- Log errors promptly so failed approaches are not repeated.
- Record query results and visual evidence in findings.md.
@@ -188,8 +188,14 @@ describe("resolver", () => {
fs.writeFileSync(path.join(planning, ".active_plan"), "2026-09-02-evil\n")
expect(resolvePlan(root, {}, env).planDir).toBeNull()
expect(resolvePlan(root, {}, { ...env, PLAN_ID: "2026-09-02-evil" }).planDir).toBeNull()
// a linked plan directory never counts toward the several-plans rule (#270)
expect(countSelectablePlans(root)).toBe(0)
const real = path.join(planning, "2026-09-02-real")
fs.mkdirSync(real)
fs.writeFileSync(path.join(real, "task_plan.md"), "# REAL\n")
expect(countSelectablePlans(root)).toBe(1)
expect(resolvePlan(root, {}, env).planDir).toBe(real)
fs.rmSync(path.join(real, "task_plan.md"))
try {
fs.symlinkSync(path.join(outside, "task_plan.md"), path.join(real, "task_plan.md"), "file")
} catch {
@@ -366,6 +372,41 @@ describe("init and status", () => {
expect(buildContext(root, dir)).toContain("[planning-with-files] plan: ")
})
it("updates a regular active plan pointer through a directory junction project root", () => {
const linkedRoot = `${root}-junction`
fs.symlinkSync(root, linkedRoot, "junction")
try {
const first = initPlan(linkedRoot, { name: "First" }, env)
expect(first.ok).toBe(true)
const second = initPlan(linkedRoot, { name: "Second" }, env)
expect(second.ok).toBe(true)
const pointer = path.join(root, ".planning", ".active_plan")
expect(fs.lstatSync(pointer).isFile()).toBe(true)
expect(fs.readFileSync(pointer, "utf8")).toBe(`${second.plan_id}\n`)
} finally {
fs.rmSync(linkedRoot, { recursive: true, force: true })
}
})
it("refuses a linked planning directory without changing its external pointer", () => {
const outside = `${root}-outside`
const planning = path.join(root, ".planning")
fs.mkdirSync(outside)
const pointer = path.join(outside, ".active_plan")
fs.writeFileSync(pointer, "external-plan\n")
fs.symlinkSync(outside, planning, "junction")
try {
const result = initPlan(root, { name: "Blocked" }, env)
expect(result.ok).toBe(false)
expect(result.error).toContain("unsafe active plan pointer")
expect(fs.readFileSync(pointer, "utf8")).toBe("external-plan\n")
expect(fs.readdirSync(outside)).toEqual([".active_plan"])
} finally {
fs.rmSync(planning, { recursive: true, force: true })
fs.rmSync(outside, { recursive: true, force: true })
}
})
it("uses a real skill template when one is discoverable, and rejects unknown modes", () => {
const skill = path.join(root, ".agents", "skills", "planning-with-files", "templates")
fs.mkdirSync(skill, { recursive: true })
@@ -86,6 +86,40 @@ function writeText(target: string, text: string): void {
fs.writeFileSync(target, text, { encoding: "utf8" })
}
function activePlanPointerError(planningRoot: string): string | null {
const pointer = path.join(planningRoot, ".active_plan")
const realRoot = realpathOrNull(planningRoot)
if (!isRealDir(planningRoot) || !realRoot) return `refusing to replace unsafe active plan pointer: ${pointer}`
if (!fs.existsSync(pointer)) return null
const st = lstatSafe(pointer)
const real = realpathOrNull(pointer)
return !st || !st.isFile() || st.isSymbolicLink() || st.nlink > 1 || !real || !isInside(real, realRoot)
? `refusing to replace unsafe active plan pointer: ${pointer}`
: null
}
function writeActivePlan(planningRoot: string, planId: string): string | null {
const pointer = path.join(planningRoot, ".active_plan")
const unsafe = activePlanPointerError(planningRoot)
if (unsafe) return unsafe
const tmp = path.join(planningRoot, `.active_plan.${process.pid}.${crypto.randomBytes(4).toString("hex")}.tmp`)
let fd: number | null = null
try {
fd = fs.openSync(tmp, "wx")
fs.writeFileSync(fd, `${planId}\n`, { encoding: "utf8" })
fs.closeSync(fd)
fd = null
fs.renameSync(tmp, pointer)
return null
} catch (err) {
return `could not safely update active plan pointer: ${err instanceof Error ? err.message : String(err)}`
} finally {
if (fd !== null) fs.closeSync(fd)
try { fs.unlinkSync(tmp) } catch { /* already renamed or absent */ }
}
}
function realpathOrNull(target: string): string | null {
try {
return fs.realpathSync(target)
@@ -205,6 +239,9 @@ export function countSelectablePlans(root: string): number {
}
for (const entry of entries) {
if (!slugIsValid(entry)) continue
// A linked plan directory is not selectable and never counts (#270),
// matching the shell counters, the Hermes plugin and resolvePlan below.
if (!isRealDir(path.join(planningRoot, entry))) continue
if (!isRegularFile(path.join(planningRoot, entry, "task_plan.md"))) continue
count += 1
if (count > 1) break
@@ -733,8 +770,11 @@ export function initPlan(
fs.mkdirSync(planningRoot, { recursive: true })
planId = `${new Date().toISOString().slice(0, 10)}-${slug}`
planDir = path.join(planningRoot, planId)
const pointerError = activePlanPointerError(planningRoot)
if (pointerError) return { ok: false, error: pointerError, project_dir: root }
fs.mkdirSync(planDir, { recursive: true })
writeText(path.join(planningRoot, ".active_plan"), `${planId}\n`)
const writeError = writeActivePlan(planningRoot, planId)
if (writeError) return { ok: false, error: writeError, project_dir: root }
}
const created = copyTemplates(planDir, templatesDir, template)
const result: InitResult = {
+1 -1
View File
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/skill-hook.sh\" \"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\" \"$HOME/.factory/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
metadata:
version: "3.20.0"
version: "3.20.7"
---
# Planning with Files
@@ -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.");
@@ -18,6 +18,27 @@ param(
[switch]$Gated
)
# Windows PowerShell 5.1 can silently relocate a -File invocation when the
# inherited cwd contains wildcard characters such as [ or ]. Recover the
# physical cwd for a direct invocation before any project-relative paths are
# resolved.
if ($PSVersionTable.PSVersion.Major -eq 5 -and
[System.Management.Automation.WildcardPattern]::ContainsWildcardCharacters([Environment]::CurrentDirectory)) {
$processArgs = [Environment]::GetCommandLineArgs()
for ($index = 0; $index -lt ($processArgs.Length - 1); $index++) {
if ($processArgs[$index] -ieq '-File') {
$entryScript = $processArgs[$index + 1]
if (-not [IO.Path]::IsPathRooted($entryScript)) {
$entryScript = Join-Path ([Environment]::CurrentDirectory) $entryScript
}
if ([IO.Path]::GetFullPath($entryScript) -eq [IO.Path]::GetFullPath($PSCommandPath)) {
Set-Location -LiteralPath ([Environment]::CurrentDirectory)
}
break
}
}
}
$DATE = Get-Date -Format "yyyy-MM-dd"
# Resolve v3 opt-in mode. -Gated implies autonomous and is the stronger marker.
@@ -80,6 +101,26 @@ function Get-InheritedMode([string]$CurrentMode) {
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") {
Write-Host "Unknown template: $Template (available: default, analytics). Using default."
@@ -136,20 +177,7 @@ if ($UsePlanDir) {
$Counter++
}
$TargetDir = Join-Path $PlanningRoot $PlanId
New-Item -ItemType Directory -Path $TargetDir -Force | Out-Null
# Reuse the selector's contained, atomic pointer replacement. Set-Content
# would follow a reparse point and truncate a hardlinked pointer in place,
# overwriting whichever file shares that inode.
$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
}
New-Item -ItemType Directory -Path $TargetDir -Force -ErrorAction Stop | Out-Null
$Mode = Get-InheritedMode $Mode
} else {
$TargetDir = (Get-Location).Path
@@ -173,11 +201,12 @@ if ($UsePlanDir) {
Write-Host "PLAN_ID=$PlanId"
}
try {
# Create task_plan.md if it doesn't exist
if (-not (Test-Path -LiteralPath $TaskPlanPath)) {
$AnalyticsPlan = Join-Path $TemplateDir "analytics_task_plan.md"
if ($Template -eq "analytics" -and (Test-Path $AnalyticsPlan)) {
Copy-Item -LiteralPath $AnalyticsPlan -Destination $TaskPlanPath
Copy-Item -LiteralPath $AnalyticsPlan -Destination $TaskPlanPath -ErrorAction Stop
} else {
@"
# Task Plan: [Brief Description]
@@ -226,7 +255,7 @@ Phase 1
## Errors Encountered
| Error | Resolution |
|-------|------------|
"@ | Out-File -LiteralPath $TaskPlanPath -Encoding UTF8
"@ | Out-File -LiteralPath $TaskPlanPath -Encoding UTF8 -ErrorAction Stop
}
Write-Host "Created $TaskPlanDisplay"
} else {
@@ -237,7 +266,7 @@ Phase 1
if (-not (Test-Path -LiteralPath $FindingsPath)) {
$AnalyticsFindings = Join-Path $TemplateDir "analytics_findings.md"
if ($Template -eq "analytics" -and (Test-Path $AnalyticsFindings)) {
Copy-Item -LiteralPath $AnalyticsFindings -Destination $FindingsPath
Copy-Item -LiteralPath $AnalyticsFindings -Destination $FindingsPath -ErrorAction Stop
} else {
@"
# Findings & Decisions
@@ -258,7 +287,7 @@ if (-not (Test-Path -LiteralPath $FindingsPath)) {
## Resources
-
"@ | Out-File -LiteralPath $FindingsPath -Encoding UTF8
"@ | Out-File -LiteralPath $FindingsPath -Encoding UTF8 -ErrorAction Stop
}
Write-Host "Created $FindingsDisplay"
} else {
@@ -287,7 +316,7 @@ if (-not (Test-Path -LiteralPath $ProgressPath)) {
### Errors
| Error | Resolution |
|-------|------------|
"@ | Out-File -LiteralPath $ProgressPath -Encoding UTF8
"@ | Out-File -LiteralPath $ProgressPath -Encoding UTF8 -ErrorAction Stop
} else {
@"
# Progress Log
@@ -308,12 +337,56 @@ if (-not (Test-Path -LiteralPath $ProgressPath)) {
### Errors
| Error | Resolution |
|-------|------------|
"@ | Out-File -LiteralPath $ProgressPath -Encoding UTF8
"@ | Out-File -LiteralPath $ProgressPath -Encoding UTF8 -ErrorAction Stop
}
Write-Host "Created $ProgressDisplay"
} else {
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.
$pointerSet = $false
for ($attempt = 1; $attempt -le 5; $attempt++) {
$global:LASTEXITCODE = 0
try {
$selectorResult = & $PlanSelector $PlanId 2>&1
} catch {
$selectorResult = $_
$global:LASTEXITCODE = 1
}
if ($LASTEXITCODE -eq 0) {
$pointerSet = $true
break
}
# Another writer can replace the pointer between the selector's
# Get-Item and final-path check. Retry only that transient result.
$transientPointerRace = $selectorResult -is [System.Management.Automation.ErrorRecord] -and
$selectorResult.Exception.Message -ceq
'Error: could not set the active plan pointer: the active plan pointer became unsafe during replacement'
if ($attempt -eq 5 -or -not $transientPointerRace) {
break
}
Start-Sleep -Milliseconds 50
$global:LASTEXITCODE = 0
try {
& $PlanSelector -VerifyRoot *> $null
} catch {
$global:LASTEXITCODE = 1
}
if ($LASTEXITCODE -ne 0) { break }
}
if (-not $pointerSet) {
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!"
@@ -350,42 +423,94 @@ if ($Mode -ne "") {
# (c) auto-attest (attestation default-on in v3 modes, security strand rec 1).
# attest-plan.ps1 intentionally refuses non-Windows hosts because its secure
# no-follow implementation uses Win32 handles. On Unix, use the POSIX
# attester instead. Bind slug mode to the plan we just created so an
# inherited PLAN_ID cannot redirect attestation to another plan.
# 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 $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 {
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) {
$AttestPs1 = Join-Path $ScriptDir "attest-plan.ps1"
if (Test-Path -LiteralPath $AttestPs1) {
& $AttestPs1 *> $null
$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 {
$AttestSh = Join-Path $ScriptDir "attest-plan.sh"
$AttestationCommand = "attest-plan.sh"
$AttestSh = Join-Path $ScriptDir $AttestationCommand
$Sh = Get-Command sh -ErrorAction SilentlyContinue
if ($Sh -and (Test-Path -LiteralPath $AttestSh)) {
& $Sh.Path $AttestSh *> $null
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)"
}
}
@@ -103,6 +103,7 @@ slugify() {
# Lowercase, non-alphanumerics → '-', collapse repeats, trim leading/trailing '-'
printf '%s' "$1" \
| tr '[:upper:]' '[:lower:]' \
| tr '\r\n' '--' \
| sed -e 's/[^a-z0-9]/-/g' -e 's/-\{2,\}/-/g' -e 's/^-//' -e 's/-$//' \
| cut -c1-40
}
@@ -185,6 +186,10 @@ apply_v3_mode() {
_mode_plan="$2"
[ -z "$MODE" ] && return 0
ATTESTATION_OK=0
ATTESTATION_COMMAND="attest-plan.sh"
ATTESTATION_REASON="task_plan.md was not available for attestation"
# (a) reset the gate block counter and drop any stale gate ledger so a prior
# run's high block count cannot let the next run stop instantly.
printf '0\n' > "${_mode_dir}/.stop_blocks"
@@ -202,12 +207,61 @@ apply_v3_mode() {
# (c) auto-attest the plan (attestation default-on in v3 modes, security
# strand rec 1). attest-plan.sh resolves the same way init-session just
# pinned things: in slug mode PLAN_ID points at this plan dir; in legacy
# mode it is empty and the script falls back to ./task_plan.md at root.
# Run from the project root (CWD here) so both resolutions land.
_attest="${SCRIPT_DIR}/attest-plan.sh"
if [ -f "${_attest}" ] && [ -f "${_mode_plan}" ]; then
PLAN_ID="${PLAN_ID:-}" sh "${_attest}" >/dev/null 2>&1 || true
# pinned things. Slug mode binds both selectors to the plan that was
# just created, so an inherited PWF_PLAN_ROOT or PLAN_ID 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. Run from the project root (CWD here) so both
# resolutions land.
_attest="${SCRIPT_DIR}/${ATTESTATION_COMMAND}"
if [ ! -f "${_attest}" ]; then
ATTESTATION_REASON="${ATTESTATION_COMMAND} was not found beside init-session.sh"
return 0
fi
if [ ! -f "${_mode_plan}" ]; then
return 0
fi
if [ "$SLUG_MODE" -eq 1 ]; then
if _attest_output="$(PWF_PLAN_ROOT="$PWD" PLAN_ID="${PLAN_ID}" sh "${_attest}" 2>&1)"; then
ATTESTATION_OK=1
ATTESTATION_REASON=""
return 0
else
_attest_rc=$?
fi
else
if _attest_output="$(PWF_PLAN_ROOT="" PLAN_ID="" sh "${_attest}" 2>&1)"; then
ATTESTATION_OK=1
ATTESTATION_REASON=""
return 0
else
_attest_rc=$?
fi
fi
_attest_reason="$(
printf '%s\n' "${_attest_output}" |
sed -n '/[^[:space:]]/ { s/[[:space:]][[:space:]]*/ /g; s/^ //; s/ $//; p; q; }' |
cut -c1-300
)"
if [ -n "${_attest_reason}" ]; then
ATTESTATION_REASON="${_attest_reason}"
else
ATTESTATION_REASON="${ATTESTATION_COMMAND} exited with code ${_attest_rc}"
fi
return 0
}
print_v3_mode_status() {
_status_dir="$1"
_marker="$(cat "${_status_dir}/.mode")"
if [ "${ATTESTATION_OK:-0}" -eq 1 ]; then
printf 'Mode: %s (attested, gate counter reset)\n' "${_marker}"
else
printf 'Mode: %s (NOT attested: %s; run %s before the first hook fire)\n' \
"${_marker}" "${ATTESTATION_REASON:-attestation failed}" "${ATTESTATION_COMMAND:-attest-plan.sh}"
fi
}
@@ -422,7 +476,7 @@ if [ "$SLUG_MODE" -eq 1 ]; then
echo "Pin this terminal to the plan for parallel sessions:"
echo " export PLAN_ID=$PLAN_ID"
if [ -n "$MODE" ]; then
echo "Mode: $(cat "${PLAN_DIR}/.mode") (attested, gate counter reset)"
print_v3_mode_status "${PLAN_DIR}"
fi
else
PROJECT_NAME="${PROJECT_NAME:-project}"
@@ -433,6 +487,6 @@ else
echo "Planning files initialized!"
echo "Files: task_plan.md, findings.md, progress.md"
if [ -n "$MODE" ]; then
echo "Mode: $(cat "$(pwd)/.mode") (attested, gate counter reset)"
print_v3_mode_status "$(pwd)"
fi
fi
@@ -845,7 +845,10 @@ class Injector(object):
)
raise Bail()
if plan_id:
if slug_is_valid(plan_id) and is_dir(plan_prefix + ".planning/" + plan_id):
# A linked plan directory is never selectable (#270): the same
# `[ ! -L ]` the reference applies on every branch below.
if (slug_is_valid(plan_id) and is_dir(plan_prefix + ".planning/" + plan_id)
and not is_link(plan_prefix + ".planning/" + plan_id)):
resolved = plan_prefix + ".planning/" + plan_id
scope = "scoped"
explicit = True
@@ -864,7 +867,7 @@ class Injector(object):
active = b""
if active and slug_is_valid(active):
slug = active.decode("ascii")
if is_dir(plan_prefix + ".planning/" + slug):
if is_dir(plan_prefix + ".planning/" + slug) and not is_link(plan_prefix + ".planning/" + slug):
resolved = plan_prefix + ".planning/" + slug
scope = "scoped"
if not resolved and is_dir(plan_prefix + ".planning"):
@@ -880,6 +883,8 @@ class Injector(object):
candidate = plan_prefix + ".planning/" + name
if not is_dir(candidate):
continue
if is_link(candidate):
continue
if not slug_is_valid(name):
continue
if not is_file(candidate + "/task_plan.md"):
@@ -1327,7 +1332,12 @@ def plan_is_ambiguous(plan_root, project_root, plan_id=""):
except OSError:
names = []
for name in names:
if slug_is_valid(name) and is_file(plan_root + "/" + name + "/task_plan.md"):
candidate_dir = plan_root + "/" + name
# A linked plan directory is not selectable, so it never counts (#270):
# the reference tests `[ -L "$plan_candidate_dir" ]` before `-f`.
if is_link(candidate_dir):
continue
if slug_is_valid(name) and is_file(candidate_dir + "/task_plan.md"):
count += 1
if count > 1:
return True
@@ -1364,7 +1374,7 @@ def resolve_plan_dir(env=None):
if plan_id:
if slug_is_valid(plan_id):
candidate = fs_root + "/" + plan_id
if is_dir(candidate) and within(candidate):
if is_dir(candidate) and not is_link(candidate) and within(candidate):
return found(plan_id)
return ("", "")
@@ -1382,7 +1392,7 @@ def resolve_plan_dir(env=None):
if slug_is_valid(active):
slug = active.decode("ascii")
candidate = fs_root + "/" + slug
if is_dir(candidate) and within(candidate):
if is_dir(candidate) and not is_link(candidate) and within(candidate):
return found(slug)
if is_dir(fs_root):
@@ -1398,6 +1408,8 @@ def resolve_plan_dir(env=None):
continue
if name.startswith("."):
continue
if is_link(candidate):
continue
if not slug_is_valid(name):
continue
if not is_file(candidate + "/task_plan.md"):
@@ -263,8 +263,9 @@ if [ -z "${PLAN_ID:-}" ]; then
PLAN_COUNT=1
fi
for plan_candidate in "${PLAN_PREFIX}".planning/*/task_plan.md; do
[ -f "$plan_candidate" ] || continue
plan_candidate_dir="${plan_candidate%/task_plan.md}"
[ -L "$plan_candidate_dir" ] && continue
[ -f "$plan_candidate" ] || continue
slug_is_valid "${plan_candidate_dir##*/}" || continue
PLAN_COUNT=$((PLAN_COUNT + 1))
if [ "$PLAN_COUNT" -gt 1 ]; then PLAN_AMBIGUOUS=1; break; fi
@@ -295,7 +296,9 @@ if [ -n "${PLAN_ID:-}" ]; then
# printing on those would spam the transcript with the same line. The
# userprompt fire is also the one plan-doctor.sh drives, so /plan-doctor
# still sees and reports the state.
if slug_is_valid "$PLAN_ID" && [ -d "${PLAN_PREFIX}.planning/${PLAN_ID}" ]; then
# A linked plan directory is never selectable (#270): same `-L` rule as
# the counter above and as resolve-plan-dir.sh, on every branch below.
if slug_is_valid "$PLAN_ID" && [ -d "${PLAN_PREFIX}.planning/${PLAN_ID}" ] && [ ! -L "${PLAN_PREFIX}.planning/${PLAN_ID}" ]; then
RESOLVED="${PLAN_PREFIX}.planning/${PLAN_ID}"; SCOPE="scoped"; EXPLICIT=1
else
if [ "$CONTEXT" = "userprompt" ]; then
@@ -305,7 +308,7 @@ if [ -n "${PLAN_ID:-}" ]; then
fi
elif [ -f "${PLAN_PREFIX}.planning/.active_plan" ]; then
AP=$(tr -d '\r\n[:space:]' < "${PLAN_PREFIX}.planning/.active_plan" 2>/dev/null)
if [ -n "$AP" ] && slug_is_valid "$AP" && [ -d "${PLAN_PREFIX}.planning/${AP}" ]; then
if [ -n "$AP" ] && slug_is_valid "$AP" && [ -d "${PLAN_PREFIX}.planning/${AP}" ] && [ ! -L "${PLAN_PREFIX}.planning/${AP}" ]; then
RESOLVED="${PLAN_PREFIX}.planning/${AP}"; SCOPE="scoped"
fi
fi
@@ -314,6 +317,7 @@ if [ -z "$RESOLVED" ] && [ -d "${PLAN_PREFIX}.planning" ]; then
for d in "${PLAN_PREFIX}".planning/*/; do
d="${d%/}"; n="${d##*/}"
case "$n" in .*) continue;; esac
[ -L "$d" ] && continue
slug_is_valid "$n" || continue
[ -f "$d/task_plan.md" ] || continue
m=$(stat -c '%Y' "$d" 2>/dev/null || stat -f '%m' "$d" 2>/dev/null || date -r "$d" +%s 2>/dev/null || echo 0)
@@ -139,6 +139,24 @@ function Test-WithinRoot {
return $candNorm.StartsWith($rootNorm + [System.IO.Path]::DirectorySeparatorChar, [System.StringComparison]::OrdinalIgnoreCase)
}
# A linked plan directory (symlink or junction) is never selectable: not by
# PLAN_ID, not by the pointer, not by the newest scan, and it never counts
# (#270). This is `[ -L ]` of resolve-plan-dir.sh and is_link of the Python
# twin: LinkType names symlinks and junctions only. The ReparsePoint
# attribute alone would also match OneDrive Files On-Demand placeholders,
# which every synced directory and file carries and which are not links to
# sh. The same predicate guards the pointer file below (#275).
function Test-LinkedDirectory {
param($PathOrItem)
if ($PathOrItem -is [string]) {
$item = Get-Item -LiteralPath $PathOrItem -Force -ErrorAction SilentlyContinue
} else {
$item = $PathOrItem
}
if (-not $item) { return $false }
return ([string]$item.LinkType) -in @('SymbolicLink', 'Junction')
}
$activeFile = Join-Path $PlanRoot ".active_plan"
# A set PLAN_ID is a BINDING, not a hint (issue #237). A selector that names
@@ -158,6 +176,9 @@ if (-not $env:PLAN_ID) {
}
if (Test-Path -LiteralPath $PlanRoot -PathType Container) {
foreach ($entry in (Get-ChildItem -LiteralPath $PlanRoot -Directory -ErrorAction SilentlyContinue)) {
# A linked plan directory (symlink, junction) is not selectable and
# never counts, matching `[ -L ]` in resolve-plan-dir.sh (#270).
if (Test-LinkedDirectory $entry) { continue }
if ((Test-ValidSlug $entry.Name) -and
(Test-Path -LiteralPath (Join-Path $entry.FullName "task_plan.md") -PathType Leaf)) {
$planCount++
@@ -175,7 +196,7 @@ if ($planCount -gt 1) { exit 0 }
if ($env:PLAN_ID) {
if (Test-ValidSlug $env:PLAN_ID) {
$candidate = Join-Path $PlanRoot $env:PLAN_ID
if ((Test-Path -LiteralPath $candidate -PathType Container) -and (Test-WithinRoot $candidate)) {
if ((Test-Path -LiteralPath $candidate -PathType Container) -and -not (Test-LinkedDirectory $candidate) -and (Test-WithinRoot $candidate)) {
Write-Output $candidate
exit 0
}
@@ -185,12 +206,14 @@ if ($env:PLAN_ID) {
# Get-Item observes the link object even when its target is missing, unlike
# Test-Path which follows the target. An active pointer that is a directory or
# reparse point is an unsafe/ambiguous selector and must terminate resolution;
# a symlink is an unsafe/ambiguous selector and must terminate resolution;
# falling through would silently select and expose the newest unrelated plan.
# LinkType, not the ReparsePoint attribute: OneDrive Files On-Demand marks
# every synced file as a reparse point, and such a pointer is a plain file
# to every other route (#275).
$activeItem = Get-Item -LiteralPath $activeFile -Force -ErrorAction SilentlyContinue
if ($activeItem) {
if ($activeItem.PSIsContainer -or
(($activeItem.Attributes -band [IO.FileAttributes]::ReparsePoint) -ne 0)) {
if ($activeItem.PSIsContainer -or (Test-LinkedDirectory $activeItem)) {
exit 0
}
# Get-Content -Raw returns $null for a zero-byte pointer; an empty pointer
@@ -198,7 +221,7 @@ if ($activeItem) {
$planId = "$(Get-Content -LiteralPath $activeFile -Raw -ErrorAction SilentlyContinue)".Trim()
if ($planId -and (Test-ValidSlug $planId)) {
$candidate = Join-Path $PlanRoot $planId
if ((Test-Path -LiteralPath $candidate -PathType Container) -and (Test-WithinRoot $candidate)) {
if ((Test-Path -LiteralPath $candidate -PathType Container) -and -not (Test-LinkedDirectory $candidate) -and (Test-WithinRoot $candidate)) {
Write-Output $candidate
exit 0
}
@@ -211,6 +234,7 @@ if ($activeItem) {
if (Test-Path -LiteralPath $PlanRoot -PathType Container) {
$latest = Get-ChildItem -LiteralPath $PlanRoot -Directory |
Where-Object { -not $_.Name.StartsWith('.') } |
Where-Object { -not (Test-LinkedDirectory $_) } |
Where-Object { Test-ValidSlug $_.Name } |
Where-Object { Test-Path -LiteralPath (Join-Path $_.FullName "task_plan.md") -PathType Leaf } |
Where-Object { Test-WithinRoot $_.FullName } |
@@ -246,10 +246,16 @@ mtime_of() {
printf "0\n"
}
# A linked plan directory (symlink or junction; `-L` sees both under Git
# Bash) is never selectable: not by PLAN_ID, not by the pointer, not by the
# newest-mtime scan, and it never counts below (#270). Containment alone let
# a link that stays inside the root be selected while the counter skipped
# it, so one real plan plus a newer linked one became an mtime guess again.
resolve_from_env() {
plan_id="${PLAN_ID:-}"
slug_is_valid "${plan_id}" || return 1
candidate="${PLAN_ROOT}/${plan_id}"
[ -L "${candidate}" ] && return 1
if [ -d "${candidate}" ] && is_within_root "${candidate}"; then
printf "%s\n" "${candidate}"
return 0
@@ -268,6 +274,7 @@ resolve_from_active_file() {
esac
slug_is_valid "${plan_id}" || return 1
candidate="${PLAN_ROOT}/${plan_id}"
[ -L "${candidate}" ] && return 1
if [ -d "${candidate}" ] && is_within_root "${candidate}"; then
printf "%s\n" "${candidate}"
return 0
@@ -288,6 +295,7 @@ resolve_latest_dir() {
case "${name}" in
.*) continue ;;
esac
[ -L "${clean}" ] && continue
slug_is_valid "${name}" || continue
[ -f "${clean}/task_plan.md" ] || continue
is_within_root "${clean}" || continue
@@ -338,8 +346,9 @@ if [ -z "${PLAN_ID:-}" ]; then
PLAN_COUNT=1
fi
for plan_candidate in "${PLAN_ROOT}"/*/task_plan.md; do
[ -f "$plan_candidate" ] || continue
plan_candidate_dir="${plan_candidate%/task_plan.md}"
[ -L "$plan_candidate_dir" ] && continue
[ -f "$plan_candidate" ] || continue
slug_is_valid "${plan_candidate_dir##*/}" || continue
PLAN_COUNT=$((PLAN_COUNT + 1))
if [ "$PLAN_COUNT" -gt 1 ]; then PLAN_AMBIGUOUS=1; break; fi
@@ -468,13 +468,16 @@ def _opencode_state_annotation(state: Any) -> str:
def _format_opencode_part(data: Dict[str, Any], session_id: str) -> Optional[Dict[str, Any]]:
"""Print-ready summary for one OpenCode part row."""
if not isinstance(data, dict):
return None
ptype = data.get('type')
short = safe_session_label(session_id)
if ptype == 'tool':
tool = (data.get('tool') or '').lower()
tool_value = data.get('tool')
tool = tool_value.lower() if isinstance(tool_value, str) else ''
state = data.get('state') or {}
input_ = state.get('input') if isinstance(state, dict) else None
input_ = input_ or {}
input_ = input_ if isinstance(input_, dict) else {}
outcome = _opencode_state_annotation(state)
if tool in ('write', 'edit'):
fp = input_.get('filePath', '')
@@ -486,7 +489,8 @@ def _format_opencode_part(data: Dict[str, Any], session_id: str) -> Optional[Dic
return {'session': short, 'summary': f"Tool bash: {cmd}{outcome}"}
return {'session': short, 'summary': f"Tool {tool}{outcome}"}
if ptype == 'text':
text = (data.get('text') or '')[:300]
text_value = data.get('text')
text = text_value[:300] if isinstance(text_value, str) else ''
if text.strip():
return {'session': short, 'summary': f"text: {text}"}
return None
@@ -577,6 +581,7 @@ def opencode_catchup(project_path: str, mode: str = 'no-history') -> None:
"""
SELECT time_created, data FROM part
WHERE session_id = ?
AND json_valid(data)
AND json_extract(data, '$.type') = 'tool'
AND lower(json_extract(data, '$.tool')) IN ('write', 'edit', 'patch')
AND (
@@ -121,9 +121,14 @@ function Test-SafeActiveFile {
param([switch]$AllowLink)
$item = Get-Item -LiteralPath $ActiveFile -Force -ErrorAction SilentlyContinue
if (-not $item) { return $false }
# Reading may follow a verified in-project link; writing must not.
# Reading may follow a verified in-project link; writing must not. A link
# is a symlink or junction by LinkType, never the bare ReparsePoint
# attribute: OneDrive Files On-Demand marks every synced file as a
# reparse point, and the pointer must stay writable there (#275).
$linked = ([string]$item.LinkType) -in @('SymbolicLink', 'Junction')
return -not $item.PSIsContainer -and
($AllowLink -or (($item.Attributes -band [IO.FileAttributes]::ReparsePoint) -eq 0)) -and
($AllowLink -or -not $linked) -and
($AllowLink -or -not $item.IsReadOnly) -and
(Test-WithinRoot $ActiveFile)
}
@@ -204,6 +209,8 @@ function Show-PlanList {
Write-Output "[active] marks the shared .active_plan pointer; listing does not bind this session."
$found = $false
foreach ($plan in (Get-ChildItem -LiteralPath $PlanRoot -Directory -ErrorAction SilentlyContinue | Sort-Object Name)) {
# A linked plan directory is never a plan (#270): no resolver selects it.
if (([string]$plan.LinkType) -in @('SymbolicLink', 'Junction')) { continue }
if (-not (Test-ValidSlug $plan.Name) -or -not (Test-WithinRoot $plan.FullName)) { continue }
$planFile = Join-Path $plan.FullName "task_plan.md"
if (-not (Test-Path -LiteralPath $planFile -PathType Leaf) -or -not (Test-WithinRoot $planFile)) { continue }
@@ -281,6 +288,11 @@ if (-not (Test-Path -LiteralPath $PlanDir -PathType Container)) {
Write-Error "Run: init-session.sh `"$PlanId`" to create it, or check .planning\ for available plans."
exit 1
}
$planDirItem = Get-Item -LiteralPath $PlanDir -Force -ErrorAction SilentlyContinue
if ($planDirItem -and (([string]$planDirItem.LinkType) -in @('SymbolicLink', 'Junction'))) {
Write-Error "Error: plan directory is a symlink or junction and no route selects it: $PlanDir"
exit 1
}
if (-not (Test-WithinRoot $PlanRoot) -or -not (Test-WithinRoot $PlanDir)) {
Write-Error "Error: plan directory must remain within the project."
exit 1
@@ -305,10 +317,23 @@ try {
$stream.Write($bytes, 0, $bytes.Length)
$stream.Flush()
} finally { $stream.Dispose() }
if ($activeItem) {
[IO.File]::Replace($tempFile, $ActiveFile, [NullString]::Value)
} else {
[IO.File]::Move($tempFile, $ActiveFile)
$maxAttempts = 20
for ($attempt = 1; $attempt -le $maxAttempts; $attempt++) {
try {
$currentActive = Get-Item -LiteralPath $ActiveFile -Force -ErrorAction SilentlyContinue
if ($currentActive) {
if (-not (Test-SafeActiveFile)) {
throw [InvalidOperationException]::new("the active plan pointer became unsafe during replacement")
}
[IO.File]::Replace($tempFile, $ActiveFile, [NullString]::Value)
} else {
[IO.File]::Move($tempFile, $ActiveFile)
}
break
} catch [IO.IOException] {
if ($attempt -eq $maxAttempts) { throw }
Start-Sleep -Milliseconds 25
}
}
} catch {
Write-Error "Error: could not set the active plan pointer: $($_.Exception.Message)"
@@ -272,6 +272,9 @@ list_plans() {
printf '%s\n' 'Available plans:'
for _dir in "${PLAN_ROOT}"/*; do
[ -d "${_dir}" ] || continue
# A linked plan directory is never a plan (#270): no resolver selects
# it, so listing it would advertise a PLAN_ID every route refuses.
[ -L "${_dir}" ] && continue
_id="${_dir##*/}"
slug_is_valid "${_id}" || continue
is_within_root "${_dir}" || continue
@@ -312,7 +315,7 @@ if [ "${1:-}" = '' ]; then
exit 1
fi
plan_id="$(current_active)"
if [ -n "${plan_id}" ] && [ -d "${PLAN_ROOT}/${plan_id}" ] && is_within_root "${PLAN_ROOT}/${plan_id}"; then
if [ -n "${plan_id}" ] && [ -d "${PLAN_ROOT}/${plan_id}" ] && [ ! -L "${PLAN_ROOT}/${plan_id}" ] && is_within_root "${PLAN_ROOT}/${plan_id}"; then
printf '%s\n' "Active plan: ${plan_id}" "Path: ${PLAN_ROOT}/${plan_id}"
elif [ -n "${plan_id}" ]; then
printf '%s\n' "Active plan pointer: ${plan_id} (directory not found or outside project - stale pointer)"
@@ -333,6 +336,10 @@ if [ ! -d "${PLAN_DIR}" ]; then
"Run: init-session.sh \"${PLAN_ID}\" to create it, or use --list to see available plans." >&2
exit 1
fi
if [ -L "${PLAN_DIR}" ]; then
printf '%s\n' "Error: plan directory is a symlink or junction and no route selects it: ${PLAN_DIR}" >&2
exit 1
fi
if ! is_within_root "${PLAN_ROOT}" || ! is_within_root "${PLAN_DIR}"; then
printf '%s\n' 'Error: plan directory is outside the project or cannot be verified.' >&2
exit 1
@@ -8,6 +8,12 @@ State the analytical question or intended deliverable in one clear sentence.
[One sentence describing the analytical objective]
## Next Step
Record the single analytical action that should happen next. Update it whenever the active phase or immediate action changes.
[The single next analytical action. Update whenever phase status changes.]
## Current Phase
Name the phase currently being worked on.
@@ -76,6 +82,6 @@ Record each distinct error, the attempt number, and the resolution. Change the a
## Notes
- Update phase status as work progresses: `pending` to `in_progress` to `complete`.
- Re-read the goal and current phase before major analytical decisions.
- Re-read the goal, next step, and current phase before major analytical decisions.
- Log errors promptly so failed approaches are not repeated.
- Record query results and visual evidence in findings.md.
@@ -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.");
@@ -18,6 +18,27 @@ param(
[switch]$Gated
)
# Windows PowerShell 5.1 can silently relocate a -File invocation when the
# inherited cwd contains wildcard characters such as [ or ]. Recover the
# physical cwd for a direct invocation before any project-relative paths are
# resolved.
if ($PSVersionTable.PSVersion.Major -eq 5 -and
[System.Management.Automation.WildcardPattern]::ContainsWildcardCharacters([Environment]::CurrentDirectory)) {
$processArgs = [Environment]::GetCommandLineArgs()
for ($index = 0; $index -lt ($processArgs.Length - 1); $index++) {
if ($processArgs[$index] -ieq '-File') {
$entryScript = $processArgs[$index + 1]
if (-not [IO.Path]::IsPathRooted($entryScript)) {
$entryScript = Join-Path ([Environment]::CurrentDirectory) $entryScript
}
if ([IO.Path]::GetFullPath($entryScript) -eq [IO.Path]::GetFullPath($PSCommandPath)) {
Set-Location -LiteralPath ([Environment]::CurrentDirectory)
}
break
}
}
}
$DATE = Get-Date -Format "yyyy-MM-dd"
# Resolve v3 opt-in mode. -Gated implies autonomous and is the stronger marker.
@@ -80,6 +101,26 @@ function Get-InheritedMode([string]$CurrentMode) {
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") {
Write-Host "Unknown template: $Template (available: default, analytics). Using default."
@@ -136,20 +177,7 @@ if ($UsePlanDir) {
$Counter++
}
$TargetDir = Join-Path $PlanningRoot $PlanId
New-Item -ItemType Directory -Path $TargetDir -Force | Out-Null
# Reuse the selector's contained, atomic pointer replacement. Set-Content
# would follow a reparse point and truncate a hardlinked pointer in place,
# overwriting whichever file shares that inode.
$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
}
New-Item -ItemType Directory -Path $TargetDir -Force -ErrorAction Stop | Out-Null
$Mode = Get-InheritedMode $Mode
} else {
$TargetDir = (Get-Location).Path
@@ -173,11 +201,12 @@ if ($UsePlanDir) {
Write-Host "PLAN_ID=$PlanId"
}
try {
# Create task_plan.md if it doesn't exist
if (-not (Test-Path -LiteralPath $TaskPlanPath)) {
$AnalyticsPlan = Join-Path $TemplateDir "analytics_task_plan.md"
if ($Template -eq "analytics" -and (Test-Path $AnalyticsPlan)) {
Copy-Item -LiteralPath $AnalyticsPlan -Destination $TaskPlanPath
Copy-Item -LiteralPath $AnalyticsPlan -Destination $TaskPlanPath -ErrorAction Stop
} else {
@"
# Task Plan: [Brief Description]
@@ -226,7 +255,7 @@ Phase 1
## Errors Encountered
| Error | Resolution |
|-------|------------|
"@ | Out-File -LiteralPath $TaskPlanPath -Encoding UTF8
"@ | Out-File -LiteralPath $TaskPlanPath -Encoding UTF8 -ErrorAction Stop
}
Write-Host "Created $TaskPlanDisplay"
} else {
@@ -237,7 +266,7 @@ Phase 1
if (-not (Test-Path -LiteralPath $FindingsPath)) {
$AnalyticsFindings = Join-Path $TemplateDir "analytics_findings.md"
if ($Template -eq "analytics" -and (Test-Path $AnalyticsFindings)) {
Copy-Item -LiteralPath $AnalyticsFindings -Destination $FindingsPath
Copy-Item -LiteralPath $AnalyticsFindings -Destination $FindingsPath -ErrorAction Stop
} else {
@"
# Findings & Decisions
@@ -258,7 +287,7 @@ if (-not (Test-Path -LiteralPath $FindingsPath)) {
## Resources
-
"@ | Out-File -LiteralPath $FindingsPath -Encoding UTF8
"@ | Out-File -LiteralPath $FindingsPath -Encoding UTF8 -ErrorAction Stop
}
Write-Host "Created $FindingsDisplay"
} else {
@@ -287,7 +316,7 @@ if (-not (Test-Path -LiteralPath $ProgressPath)) {
### Errors
| Error | Resolution |
|-------|------------|
"@ | Out-File -LiteralPath $ProgressPath -Encoding UTF8
"@ | Out-File -LiteralPath $ProgressPath -Encoding UTF8 -ErrorAction Stop
} else {
@"
# Progress Log
@@ -308,12 +337,56 @@ if (-not (Test-Path -LiteralPath $ProgressPath)) {
### Errors
| Error | Resolution |
|-------|------------|
"@ | Out-File -LiteralPath $ProgressPath -Encoding UTF8
"@ | Out-File -LiteralPath $ProgressPath -Encoding UTF8 -ErrorAction Stop
}
Write-Host "Created $ProgressDisplay"
} else {
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.
$pointerSet = $false
for ($attempt = 1; $attempt -le 5; $attempt++) {
$global:LASTEXITCODE = 0
try {
$selectorResult = & $PlanSelector $PlanId 2>&1
} catch {
$selectorResult = $_
$global:LASTEXITCODE = 1
}
if ($LASTEXITCODE -eq 0) {
$pointerSet = $true
break
}
# Another writer can replace the pointer between the selector's
# Get-Item and final-path check. Retry only that transient result.
$transientPointerRace = $selectorResult -is [System.Management.Automation.ErrorRecord] -and
$selectorResult.Exception.Message -ceq
'Error: could not set the active plan pointer: the active plan pointer became unsafe during replacement'
if ($attempt -eq 5 -or -not $transientPointerRace) {
break
}
Start-Sleep -Milliseconds 50
$global:LASTEXITCODE = 0
try {
& $PlanSelector -VerifyRoot *> $null
} catch {
$global:LASTEXITCODE = 1
}
if ($LASTEXITCODE -ne 0) { break }
}
if (-not $pointerSet) {
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!"
@@ -350,42 +423,94 @@ if ($Mode -ne "") {
# (c) auto-attest (attestation default-on in v3 modes, security strand rec 1).
# attest-plan.ps1 intentionally refuses non-Windows hosts because its secure
# no-follow implementation uses Win32 handles. On Unix, use the POSIX
# attester instead. Bind slug mode to the plan we just created so an
# inherited PLAN_ID cannot redirect attestation to another plan.
# 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 $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 {
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) {
$AttestPs1 = Join-Path $ScriptDir "attest-plan.ps1"
if (Test-Path -LiteralPath $AttestPs1) {
& $AttestPs1 *> $null
$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 {
$AttestSh = Join-Path $ScriptDir "attest-plan.sh"
$AttestationCommand = "attest-plan.sh"
$AttestSh = Join-Path $ScriptDir $AttestationCommand
$Sh = Get-Command sh -ErrorAction SilentlyContinue
if ($Sh -and (Test-Path -LiteralPath $AttestSh)) {
& $Sh.Path $AttestSh *> $null
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)"
}
}
@@ -103,6 +103,7 @@ slugify() {
# Lowercase, non-alphanumerics → '-', collapse repeats, trim leading/trailing '-'
printf '%s' "$1" \
| tr '[:upper:]' '[:lower:]' \
| tr '\r\n' '--' \
| sed -e 's/[^a-z0-9]/-/g' -e 's/-\{2,\}/-/g' -e 's/^-//' -e 's/-$//' \
| cut -c1-40
}
@@ -185,6 +186,10 @@ apply_v3_mode() {
_mode_plan="$2"
[ -z "$MODE" ] && return 0
ATTESTATION_OK=0
ATTESTATION_COMMAND="attest-plan.sh"
ATTESTATION_REASON="task_plan.md was not available for attestation"
# (a) reset the gate block counter and drop any stale gate ledger so a prior
# run's high block count cannot let the next run stop instantly.
printf '0\n' > "${_mode_dir}/.stop_blocks"
@@ -202,12 +207,61 @@ apply_v3_mode() {
# (c) auto-attest the plan (attestation default-on in v3 modes, security
# strand rec 1). attest-plan.sh resolves the same way init-session just
# pinned things: in slug mode PLAN_ID points at this plan dir; in legacy
# mode it is empty and the script falls back to ./task_plan.md at root.
# Run from the project root (CWD here) so both resolutions land.
_attest="${SCRIPT_DIR}/attest-plan.sh"
if [ -f "${_attest}" ] && [ -f "${_mode_plan}" ]; then
PLAN_ID="${PLAN_ID:-}" sh "${_attest}" >/dev/null 2>&1 || true
# pinned things. Slug mode binds both selectors to the plan that was
# just created, so an inherited PWF_PLAN_ROOT or PLAN_ID 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. Run from the project root (CWD here) so both
# resolutions land.
_attest="${SCRIPT_DIR}/${ATTESTATION_COMMAND}"
if [ ! -f "${_attest}" ]; then
ATTESTATION_REASON="${ATTESTATION_COMMAND} was not found beside init-session.sh"
return 0
fi
if [ ! -f "${_mode_plan}" ]; then
return 0
fi
if [ "$SLUG_MODE" -eq 1 ]; then
if _attest_output="$(PWF_PLAN_ROOT="$PWD" PLAN_ID="${PLAN_ID}" sh "${_attest}" 2>&1)"; then
ATTESTATION_OK=1
ATTESTATION_REASON=""
return 0
else
_attest_rc=$?
fi
else
if _attest_output="$(PWF_PLAN_ROOT="" PLAN_ID="" sh "${_attest}" 2>&1)"; then
ATTESTATION_OK=1
ATTESTATION_REASON=""
return 0
else
_attest_rc=$?
fi
fi
_attest_reason="$(
printf '%s\n' "${_attest_output}" |
sed -n '/[^[:space:]]/ { s/[[:space:]][[:space:]]*/ /g; s/^ //; s/ $//; p; q; }' |
cut -c1-300
)"
if [ -n "${_attest_reason}" ]; then
ATTESTATION_REASON="${_attest_reason}"
else
ATTESTATION_REASON="${ATTESTATION_COMMAND} exited with code ${_attest_rc}"
fi
return 0
}
print_v3_mode_status() {
_status_dir="$1"
_marker="$(cat "${_status_dir}/.mode")"
if [ "${ATTESTATION_OK:-0}" -eq 1 ]; then
printf 'Mode: %s (attested, gate counter reset)\n' "${_marker}"
else
printf 'Mode: %s (NOT attested: %s; run %s before the first hook fire)\n' \
"${_marker}" "${ATTESTATION_REASON:-attestation failed}" "${ATTESTATION_COMMAND:-attest-plan.sh}"
fi
}
@@ -422,7 +476,7 @@ if [ "$SLUG_MODE" -eq 1 ]; then
echo "Pin this terminal to the plan for parallel sessions:"
echo " export PLAN_ID=$PLAN_ID"
if [ -n "$MODE" ]; then
echo "Mode: $(cat "${PLAN_DIR}/.mode") (attested, gate counter reset)"
print_v3_mode_status "${PLAN_DIR}"
fi
else
PROJECT_NAME="${PROJECT_NAME:-project}"
@@ -433,6 +487,6 @@ else
echo "Planning files initialized!"
echo "Files: task_plan.md, findings.md, progress.md"
if [ -n "$MODE" ]; then
echo "Mode: $(cat "$(pwd)/.mode") (attested, gate counter reset)"
print_v3_mode_status "$(pwd)"
fi
fi
@@ -139,6 +139,24 @@ function Test-WithinRoot {
return $candNorm.StartsWith($rootNorm + [System.IO.Path]::DirectorySeparatorChar, [System.StringComparison]::OrdinalIgnoreCase)
}
# A linked plan directory (symlink or junction) is never selectable: not by
# PLAN_ID, not by the pointer, not by the newest scan, and it never counts
# (#270). This is `[ -L ]` of resolve-plan-dir.sh and is_link of the Python
# twin: LinkType names symlinks and junctions only. The ReparsePoint
# attribute alone would also match OneDrive Files On-Demand placeholders,
# which every synced directory and file carries and which are not links to
# sh. The same predicate guards the pointer file below (#275).
function Test-LinkedDirectory {
param($PathOrItem)
if ($PathOrItem -is [string]) {
$item = Get-Item -LiteralPath $PathOrItem -Force -ErrorAction SilentlyContinue
} else {
$item = $PathOrItem
}
if (-not $item) { return $false }
return ([string]$item.LinkType) -in @('SymbolicLink', 'Junction')
}
$activeFile = Join-Path $PlanRoot ".active_plan"
# A set PLAN_ID is a BINDING, not a hint (issue #237). A selector that names
@@ -158,6 +176,9 @@ if (-not $env:PLAN_ID) {
}
if (Test-Path -LiteralPath $PlanRoot -PathType Container) {
foreach ($entry in (Get-ChildItem -LiteralPath $PlanRoot -Directory -ErrorAction SilentlyContinue)) {
# A linked plan directory (symlink, junction) is not selectable and
# never counts, matching `[ -L ]` in resolve-plan-dir.sh (#270).
if (Test-LinkedDirectory $entry) { continue }
if ((Test-ValidSlug $entry.Name) -and
(Test-Path -LiteralPath (Join-Path $entry.FullName "task_plan.md") -PathType Leaf)) {
$planCount++
@@ -175,7 +196,7 @@ if ($planCount -gt 1) { exit 0 }
if ($env:PLAN_ID) {
if (Test-ValidSlug $env:PLAN_ID) {
$candidate = Join-Path $PlanRoot $env:PLAN_ID
if ((Test-Path -LiteralPath $candidate -PathType Container) -and (Test-WithinRoot $candidate)) {
if ((Test-Path -LiteralPath $candidate -PathType Container) -and -not (Test-LinkedDirectory $candidate) -and (Test-WithinRoot $candidate)) {
Write-Output $candidate
exit 0
}
@@ -185,12 +206,14 @@ if ($env:PLAN_ID) {
# Get-Item observes the link object even when its target is missing, unlike
# Test-Path which follows the target. An active pointer that is a directory or
# reparse point is an unsafe/ambiguous selector and must terminate resolution;
# a symlink is an unsafe/ambiguous selector and must terminate resolution;
# falling through would silently select and expose the newest unrelated plan.
# LinkType, not the ReparsePoint attribute: OneDrive Files On-Demand marks
# every synced file as a reparse point, and such a pointer is a plain file
# to every other route (#275).
$activeItem = Get-Item -LiteralPath $activeFile -Force -ErrorAction SilentlyContinue
if ($activeItem) {
if ($activeItem.PSIsContainer -or
(($activeItem.Attributes -band [IO.FileAttributes]::ReparsePoint) -ne 0)) {
if ($activeItem.PSIsContainer -or (Test-LinkedDirectory $activeItem)) {
exit 0
}
# Get-Content -Raw returns $null for a zero-byte pointer; an empty pointer
@@ -198,7 +221,7 @@ if ($activeItem) {
$planId = "$(Get-Content -LiteralPath $activeFile -Raw -ErrorAction SilentlyContinue)".Trim()
if ($planId -and (Test-ValidSlug $planId)) {
$candidate = Join-Path $PlanRoot $planId
if ((Test-Path -LiteralPath $candidate -PathType Container) -and (Test-WithinRoot $candidate)) {
if ((Test-Path -LiteralPath $candidate -PathType Container) -and -not (Test-LinkedDirectory $candidate) -and (Test-WithinRoot $candidate)) {
Write-Output $candidate
exit 0
}
@@ -211,6 +234,7 @@ if ($activeItem) {
if (Test-Path -LiteralPath $PlanRoot -PathType Container) {
$latest = Get-ChildItem -LiteralPath $PlanRoot -Directory |
Where-Object { -not $_.Name.StartsWith('.') } |
Where-Object { -not (Test-LinkedDirectory $_) } |
Where-Object { Test-ValidSlug $_.Name } |
Where-Object { Test-Path -LiteralPath (Join-Path $_.FullName "task_plan.md") -PathType Leaf } |
Where-Object { Test-WithinRoot $_.FullName } |
@@ -246,10 +246,16 @@ mtime_of() {
printf "0\n"
}
# A linked plan directory (symlink or junction; `-L` sees both under Git
# Bash) is never selectable: not by PLAN_ID, not by the pointer, not by the
# newest-mtime scan, and it never counts below (#270). Containment alone let
# a link that stays inside the root be selected while the counter skipped
# it, so one real plan plus a newer linked one became an mtime guess again.
resolve_from_env() {
plan_id="${PLAN_ID:-}"
slug_is_valid "${plan_id}" || return 1
candidate="${PLAN_ROOT}/${plan_id}"
[ -L "${candidate}" ] && return 1
if [ -d "${candidate}" ] && is_within_root "${candidate}"; then
printf "%s\n" "${candidate}"
return 0
@@ -268,6 +274,7 @@ resolve_from_active_file() {
esac
slug_is_valid "${plan_id}" || return 1
candidate="${PLAN_ROOT}/${plan_id}"
[ -L "${candidate}" ] && return 1
if [ -d "${candidate}" ] && is_within_root "${candidate}"; then
printf "%s\n" "${candidate}"
return 0
@@ -288,6 +295,7 @@ resolve_latest_dir() {
case "${name}" in
.*) continue ;;
esac
[ -L "${clean}" ] && continue
slug_is_valid "${name}" || continue
[ -f "${clean}/task_plan.md" ] || continue
is_within_root "${clean}" || continue
@@ -338,8 +346,9 @@ if [ -z "${PLAN_ID:-}" ]; then
PLAN_COUNT=1
fi
for plan_candidate in "${PLAN_ROOT}"/*/task_plan.md; do
[ -f "$plan_candidate" ] || continue
plan_candidate_dir="${plan_candidate%/task_plan.md}"
[ -L "$plan_candidate_dir" ] && continue
[ -f "$plan_candidate" ] || continue
slug_is_valid "${plan_candidate_dir##*/}" || continue
PLAN_COUNT=$((PLAN_COUNT + 1))
if [ "$PLAN_COUNT" -gt 1 ]; then PLAN_AMBIGUOUS=1; break; fi
@@ -468,13 +468,16 @@ def _opencode_state_annotation(state: Any) -> str:
def _format_opencode_part(data: Dict[str, Any], session_id: str) -> Optional[Dict[str, Any]]:
"""Print-ready summary for one OpenCode part row."""
if not isinstance(data, dict):
return None
ptype = data.get('type')
short = safe_session_label(session_id)
if ptype == 'tool':
tool = (data.get('tool') or '').lower()
tool_value = data.get('tool')
tool = tool_value.lower() if isinstance(tool_value, str) else ''
state = data.get('state') or {}
input_ = state.get('input') if isinstance(state, dict) else None
input_ = input_ or {}
input_ = input_ if isinstance(input_, dict) else {}
outcome = _opencode_state_annotation(state)
if tool in ('write', 'edit'):
fp = input_.get('filePath', '')
@@ -486,7 +489,8 @@ def _format_opencode_part(data: Dict[str, Any], session_id: str) -> Optional[Dic
return {'session': short, 'summary': f"Tool bash: {cmd}{outcome}"}
return {'session': short, 'summary': f"Tool {tool}{outcome}"}
if ptype == 'text':
text = (data.get('text') or '')[:300]
text_value = data.get('text')
text = text_value[:300] if isinstance(text_value, str) else ''
if text.strip():
return {'session': short, 'summary': f"text: {text}"}
return None
@@ -577,6 +581,7 @@ def opencode_catchup(project_path: str, mode: str = 'no-history') -> None:
"""
SELECT time_created, data FROM part
WHERE session_id = ?
AND json_valid(data)
AND json_extract(data, '$.type') = 'tool'
AND lower(json_extract(data, '$.tool')) IN ('write', 'edit', 'patch')
AND (
@@ -121,9 +121,14 @@ function Test-SafeActiveFile {
param([switch]$AllowLink)
$item = Get-Item -LiteralPath $ActiveFile -Force -ErrorAction SilentlyContinue
if (-not $item) { return $false }
# Reading may follow a verified in-project link; writing must not.
# Reading may follow a verified in-project link; writing must not. A link
# is a symlink or junction by LinkType, never the bare ReparsePoint
# attribute: OneDrive Files On-Demand marks every synced file as a
# reparse point, and the pointer must stay writable there (#275).
$linked = ([string]$item.LinkType) -in @('SymbolicLink', 'Junction')
return -not $item.PSIsContainer -and
($AllowLink -or (($item.Attributes -band [IO.FileAttributes]::ReparsePoint) -eq 0)) -and
($AllowLink -or -not $linked) -and
($AllowLink -or -not $item.IsReadOnly) -and
(Test-WithinRoot $ActiveFile)
}
@@ -204,6 +209,8 @@ function Show-PlanList {
Write-Output "[active] marks the shared .active_plan pointer; listing does not bind this session."
$found = $false
foreach ($plan in (Get-ChildItem -LiteralPath $PlanRoot -Directory -ErrorAction SilentlyContinue | Sort-Object Name)) {
# A linked plan directory is never a plan (#270): no resolver selects it.
if (([string]$plan.LinkType) -in @('SymbolicLink', 'Junction')) { continue }
if (-not (Test-ValidSlug $plan.Name) -or -not (Test-WithinRoot $plan.FullName)) { continue }
$planFile = Join-Path $plan.FullName "task_plan.md"
if (-not (Test-Path -LiteralPath $planFile -PathType Leaf) -or -not (Test-WithinRoot $planFile)) { continue }
@@ -281,6 +288,11 @@ if (-not (Test-Path -LiteralPath $PlanDir -PathType Container)) {
Write-Error "Run: init-session.sh `"$PlanId`" to create it, or check .planning\ for available plans."
exit 1
}
$planDirItem = Get-Item -LiteralPath $PlanDir -Force -ErrorAction SilentlyContinue
if ($planDirItem -and (([string]$planDirItem.LinkType) -in @('SymbolicLink', 'Junction'))) {
Write-Error "Error: plan directory is a symlink or junction and no route selects it: $PlanDir"
exit 1
}
if (-not (Test-WithinRoot $PlanRoot) -or -not (Test-WithinRoot $PlanDir)) {
Write-Error "Error: plan directory must remain within the project."
exit 1
@@ -305,10 +317,23 @@ try {
$stream.Write($bytes, 0, $bytes.Length)
$stream.Flush()
} finally { $stream.Dispose() }
if ($activeItem) {
[IO.File]::Replace($tempFile, $ActiveFile, [NullString]::Value)
} else {
[IO.File]::Move($tempFile, $ActiveFile)
$maxAttempts = 20
for ($attempt = 1; $attempt -le $maxAttempts; $attempt++) {
try {
$currentActive = Get-Item -LiteralPath $ActiveFile -Force -ErrorAction SilentlyContinue
if ($currentActive) {
if (-not (Test-SafeActiveFile)) {
throw [InvalidOperationException]::new("the active plan pointer became unsafe during replacement")
}
[IO.File]::Replace($tempFile, $ActiveFile, [NullString]::Value)
} else {
[IO.File]::Move($tempFile, $ActiveFile)
}
break
} catch [IO.IOException] {
if ($attempt -eq $maxAttempts) { throw }
Start-Sleep -Milliseconds 25
}
}
} catch {
Write-Error "Error: could not set the active plan pointer: $($_.Exception.Message)"
@@ -272,6 +272,9 @@ list_plans() {
printf '%s\n' 'Available plans:'
for _dir in "${PLAN_ROOT}"/*; do
[ -d "${_dir}" ] || continue
# A linked plan directory is never a plan (#270): no resolver selects
# it, so listing it would advertise a PLAN_ID every route refuses.
[ -L "${_dir}" ] && continue
_id="${_dir##*/}"
slug_is_valid "${_id}" || continue
is_within_root "${_dir}" || continue
@@ -312,7 +315,7 @@ if [ "${1:-}" = '' ]; then
exit 1
fi
plan_id="$(current_active)"
if [ -n "${plan_id}" ] && [ -d "${PLAN_ROOT}/${plan_id}" ] && is_within_root "${PLAN_ROOT}/${plan_id}"; then
if [ -n "${plan_id}" ] && [ -d "${PLAN_ROOT}/${plan_id}" ] && [ ! -L "${PLAN_ROOT}/${plan_id}" ] && is_within_root "${PLAN_ROOT}/${plan_id}"; then
printf '%s\n' "Active plan: ${plan_id}" "Path: ${PLAN_ROOT}/${plan_id}"
elif [ -n "${plan_id}" ]; then
printf '%s\n' "Active plan pointer: ${plan_id} (directory not found or outside project - stale pointer)"
@@ -333,6 +336,10 @@ if [ ! -d "${PLAN_DIR}" ]; then
"Run: init-session.sh \"${PLAN_ID}\" to create it, or use --list to see available plans." >&2
exit 1
fi
if [ -L "${PLAN_DIR}" ]; then
printf '%s\n' "Error: plan directory is a symlink or junction and no route selects it: ${PLAN_DIR}" >&2
exit 1
fi
if ! is_within_root "${PLAN_ROOT}" || ! is_within_root "${PLAN_DIR}"; then
printf '%s\n' 'Error: plan directory is outside the project or cannot be verified.' >&2
exit 1
@@ -8,6 +8,12 @@ State the analytical question or intended deliverable in one clear sentence.
[One sentence describing the analytical objective]
## Next Step
Record the single analytical action that should happen next. Update it whenever the active phase or immediate action changes.
[The single next analytical action. Update whenever phase status changes.]
## Current Phase
Name the phase currently being worked on.
@@ -76,6 +82,6 @@ Record each distinct error, the attempt number, and the resolution. Change the a
## Notes
- Update phase status as work progresses: `pending` to `in_progress` to `complete`.
- Re-read the goal and current phase before major analytical decisions.
- Re-read the goal, next step, and current phase before major analytical decisions.
- Log errors promptly so failed approaches are not repeated.
- Record query results and visual evidence in findings.md.
@@ -1,12 +1,21 @@
from __future__ import annotations
import importlib
import json
import os
import shlex
from pathlib import Path
from typing import Any
from .hooks import post_tool_call, pre_llm_call, pre_verify
from .paths import normalize_cwd, plugin_skill_dir
from .hooks import (
WORKTREES_DIR_NAME,
launch_dir_has_planning_state,
launch_dir_notice,
post_tool_call,
pre_llm_call,
pre_verify,
)
from .paths import effective_project_root, normalize_cwd, plan_root_is_pinned, plugin_skill_dir
from .tools import (
planning_with_files_check_complete,
planning_with_files_init,
@@ -14,10 +23,25 @@ from .tools import (
)
SLASH_COMMANDS = ("pwf", "pwf-status", "plan-status")
BROKEN_PIN_MESSAGE = (
"planning-with-files: PWF_PLAN_ROOT is set but does not resolve to an absolute, "
"existing directory; nothing done."
)
def _command_cwd() -> Path:
"""Project directory for a slash command: the Hermes session cwd, else the process cwd."""
def _command_cwd() -> Path | None:
"""Project directory for a slash command.
The PWF_PLAN_ROOT pin wins, exactly as it does for the hooks, and a broken
pin returns None instead of a fallback (issue #272: on Hermes 0.21.3 the
session cwd can name the home directory, and a pinned operator must not
get a plan created or reported there). Without a pin: the Hermes session
cwd, else the process cwd. A command handler receives only its arguments,
no platform or session, so the CLI-only launch-directory rule of the hooks
cannot be applied here; the pin is the documented answer for commands.
"""
if plan_root_is_pinned():
return effective_project_root(normalize_cwd())
try:
from agent.runtime_cwd import resolve_agent_cwd
@@ -81,6 +105,8 @@ def pwf_command(raw_args: str = "") -> str:
name_parts.append(token)
index += 1
project_dir = _command_cwd()
if project_dir is None:
return BROKEN_PIN_MESSAGE
result = json.loads(
planning_with_files_init(
template=template, cwd=str(project_dir), name=" ".join(name_parts), mode=mode
@@ -97,14 +123,61 @@ def pwf_command(raw_args: str = "") -> str:
if result.get("attestation"):
lines.append(f" attested: sha256 {result['attestation'][:12]}...")
lines.append(" next: read task_plan.md, findings.md and progress.md, then fill in the goal and phases.")
if not plan_root_is_pinned():
# Issue #272: the plan just went where Hermes pointed while the launch
# directory already holds one; say so instead of leaving two plans apart.
hint = _launch_dir_hint(project_dir)
if hint:
lines.append(hint)
return "\n".join(lines)
def status_command(raw_args: str = "") -> str:
"""/pwf-status and /plan-status: compact planning state for the current project."""
project_dir = _command_cwd()
if project_dir is None:
return BROKEN_PIN_MESSAGE
payload = json.loads(planning_with_files_status(cwd=str(project_dir)))
return _format_status(payload)
report = _format_status(payload)
if not payload.get("exists") and not plan_root_is_pinned():
hint = _launch_dir_hint(project_dir)
if hint:
report = "\n".join((report, hint))
return report
def _session_cwd_is_pinned() -> bool:
"""True when Hermes pinned this context's cwd per session (``agent.runtime_cwd._SESSION_CWD``).
A pinned context runs in a multi-session backend whose process cwd is the
backend's start directory, not a launch directory, so the hint would
compare the wrong things. Prompt turns on the TUI and Desktop carry the
pin; their plugin command dispatch does not, so this is a best-effort
exemption. Read-only inspection; any failure counts as not pinned.
"""
try:
value = importlib.import_module("agent.runtime_cwd")._SESSION_CWD.get()
except Exception: # noqa: BLE001 - a host without the pin keeps the hint
return False
return isinstance(value, str) and bool(value.strip())
def _launch_dir_hint(project_dir: Path) -> str:
"""Issue #272 diagnostic for the slash commands: name the launch directory's plan.
Read-only and platform-blind (a command handler has no platform), so it is
a hint under the report, never a refusal. Worktree sessions and sessions
whose cwd Hermes pinned per session are exempt.
"""
if WORKTREES_DIR_NAME in project_dir.parts or _session_cwd_is_pinned():
return ""
try:
launch = normalize_cwd(os.getcwd())
if not launch.is_dir() or launch == project_dir or not launch_dir_has_planning_state(launch):
return ""
except (OSError, RuntimeError, ValueError):
return ""
return launch_dir_notice(project_dir, launch)
def _register_commands(ctx: Any) -> None:
+73 -58
View File
@@ -9,27 +9,22 @@ from .constants import PROGRESS_TAIL_LINES, READ_PREVIEW_LINES
from .context_frame import frame_bytes, read_regular_bytes, select_lines, verified_frame
from .hook_state import add_reminder, pop_reminders, state_key
from .paths import (
MULTIPLE_PLANS_NOTICE,
ambiguity_notice,
attestation_path_for,
effective_project_root,
multiple_plans_require_selector,
normalize_cwd,
plan_id_for,
plan_root_is_pinned,
resolve_plan,
resolve_plan_dir,
slug_is_valid,
)
from .planning_files import evaluate_gate, normalize_wall_clock
ATTACH_LEGACY = "legacy" # no .planning/sessions directory: single-session setup
ATTACH_ATTACHED = "attached" # sessions directory armed and this session holds a sentinel
ATTACH_DETACHED = "detached" # sessions directory armed, no sentinel (or unsafe directory)
SESSION_PLAN_BINDING_NOTICE = (
"[planning-with-files] Multiple plans are available while session isolation "
"is armed. Set PLAN_ID=<slug> for this session; nothing injected."
)
def _runtime_project_dir(kwargs: dict[str, Any]) -> Path | None:
"""Resolve the active Hermes project, never a cached import-time cwd.
@@ -59,6 +54,66 @@ def _runtime_project_dir(kwargs: dict[str, Any]) -> Path | None:
return effective_project_root(project)
WORKTREES_DIR_NAME = ".worktrees" # hermes -w and /worktree new place trees at <repo>/.worktrees/<name>
def launch_dir_has_planning_state(launch: Path) -> bool:
"""True when the process launch directory holds a plan, or several plans.
A plan with a nested-root conflict still counts (``explicit=True`` skips
only that check), because the question here is whether the directory the
session was started in carries planning state at all.
"""
return (
resolve_plan(launch, explicit=True)[0] is not None
or multiple_plans_require_selector(launch)
)
def launch_dir_notice(project_dir: Path, launch: Path) -> str:
"""The once-per-turn line for issue #272; the resolved root and the launch directory differ."""
return (
f"[planning-with-files] Hermes resolved {project_dir} as the working directory, "
f"but the launch directory {launch} holds a plan. Nothing injected. "
f"Pin the thread with PWF_PLAN_ROOT={launch}."
)
def _launch_dir_notice(project_dir: Path, kwargs: dict[str, Any]) -> str | None:
"""Issue #272: the resolved root holds no plan while the launch directory does.
Hermes 0.21.3 rewrites the process-global TERMINAL_CWD during the first
turn of a CLI session (``agent/relay_runtime.py`` imports ``gateway/run.py``
lazily; its import-time bridge applies the ``Path.home()`` fallback), so
``resolve_agent_cwd`` names the home directory while ``os.getcwd()`` still
names the directory the session was started in (upstream hermes-agent
#86411 and #95577). The rewrite runs before the first hook, so the adapter
cannot recover the root on its own and never switches to the launch
directory: it says why nothing was injected and names the pin.
Silent by design: platforms other than the CLI (their process cwd is not a
launch directory), Hermes worktree sessions (``hermes -w`` points
TERMINAL_CWD at ``<repo>/.worktrees/<name>`` without a chdir, which is the
intended split), a launch directory without planning state, and a launch
directory whose session isolation refuses this session anyway.
"""
if str(kwargs.get("platform", "")).strip().lower() != "cli":
return None
if WORKTREES_DIR_NAME in project_dir.parts:
return None
try:
launch = normalize_cwd(os.getcwd())
if not launch.is_dir() or launch == project_dir:
return None
if _session_attachment(launch, _session_id(kwargs)) == ATTACH_DETACHED:
return None
if not launch_dir_has_planning_state(launch):
return None
except (OSError, RuntimeError, ValueError):
return None
return launch_dir_notice(project_dir, launch)
def _session_attachment(project_dir: Path, session_id: str) -> str:
"""Opt-in isolation state once a project creates its sessions directory."""
sessions_dir = project_dir / ".planning" / "sessions"
@@ -84,50 +139,6 @@ def _session_attachment(project_dir: Path, session_id: str) -> str:
return ATTACH_DETACHED
def _is_live_plan_file(path: Path) -> bool:
try:
info = path.lstat()
except OSError:
return False
attrs = getattr(info, "st_file_attributes", 0)
return (
stat.S_ISREG(info.st_mode)
and not stat.S_ISLNK(info.st_mode)
and not attrs & getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0x400)
)
def _session_plan_requires_binding(project_dir: Path) -> bool:
"""True when an attached session must select a same-root plan by PLAN_ID."""
if os.environ.get("PLAN_ID", "").strip():
return False
candidates = 1 if _is_live_plan_file(project_dir / "task_plan.md") else 0
planning_dir = project_dir / ".planning"
try:
children = planning_dir.iterdir()
for child in children:
if not slug_is_valid(child.name):
continue
try:
info = child.lstat()
except OSError:
continue
attrs = getattr(info, "st_file_attributes", 0)
if (
not stat.S_ISDIR(info.st_mode)
or stat.S_ISLNK(info.st_mode)
or attrs & getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0x400)
):
continue
if _is_live_plan_file(child / "task_plan.md"):
candidates += 1
if candidates > 1:
return True
except (OSError, RuntimeError):
return True
return False
def _resolve_plan(project_dir: Path, *, explicit: bool = False) -> tuple[Path | None, list[str]]:
"""Active plan directory whose task_plan.md is a regular file, plus nested conflicts."""
plan_dir, conflicts = resolve_plan(project_dir, explicit=explicit)
@@ -148,7 +159,7 @@ def _session_id(kwargs: dict[str, Any]) -> str:
def _locate(
kwargs: dict[str, Any],
) -> tuple[Path | None, Path | None, list[str], str, bool]:
"""Shared front half: project, plan, conflicts, session id, binding refusal.
"""Shared front half: project, plan, conflicts, session id, selector refusal.
PWF_PLAN_ROOT selects the effective project root. PLAN_ID selects a plan
within it. A session attachment is admission only and never skips either
@@ -161,7 +172,7 @@ def _locate(
attachment = _session_attachment(project_dir, session_id)
if attachment == ATTACH_DETACHED:
return project_dir, None, [], session_id, False
if attachment == ATTACH_ATTACHED and _session_plan_requires_binding(project_dir):
if multiple_plans_require_selector(project_dir):
return project_dir, None, [], session_id, True
explicit = plan_root_is_pinned()
plan_dir, conflicts = _resolve_plan(project_dir, explicit=explicit)
@@ -213,16 +224,20 @@ def build_user_prompt_context(project_dir: Path, plan_dir: Path | None = None) -
def pre_llm_call(**kwargs: Any) -> dict[str, str] | None:
project_dir, plan_dir, conflicts, session_id, binding_required = _locate(kwargs)
project_dir, plan_dir, conflicts, session_id, selector_required = _locate(kwargs)
if project_dir is None:
return None
if plan_dir is None:
# The refusal holds in every hook; the notice is turn-scoped, so only
# this once-per-turn hook says why (same split as inject-plan.sh).
if binding_required:
return {"context": SESSION_PLAN_BINDING_NOTICE}
if selector_required:
return {"context": MULTIPLE_PLANS_NOTICE}
if conflicts:
return {"context": ambiguity_notice(conflicts)}
if not plan_root_is_pinned():
notice = _launch_dir_notice(project_dir, kwargs)
if notice:
return {"context": notice}
return None
user_message = str(kwargs.get("user_message", ""))
reminder_messages = pop_reminders(project_dir, session_id)
@@ -252,7 +267,7 @@ def post_tool_call(**kwargs: Any) -> None:
return None
else:
return None
project_dir, plan_dir, _conflicts, session_id, _binding_required = _locate(kwargs)
project_dir, plan_dir, _conflicts, session_id, _selector_required = _locate(kwargs)
if project_dir is None or plan_dir is None:
return None
message = "[planning-with-files] Update progress.md with what you just did. If a phase is now complete, update task_plan.md status."
@@ -269,7 +284,7 @@ def pre_verify(**kwargs: Any) -> dict[str, str] | None:
plan without the ``gate`` token stays advisory and this hook returns None,
so legacy and autonomous plans never hold a turn open.
"""
project_dir, plan_dir, _conflicts, _session_id, _binding_required = _locate(kwargs)
project_dir, plan_dir, _conflicts, _session_id, _selector_required = _locate(kwargs)
if project_dir is None or plan_dir is None:
return None
try:
+67 -7
View File
@@ -12,6 +12,11 @@ SKILL_DIR_NAME = "planning-with-files"
# underscore. Rejects traversal, separators, and whitespace by construction.
_SLUG_RE = re.compile(r"^[A-Za-z0-9_][A-Za-z0-9._-]*$")
_REPARSE_ATTR = getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0x400)
MULTIPLE_PLANS_NOTICE = (
"[planning-with-files] Multiple plans are available. "
"Set PLAN_ID=<slug> for this session; nothing injected."
)
MULTIPLE_PLANS_MESSAGE = "Multiple plans are available. Set PLAN_ID=<slug> to select one."
def has_skill_assets(candidate: Path) -> bool:
@@ -136,6 +141,16 @@ def _is_regular_file(path: Path) -> bool:
return stat.S_ISREG(info.st_mode)
def _is_real_dir(path: Path) -> bool:
try:
info = path.lstat()
except OSError:
return False
if stat.S_ISLNK(info.st_mode) or getattr(info, "st_file_attributes", 0) & _REPARSE_ATTR:
return False
return stat.S_ISDIR(info.st_mode)
def slug_is_valid(slug: str) -> bool:
return bool(slug) and _SLUG_RE.match(slug) is not None
@@ -197,6 +212,39 @@ def _read_active_pointer(planning_root: Path) -> str:
return lines[0] if len(lines) == 1 else ""
def count_selectable_plans(project_dir: Path) -> int:
"""Count plans exactly as inject-plan.sh does before guessing a selection.
A legacy root plan counts only after session isolation is armed. Every
contained valid slug directory with a regular task_plan.md counts. The
caller only needs to distinguish zero/one from "more than one", so stop at
two.
"""
planning_root = project_dir / ".planning"
count = 0
if _is_real_dir(planning_root / "sessions") and _is_regular_file(project_dir / "task_plan.md"):
count = 1
try:
entries = list(planning_root.iterdir())
except OSError:
return count
for entry in entries:
if not slug_is_valid(entry.name):
continue
if _slug_plan_dir(planning_root, entry.name) is None:
continue
count += 1
if count > 1:
break
return count
def multiple_plans_require_selector(project_dir: Path, *, plan_id: str | None = None) -> bool:
"""True when shared pointer/mtime guesses cannot identify this session's plan."""
requested = plan_id if plan_id is not None else os.environ.get("PLAN_ID", "").strip()
return not requested and count_selectable_plans(project_dir) > 1
def nested_live_plans(root: Path) -> list[str]:
"""Direct children whose own .planning holds a live plan (<slug>/task_plan.md).
@@ -236,17 +284,23 @@ def resolve_plan(
) -> tuple[Path | None, list[str]]:
"""Resolve the active plan directory; return it with any nested conflicts.
Precedence mirrors resolve-plan-dir.sh: an explicit plan id (the PLAN_ID
environment variable when not passed), then .planning/.active_plan, then
the newest .planning/<slug>/task_plan.md by modification time, then the
legacy root task_plan.md. Slugs are validated and the chosen directory
must stay inside .planning (no symlink or junction escape).
Precedence mirrors resolve-plan-dir.sh: a non-empty explicit plan id (the
PLAN_ID environment variable when not passed) is binding. Without one,
more than one selectable same-root plan is refused; otherwise resolution
continues through .planning/.active_plan, the newest
.planning/<slug>/task_plan.md by modification time, then the legacy root
task_plan.md. Slugs are validated and the chosen directory must stay
inside .planning (no symlink or junction escape). A linked plan directory
never counts and never resolves here; since v3.20.3 the shell family, the
Python twin, the Codex adapter and the OpenCode and DSH cores apply the
same rule (#270).
A cwd guess (pointer, newest, or legacy root) is refused when a direct
child of the root carries its own live plan (issue #212): the result is
``(None, [child names])`` so the caller can say why. ``explicit`` marks a
selection that skips that check, exactly as inject-plan.sh does for a
``PWF_PLAN_ROOT`` pin or a ``PLAN_ID`` slug.
project-root selection that skips only that nested-root check, exactly as
inject-plan.sh does for a valid ``PWF_PLAN_ROOT`` pin. It never selects one
of several same-root plans; that still requires ``PLAN_ID``.
"""
planning_root = project_dir / ".planning"
requested = plan_id if plan_id is not None else os.environ.get("PLAN_ID", "").strip()
@@ -271,6 +325,12 @@ def resolve_plan(
return explicit_dir, []
return None, []
# A shared .active_plan pointer or directory mtime cannot identify which
# same-root task this session owns. PWF_PLAN_ROOT selects the project, not
# one of its plans, so even an explicit root pin does not lift this refusal.
if count_selectable_plans(project_dir) > 1:
return None, []
chosen: Path | None = None
if planning_root.is_dir() and not _is_link_or_reparse(planning_root):
pointed = _read_active_pointer(planning_root)
@@ -9,7 +9,9 @@ from typing import Any
from .constants import PLANNING_FILES, PLAN_PREVIEW_LINES, PROGRESS_TAIL_LINES
from .paths import (
MULTIPLE_PLANS_MESSAGE,
attestation_path_for,
multiple_plans_require_selector,
plan_id_for,
resolve_plan_dir,
resolve_skill_dir,
@@ -113,6 +115,46 @@ def apply_v3_mode(project_dir: Path, plan_dir: Path, mode: str) -> dict[str, Any
return {"marker": marker.strip(), "attestation": digest}
def _active_plan_pointer_error(planning_root: Path) -> str | None:
pointer = planning_root / ".active_plan"
if not pointer.exists() and not pointer.is_symlink():
return None
try:
stat = pointer.lstat()
resolved = pointer.resolve(strict=True)
resolved.relative_to(planning_root.resolve(strict=True))
except (OSError, ValueError):
return f"refusing to replace unsafe active plan pointer: {pointer}"
if pointer.is_symlink() or not pointer.is_file() or stat.st_nlink > 1:
return f"refusing to replace unsafe active plan pointer: {pointer}"
return None
def _write_active_plan(planning_root: Path, plan_id: str) -> str | None:
pointer = planning_root / ".active_plan"
unsafe = _active_plan_pointer_error(planning_root)
if unsafe:
return unsafe
temp = planning_root / f".active_plan.{os.getpid()}.{secrets.token_hex(4)}.tmp"
fd: int | None = None
try:
fd = os.open(temp, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
with os.fdopen(fd, "w", encoding="utf-8") as handle:
fd = None
handle.write(plan_id + "\n")
os.replace(temp, pointer)
return None
except OSError as exc:
return f"could not safely update active plan pointer: {exc}"
finally:
if fd is not None:
os.close(fd)
try:
temp.unlink()
except FileNotFoundError:
pass
def init_plan(
project_dir: Path,
*,
@@ -145,8 +187,13 @@ def init_plan(
planning_root.mkdir(parents=True, exist_ok=True)
plan_id = f"{_dt.date.today().isoformat()}-{slug}"
plan_dir = planning_root / plan_id
pointer_error = _active_plan_pointer_error(planning_root)
if pointer_error:
return {"ok": False, "error": pointer_error, "project_dir": str(project_dir)}
plan_dir.mkdir(exist_ok=True)
(planning_root / ".active_plan").write_text(plan_id + "\n", encoding="utf-8")
write_error = _write_active_plan(planning_root, plan_id)
if write_error:
return {"ok": False, "error": write_error, "project_dir": str(project_dir)}
else:
plan_dir = project_dir
plan_id = "root"
@@ -425,9 +472,14 @@ def evaluate_gate(project_dir: Path, plan_dir: Path) -> str | None:
def summarize_status(project_dir: Path) -> dict[str, Any]:
plan_dir = resolve_plan_dir(project_dir)
if plan_dir is None:
message = (
MULTIPLE_PLANS_MESSAGE
if multiple_plans_require_selector(project_dir)
else "No planning files found. Run planning_with_files_init first."
)
return {
"exists": False,
"message": "No planning files found. Run planning_with_files_init first.",
"message": message,
"project_dir": str(project_dir),
"files": {
"task_plan.md": False,
@@ -1,5 +1,5 @@
name: planning-with-files
version: 0.2.1
version: 0.2.2
description: Hermes adapter for persistent project planning and selected context injection. Resolves root and .planning/<slug> plans, injects the attested plan each turn, reminds after writes, and registers /pwf and /pwf-status. Optional gated mode can request continuation only through the Hermes pre_verify hook, bounded by agent.max_verify_nudges; legacy plans stay advisory. Explicit catchup modes read same-project local session records for aggregate counts or bounded replay. No network upload path.
author: planning-with-files contributors
provides_tools:
+13 -2
View File
@@ -3,7 +3,14 @@ import shutil
import subprocess
from pathlib import Path
from .paths import normalize_cwd, plan_id_for, resolve_plan_dir, resolve_skill_dir
from .paths import (
MULTIPLE_PLANS_MESSAGE,
multiple_plans_require_selector,
normalize_cwd,
plan_id_for,
resolve_plan_dir,
resolve_skill_dir,
)
from .planning_files import init_plan, phase_counts, summarize_status
@@ -49,7 +56,11 @@ def planning_with_files_check_complete(cwd: str = "") -> str:
return json.dumps(
{
"ok": False,
"error": "No task_plan.md found. Run planning_with_files_init first.",
"error": (
MULTIPLE_PLANS_MESSAGE
if multiple_plans_require_selector(project_dir)
else "No task_plan.md found. Run planning_with_files_init first."
),
"skill_root": str(skill_root),
"complete": False,
},
+1 -1
View File
@@ -2,7 +2,7 @@
name: planning-with-files
description: "Persistent file-based planning for multi-step AI-agent work. Keeps task_plan.md, findings.md, and progress.md on disk; lifecycle hooks inject selected project planning context. Automatic recovery reads project planning files only. Explicit session-catchup.py --metadata reads same-project local agent session records and emits aggregate counts only; --replay may emit bounded nonce-framed excerpts. Optional gated mode can request continuation only when the host supports it and never runs commands declared in Markdown. The skill has no network upload path. Use for research or work needing 5+ tool calls."
metadata:
version: "3.20.0"
version: "3.20.7"
hermes:
tags: [planning, long-running-tasks, context-engineering, workflow]
---
@@ -7,6 +7,8 @@ param(
[string]$Template = "default"
)
$ErrorActionPreference = "Stop"
$DATE = Get-Date -Format "yyyy-MM-dd"
# Resolve template directory (skill root is one level up from scripts/)
@@ -121,9 +121,14 @@ function Test-SafeActiveFile {
param([switch]$AllowLink)
$item = Get-Item -LiteralPath $ActiveFile -Force -ErrorAction SilentlyContinue
if (-not $item) { return $false }
# Reading may follow a verified in-project link; writing must not.
# Reading may follow a verified in-project link; writing must not. A link
# is a symlink or junction by LinkType, never the bare ReparsePoint
# attribute: OneDrive Files On-Demand marks every synced file as a
# reparse point, and the pointer must stay writable there (#275).
$linked = ([string]$item.LinkType) -in @('SymbolicLink', 'Junction')
return -not $item.PSIsContainer -and
($AllowLink -or (($item.Attributes -band [IO.FileAttributes]::ReparsePoint) -eq 0)) -and
($AllowLink -or -not $linked) -and
($AllowLink -or -not $item.IsReadOnly) -and
(Test-WithinRoot $ActiveFile)
}
@@ -204,6 +209,8 @@ function Show-PlanList {
Write-Output "[active] marks the shared .active_plan pointer; listing does not bind this session."
$found = $false
foreach ($plan in (Get-ChildItem -LiteralPath $PlanRoot -Directory -ErrorAction SilentlyContinue | Sort-Object Name)) {
# A linked plan directory is never a plan (#270): no resolver selects it.
if (([string]$plan.LinkType) -in @('SymbolicLink', 'Junction')) { continue }
if (-not (Test-ValidSlug $plan.Name) -or -not (Test-WithinRoot $plan.FullName)) { continue }
$planFile = Join-Path $plan.FullName "task_plan.md"
if (-not (Test-Path -LiteralPath $planFile -PathType Leaf) -or -not (Test-WithinRoot $planFile)) { continue }
@@ -281,6 +288,11 @@ if (-not (Test-Path -LiteralPath $PlanDir -PathType Container)) {
Write-Error "Run: init-session.sh `"$PlanId`" to create it, or check .planning\ for available plans."
exit 1
}
$planDirItem = Get-Item -LiteralPath $PlanDir -Force -ErrorAction SilentlyContinue
if ($planDirItem -and (([string]$planDirItem.LinkType) -in @('SymbolicLink', 'Junction'))) {
Write-Error "Error: plan directory is a symlink or junction and no route selects it: $PlanDir"
exit 1
}
if (-not (Test-WithinRoot $PlanRoot) -or -not (Test-WithinRoot $PlanDir)) {
Write-Error "Error: plan directory must remain within the project."
exit 1
@@ -305,10 +317,23 @@ try {
$stream.Write($bytes, 0, $bytes.Length)
$stream.Flush()
} finally { $stream.Dispose() }
if ($activeItem) {
[IO.File]::Replace($tempFile, $ActiveFile, [NullString]::Value)
} else {
[IO.File]::Move($tempFile, $ActiveFile)
$maxAttempts = 20
for ($attempt = 1; $attempt -le $maxAttempts; $attempt++) {
try {
$currentActive = Get-Item -LiteralPath $ActiveFile -Force -ErrorAction SilentlyContinue
if ($currentActive) {
if (-not (Test-SafeActiveFile)) {
throw [InvalidOperationException]::new("the active plan pointer became unsafe during replacement")
}
[IO.File]::Replace($tempFile, $ActiveFile, [NullString]::Value)
} else {
[IO.File]::Move($tempFile, $ActiveFile)
}
break
} catch [IO.IOException] {
if ($attempt -eq $maxAttempts) { throw }
Start-Sleep -Milliseconds 25
}
}
} catch {
Write-Error "Error: could not set the active plan pointer: $($_.Exception.Message)"
@@ -272,6 +272,9 @@ list_plans() {
printf '%s\n' 'Available plans:'
for _dir in "${PLAN_ROOT}"/*; do
[ -d "${_dir}" ] || continue
# A linked plan directory is never a plan (#270): no resolver selects
# it, so listing it would advertise a PLAN_ID every route refuses.
[ -L "${_dir}" ] && continue
_id="${_dir##*/}"
slug_is_valid "${_id}" || continue
is_within_root "${_dir}" || continue
@@ -312,7 +315,7 @@ if [ "${1:-}" = '' ]; then
exit 1
fi
plan_id="$(current_active)"
if [ -n "${plan_id}" ] && [ -d "${PLAN_ROOT}/${plan_id}" ] && is_within_root "${PLAN_ROOT}/${plan_id}"; then
if [ -n "${plan_id}" ] && [ -d "${PLAN_ROOT}/${plan_id}" ] && [ ! -L "${PLAN_ROOT}/${plan_id}" ] && is_within_root "${PLAN_ROOT}/${plan_id}"; then
printf '%s\n' "Active plan: ${plan_id}" "Path: ${PLAN_ROOT}/${plan_id}"
elif [ -n "${plan_id}" ]; then
printf '%s\n' "Active plan pointer: ${plan_id} (directory not found or outside project - stale pointer)"
@@ -333,6 +336,10 @@ if [ ! -d "${PLAN_DIR}" ]; then
"Run: init-session.sh \"${PLAN_ID}\" to create it, or use --list to see available plans." >&2
exit 1
fi
if [ -L "${PLAN_DIR}" ]; then
printf '%s\n' "Error: plan directory is a symlink or junction and no route selects it: ${PLAN_DIR}" >&2
exit 1
fi
if ! is_within_root "${PLAN_ROOT}" || ! is_within_root "${PLAN_DIR}"; then
printf '%s\n' 'Error: plan directory is outside the project or cannot be verified.' >&2
exit 1
@@ -8,6 +8,12 @@ State what the analysis should determine or produce in one clear sentence.
[One sentence describing the analytical objective]
## Next Step
Record the single analytical action that should happen next. Update it whenever the active phase or immediate action changes.
[The single next analytical action. Update whenever phase status changes.]
## Current Phase
Name the phase currently being worked on.
@@ -84,6 +90,6 @@ Record each distinct error, the attempt number, and the resolution. Change the a
## Notes
- Update phase status as work progresses: `pending` to `in_progress` to `complete`.
- Re-read the goal and current phase before major analytical decisions.
- Re-read the goal, next step, and current phase before major analytical decisions.
- Log errors promptly so failed approaches are not repeated.
- Record query results and visual findings in findings.md while the evidence is available.
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/skill-hook.sh\" \"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\" \"$HOME/.mastracode/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
metadata:
version: "3.20.0"
version: "3.20.7"
---
@@ -5,6 +5,8 @@ param(
[string]$ProjectName = "project"
)
$ErrorActionPreference = "Stop"
$DATE = Get-Date -Format "yyyy-MM-dd"
Write-Host "Initializing planning files for: $ProjectName"
@@ -845,7 +845,10 @@ class Injector(object):
)
raise Bail()
if plan_id:
if slug_is_valid(plan_id) and is_dir(plan_prefix + ".planning/" + plan_id):
# A linked plan directory is never selectable (#270): the same
# `[ ! -L ]` the reference applies on every branch below.
if (slug_is_valid(plan_id) and is_dir(plan_prefix + ".planning/" + plan_id)
and not is_link(plan_prefix + ".planning/" + plan_id)):
resolved = plan_prefix + ".planning/" + plan_id
scope = "scoped"
explicit = True
@@ -864,7 +867,7 @@ class Injector(object):
active = b""
if active and slug_is_valid(active):
slug = active.decode("ascii")
if is_dir(plan_prefix + ".planning/" + slug):
if is_dir(plan_prefix + ".planning/" + slug) and not is_link(plan_prefix + ".planning/" + slug):
resolved = plan_prefix + ".planning/" + slug
scope = "scoped"
if not resolved and is_dir(plan_prefix + ".planning"):
@@ -880,6 +883,8 @@ class Injector(object):
candidate = plan_prefix + ".planning/" + name
if not is_dir(candidate):
continue
if is_link(candidate):
continue
if not slug_is_valid(name):
continue
if not is_file(candidate + "/task_plan.md"):
@@ -1327,7 +1332,12 @@ def plan_is_ambiguous(plan_root, project_root, plan_id=""):
except OSError:
names = []
for name in names:
if slug_is_valid(name) and is_file(plan_root + "/" + name + "/task_plan.md"):
candidate_dir = plan_root + "/" + name
# A linked plan directory is not selectable, so it never counts (#270):
# the reference tests `[ -L "$plan_candidate_dir" ]` before `-f`.
if is_link(candidate_dir):
continue
if slug_is_valid(name) and is_file(candidate_dir + "/task_plan.md"):
count += 1
if count > 1:
return True
@@ -1364,7 +1374,7 @@ def resolve_plan_dir(env=None):
if plan_id:
if slug_is_valid(plan_id):
candidate = fs_root + "/" + plan_id
if is_dir(candidate) and within(candidate):
if is_dir(candidate) and not is_link(candidate) and within(candidate):
return found(plan_id)
return ("", "")
@@ -1382,7 +1392,7 @@ def resolve_plan_dir(env=None):
if slug_is_valid(active):
slug = active.decode("ascii")
candidate = fs_root + "/" + slug
if is_dir(candidate) and within(candidate):
if is_dir(candidate) and not is_link(candidate) and within(candidate):
return found(slug)
if is_dir(fs_root):
@@ -1398,6 +1408,8 @@ def resolve_plan_dir(env=None):
continue
if name.startswith("."):
continue
if is_link(candidate):
continue
if not slug_is_valid(name):
continue
if not is_file(candidate + "/task_plan.md"):

Some files were not shown because too many files have changed in this diff Show More