planning-with-files 3.16.0 → 3.17.1

package/extensions/planning-with-files/plan.ts

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
+import { existsSync, lstatSync, readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
 import { basename, dirname, join, sep } from "node:path";
 
 export type PlanScope = "scoped" | "root" | "none";
@@ -6,6 +6,7 @@ export type PlanScope = "scoped" | "root" | "none";
 export interface PlanPaths {
 	cwd: string;
 	scope: PlanScope;
+	selectionError?: "session-plan-ambiguous";
 	planPath?: string;
 	progressPath?: string;
 	findingsPath?: string;
@@ -14,6 +15,9 @@ export interface PlanPaths {
 	attestationCandidates: string[];
 }
 
+export const SESSION_PLAN_AMBIGUOUS_NOTICE =
+	"[planning-with-files] Multiple plans are available while session isolation is armed. Set PLAN_ID=<slug> for this session; nothing injected.";
+
 export interface PlanStatus extends PlanPaths {
 	exists: boolean;
 	closed: boolean;
@@ -73,6 +77,39 @@ function resolveNewestPlanDir(planRoot: string): string | undefined {
 // with resolve-plan-dir.sh on the same trees.
 const SLUG_RE = /^[A-Za-z0-9_][A-Za-z0-9._-]*$/;
 
+type SessionIsolationState = "absent" | "armed" | "invalid";
+
+function sessionIsolationState(cwd: string): SessionIsolationState {
+	try {
+		const sessions = lstatSync(join(cwd, ".planning", "sessions"));
+		return sessions.isDirectory() && !sessions.isSymbolicLink() ? "armed" : "invalid";
+	} catch (error) {
+		return (error as NodeJS.ErrnoException).code === "ENOENT" ? "absent" : "invalid";
+	}
+}
+
+function isSessionIsolationArmed(cwd: string): boolean {
+	return sessionIsolationState(cwd) === "armed";
+}
+
+function hasMultipleLivePlans(cwd: string, planRoot: string): boolean {
+	let count = existsSync(join(cwd, "task_plan.md")) ? 1 : 0;
+
+	try {
+		for (const entry of readdirSync(planRoot, { withFileTypes: true })) {
+			if (!entry.isDirectory() || entry.name.startsWith(".") || !SLUG_RE.test(entry.name)) continue;
+			const candidate = join(planRoot, entry.name);
+			if (!existsSync(join(candidate, "task_plan.md")) || !isWithinRoot(cwd, candidate)) continue;
+			count += 1;
+			if (count > 1) return true;
+		}
+	} catch {
+		return true;
+	}
+
+	return false;
+}
+
 // Containment (security A1.3 parity with the sh resolver): a scoped candidate
 // must canonicalize to a path under the anchor, or a symlinked/junctioned
 // slug dir could hand the hooks an arbitrary file outside the project. Fails
@@ -144,9 +181,10 @@ export function resolvePlanPaths(sessionCwd: string): PlanPaths {
 		attestationCandidates: [join(cwd, ".plan-attestation")],
 	});
 
-	const makeNone = (): PlanPaths => ({
+	const makeNone = (selectionError?: PlanPaths["selectionError"]): PlanPaths => ({
 		cwd,
 		scope: "none",
+		selectionError,
 		attestationCandidates: [join(cwd, ".plan-attestation")],
 	});
 
@@ -175,6 +213,14 @@ export function resolvePlanPaths(sessionCwd: string): PlanPaths {
 		return makeNone();
 	}
 
+	// An attachment admits a session to the project, but it does not choose one
+	// of several plans. With isolation armed, the shared pointer and newest-plan
+	// fallback would otherwise cross session boundaries. Match the canonical hook:
+	// an explicit PLAN_ID remains the only task selector in this state.
+	if (isSessionIsolationArmed(cwd) && hasMultipleLivePlans(cwd, planRoot)) {
+		return makeNone("session-plan-ambiguous");
+	}
+
 	const activePlanFile = join(planRoot, ".active_plan");
 	if (existsSync(activePlanFile)) {
 		const activePlanId = safeRead(activePlanFile).trim();
@@ -276,7 +322,8 @@ export function isPlanIncomplete(status: PlanStatus): boolean {
 
 export function isSessionAttached(cwd: string, sessionId: string | undefined): boolean {
 	const sessionsDir = join(cwd, ".planning", "sessions");
-	if (!existsSync(sessionsDir)) return true;
+	if (sessionIsolationState(cwd) === "absent") return true;
+	if (!isSessionIsolationArmed(cwd)) return false;
 	if (!sessionId) return false;
 	return existsSync(join(sessionsDir, `${sessionId}.attached`));
 }

package/extensions/planning-with-files/runtime.ts

@@ -28,6 +28,7 @@ import {
 	isPlanIncomplete,
 	isSessionAttached,
 	readPlanStatus,
+	SESSION_PLAN_AMBIGUOUS_NOTICE,
 	type PlanStatus,
 	resolveAnchor,
 } from "./plan.ts";
@@ -141,6 +142,10 @@ function isAttachedSession(ctx: ExtensionContext): boolean {
 	return isSessionAttached(anchorCwd(ctx), getSessionId(ctx));
 }
 
+function isAmbiguousSessionPlan(status: PlanStatus): boolean {
+	return status.selectionError === "session-plan-ambiguous";
+}
+
 function runCommand(cmd: string, args: string[], cwd: string): ExecResult {
 	const result = spawnSync(cmd, args, {
 		cwd,
@@ -176,13 +181,13 @@ function runSessionCatchup(cwd: string): ExecResult {
 		return { ok: false, stdout: "", stderr: `missing catchup script: ${CATCHUP_SCRIPT}` };
 	}
 
-	return runFirstSuccessful(
-		[
-			["uv", ["run", CATCHUP_SCRIPT, "--no-history", cwd]],
-			["python3", [CATCHUP_SCRIPT, "--no-history", cwd]],
-			["python", [CATCHUP_SCRIPT, "--no-history", cwd]],
-			["py", ["-3", CATCHUP_SCRIPT, "--no-history", cwd]],
-		],
+	return runFirstSuccessful(
+		[
+			["uv", ["run", CATCHUP_SCRIPT, "--no-history", cwd]],
+			["python3", [CATCHUP_SCRIPT, "--no-history", cwd]],
+			["python", [CATCHUP_SCRIPT, "--no-history", cwd]],
+			["py", ["-3", CATCHUP_SCRIPT, "--no-history", cwd]],
+		],
 		cwd,
 	);
 }
@@ -353,6 +358,10 @@ function registerCommands(pi: ExtensionAPI, state: RuntimeState): void {
 		description: "Show current planning-with-files plan status",
 		handler: async (_args, ctx) => {
 			const status = readPlanStatus(ctx.cwd);
+			if (isAmbiguousSessionPlan(status)) {
+				ctx.ui.notify(SESSION_PLAN_AMBIGUOUS_NOTICE, "warning");
+				return;
+			}
 			if (!status.exists) {
 				ctx.ui.notify("No active plan (task_plan.md not found)", "warning");
 				return;
@@ -373,6 +382,10 @@ function registerCommands(pi: ExtensionAPI, state: RuntimeState): void {
 	pi.registerCommand("plan-attest", {
 		description: "Run attest-plan helper for the active plan (--show / --clear supported)",
 		handler: async (args, ctx) => {
+			if (isAmbiguousSessionPlan(readPlanStatus(ctx.cwd))) {
+				ctx.ui.notify(SESSION_PLAN_AMBIGUOUS_NOTICE, "warning");
+				return;
+			}
 			const flags = args.trim() ? args.trim().split(/\s+/) : [];
 			const result = runAttestScript(anchorCwd(ctx), flags);
 			if (result.ok) {
@@ -404,6 +417,10 @@ function registerCommands(pi: ExtensionAPI, state: RuntimeState): void {
 		description: "Approve the active plan and enable planning-with-files hook activation",
 		handler: async (args, ctx) => {
 			const status = readPlanStatus(ctx.cwd);
+			if (isAmbiguousSessionPlan(status)) {
+				ctx.ui.notify(SESSION_PLAN_AMBIGUOUS_NOTICE, "warning");
+				return;
+			}
 			if (!status.exists) {
 				ctx.ui.notify("No active plan (task_plan.md not found)", "warning");
 				return;
@@ -455,6 +472,11 @@ function registerCommands(pi: ExtensionAPI, state: RuntimeState): void {
 			const intervalMs = maybeInterval ?? DEFAULT_LOOP_INTERVAL_MS;
 			const prompt = maybeInterval ? parts.slice(1).join(" ").trim() : parts.join(" ").trim();
 			const tickPrompt = prompt || DEFAULT_LOOP_PROMPT;
+			const initialStatus = readPlanStatus(ctx.cwd);
+			if (isAmbiguousSessionPlan(initialStatus)) {
+				ctx.ui.notify(SESSION_PLAN_AMBIGUOUS_NOTICE, "warning");
+				return;
+			}
 
 			const existing = state.loopTimersBySession.get(sessionId);
 			if (existing) clearInterval(existing);
@@ -509,11 +531,15 @@ export default function planningWithFilesExtension(pi: ExtensionAPI): void {
 			return;
 		}
 
+		const status = readPlanStatus(ctx.cwd);
+		if (isAmbiguousSessionPlan(status)) {
+			ctx.ui.setStatus(PKG_NAME, "multiple plans require PLAN_ID");
+			return;
+		}
+
 		if (["startup", "new", "resume", "fork"].includes(event.reason)) {
 			runSessionCatchup(anchorCwd(ctx));
 		}
-
-		const status = readPlanStatus(ctx.cwd);
 		if (status.exists) {
 			setPassivePlanStatus(ctx, status);
 		}
@@ -537,6 +563,15 @@ export default function planningWithFilesExtension(pi: ExtensionAPI): void {
 		if (!isAttachedSession(ctx)) return;
 
 		const status = readPlanStatus(ctx.cwd);
+		if (isAmbiguousSessionPlan(status)) {
+			return {
+				message: {
+					customType: CUSTOM_TYPE,
+					content: SESSION_PLAN_AMBIGUOUS_NOTICE,
+					display: true,
+				},
+			};
+		}
 		if (!status.exists) return;
 
 		if (!isExecutionApproved(state, ctx, status)) {
@@ -622,7 +657,7 @@ export default function planningWithFilesExtension(pi: ExtensionAPI): void {
 			}
 		}
 
-		if (!status.exists && (event.toolName === "write" || event.toolName === "edit")) {
+		if (!isAmbiguousSessionPlan(status) && !status.exists && (event.toolName === "write" || event.toolName === "edit")) {
 			ctx.ui.notify("[planning-with-files] No task_plan.md found. Create planning files first.", "warning");
 		}
 

package/package.json

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

package/scripts/attest-plan.ps1

@@ -404,6 +404,7 @@ function Resolve-PlanFile {
     $resolver = Join-Path $PSScriptRoot "resolve-plan-dir.ps1"
     if (-not (Test-Path -LiteralPath $resolver -PathType Leaf)) { return $null }
     $resolvedDir = @(& $resolver | Where-Object { $_ }) | Select-Object -First 1
+    if (-not $resolvedDir -and ((& $resolver -CheckAmbiguity) -eq "PWF_PLAN_AMBIGUOUS_V1")) { return $null }
     if ($resolvedDir) {
         $planFile = Join-Path $resolvedDir "task_plan.md"
         return (Resolve-ContainedPlanFile -Candidate $planFile -ExpectedDirectory $resolvedDir)

package/scripts/attest-plan.sh

@@ -45,6 +45,10 @@ resolve_plan_file() {
     plan_dir=""
     if [ -f "${RESOLVER}" ]; then
         plan_dir="$(sh "${RESOLVER}" 2>/dev/null)"
+        if [ -z "$plan_dir" ] && [ "$(sh "${RESOLVER}" --check-ambiguity 2>/dev/null)" = "PWF_PLAN_AMBIGUOUS_V1" ]; then
+            printf "[plan-attest] Multiple plans are available. Set PLAN_ID=<slug>; nothing was attested.\n" >&2
+            return 1
+        fi
     fi
     if [ -n "${plan_dir}" ] && [ -f "${plan_dir}/task_plan.md" ]; then
         printf "%s\n" "${plan_dir}/task_plan.md"

package/scripts/check-complete.ps1

@@ -35,6 +35,7 @@ if ($PlanFile -ne "") {
         try {
             $resolvedDir = (& $resolver 2>$null | Select-Object -First 1)
             if ($null -eq $resolvedDir) { $resolvedDir = "" }
+            if (-not $resolvedDir -and ((& $resolver -CheckAmbiguity) -eq "PWF_PLAN_AMBIGUOUS_V1")) { exit 0 }
         } catch {
             $resolvedDir = ""
         }

package/scripts/check-complete.sh

@@ -56,6 +56,9 @@ else
     RESOLVED_DIR=""
     if [ -f "${RESOLVER}" ]; then
         RESOLVED_DIR="$(sh "${RESOLVER}" 2>/dev/null)"
+        if [ -z "$RESOLVED_DIR" ] && [ "$(sh "${RESOLVER}" --check-ambiguity 2>/dev/null)" = "PWF_PLAN_AMBIGUOUS_V1" ]; then
+            exit 0
+        fi
     fi
     if [ -n "${RESOLVED_DIR}" ] && [ -f "${RESOLVED_DIR}/task_plan.md" ]; then
         PLAN_FILE="${RESOLVED_DIR}/task_plan.md"