wade-cli 1.2.6__tar.gz → 1.2.7__tar.gz

{wade_cli-1.2.6 → wade_cli-1.2.7}/CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Conventional Commits](https://conventionalcommits.org/).
 
+## [v1.2.7] — 2026-09-25
+
+### Bug Fixes
+
+- preserve and recover completed handoffs after filesystem access denial (#516) (dc83f62)
+
 ## [v1.2.6] — 2026-09-23
 
 ### Chores

{wade_cli-1.2.6 → wade_cli-1.2.7}/KNOWLEDGE.ratings.jsonl

@@ -190,3 +190,5 @@
 {"dir": "up", "event_id": "66056751a7824f6bb780f4974e2e2d7d", "id": "b08abb58", "ts": "2026-09-15T15:24:18.781881+00:00"}
 {"dir": "up", "event_id": "86b45a2f2bf74f0c8736e3ce9c7a7642", "id": "40a26d7cfd61", "ts": "2026-09-15T15:24:18.938217+00:00"}
 {"dir": "stale", "event_id": "86da7ec333234953869f880b857ce682", "id": "6cd9b543", "ts": "2026-09-15T15:24:19.088735+00:00"}
+{"dir": "up", "event_id": "5bf57cae39ae477f9295c18a3ac6d6c9", "id": "7c6526983755", "ts": "2026-09-16T22:22:59.183519+00:00"}
+{"dir": "up", "event_id": "6cccca145ffa471abd9ee11f3c2d259b", "id": "2bc8b5ab31d3", "ts": "2026-09-24T18:50:40.963016+00:00"}

{wade_cli-1.2.6 → wade_cli-1.2.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: wade-cli
-Version: 1.2.6
+Version: 1.2.7
 Summary: WADE — Workflow for AI-Driven Engineering
 Project-URL: Homepage, https://github.com/ivanviragine/wade
 Project-URL: Repository, https://github.com/ivanviragine/wade
@@ -344,6 +344,18 @@ Native terminal output is retained for recovery; usage is reported only when
 the adapter can extract it from that output. WADE's handoff ID is not a native
 CLI session ID.
 
+If the OS denies the parent access after the terminal exits, WADE reports the
+permission failure instead of calling the handoff absent, leaves the detached
+planning worktree intact, and prints a recovery command. Restore filesystem
+access, then run `wade plan --recover <planning-worktree>` from the source repo.
+Recovery does not launch an AI or regenerate content: it accepts only a retained
+registered detached worktree, then rechecks the frozen bindings, completed state,
+exact plan content, review receipts, dependencies, and plan validation before any
+task/provider write. It rejects a handoff whose original launch binding was never
+durably recorded rather than applying settings changed after collection. If even the plans directory cannot be enumerated, WADE says
+the retained plan count is unknown rather than reporting zero. WADE never changes
+OS privacy or sandbox settings for you.
+
 `wade plan --issue <N>` re-plans an existing task. If the session produces a
 single plan file, it's attached to `#N` and the task stays open. If the
 session decides the work should be split into several independent pieces

{wade_cli-1.2.6 → wade_cli-1.2.7}/README.md

@@ -308,6 +308,18 @@ Native terminal output is retained for recovery; usage is reported only when
 the adapter can extract it from that output. WADE's handoff ID is not a native
 CLI session ID.
 
+If the OS denies the parent access after the terminal exits, WADE reports the
+permission failure instead of calling the handoff absent, leaves the detached
+planning worktree intact, and prints a recovery command. Restore filesystem
+access, then run `wade plan --recover <planning-worktree>` from the source repo.
+Recovery does not launch an AI or regenerate content: it accepts only a retained
+registered detached worktree, then rechecks the frozen bindings, completed state,
+exact plan content, review receipts, dependencies, and plan validation before any
+task/provider write. It rejects a handoff whose original launch binding was never
+durably recorded rather than applying settings changed after collection. If even the plans directory cannot be enumerated, WADE says
+the retained plan count is unknown rather than reporting zero. WADE never changes
+OS privacy or sandbox settings for you.
+
 `wade plan --issue <N>` re-plans an existing task. If the session produces a
 single plan file, it's attached to `#N` and the task stays open. If the
 session decides the work should be split into several independent pieces

{wade_cli-1.2.6 → wade_cli-1.2.7}/docs/dev/architecture.md

@@ -256,6 +256,54 @@ The legacy file-presence Stop nudge is not installed; correctness depends on the
 completion and parent gates, not ambient hooks. Collected transports may exclude
 ambient settings; native terminals use their ordinary launch behavior.
 
+Parent collection uses the additive strict `safe_state` read/list API. The
+legacy API continues to collapse unsafe or unreadable state to `None` for review
+receipts, review cycles, documentation receipts, and other established callers;
+the strict path preserves `EACCES`/`EPERM` as `StateFileAccessError` while keeping
+the same descriptor-relative `O_NOFOLLOW`, regular-file, and byte-limit checks.
+An access denial after native exit causes no provider mutation and never enters
+normal worktree cleanup. Enumeration denial reports an unknown plan count and
+retains the original detached worktree. `wade plan --recover <worktree>` accepts
+only a detached worktree still registered with the current repo, skips launch,
+reloads its frozen plan manifest and explicit completed handoff, and reruns
+binding, content, review, dependency, and strict plan-validation gates before
+persistence. Successful recovery resumes the ordinary finalization and cleanup
+path; WADE does not invoke platform privacy tools or weaken sandbox policy.
+
+Recovery is idempotent because its launch binding and persistence are recorded as
+they happen. Before a managed planner launches, its worktree gets
+`.wade/plans/handoff-binding.json` (`PlanHandoffBinding`) with the resolved
+model, complete provider configuration, project task-persistence settings, and
+complete knowledge configuration. Recovery rejects a retained handoff without
+that binding rather than synthesizing one from settings that may have changed
+after collection. After collection and before any provider mutation, the worktree
+gets `.wade/plans/handoff-progress.json` (`PlanHandoffProgress`), keyed to the
+completed handoff's session id; it binds the vote set, a pending per-plan marker,
+and a per-plan-file to task-id mapping written after each issue and draft PR
+become durable. Each persisted mapping also records a digest of the exact plan
+content in its draft PR, so a later review edit rejects reuse instead of letting
+task metadata and the retained PR diverge. Recovery validates the provider
+configuration before it instantiates or uses a provider, and reuses the original
+project and knowledge settings rather than silently applying changed values. The
+vote set is bound before staging, so a revised retained artifact cannot reuse a
+previously delivered event ID with a different direction. The pending marker is
+placed in the task's initial hidden body before creation, so a post-creation
+progress-write failure can recover the exact task instead of guessing from its
+title or creating a duplicate. Before recovery renames a task to its reviewed
+plan title, it also records the original branch-forming title, so a rename whose
+response or later progress write fails still refreshes the existing draft PR
+instead of creating one from the new title. A later finalization or cleanup
+failure therefore
+leaves a retry reusing those tasks — and the original model for `planned-by`
+provenance — instead of creating duplicates; a partial finalization with a
+pending marker retains the original worktree for the same reconciliation path.
+Attaching a plan to an existing issue is idempotent for the same reason:
+`bootstrap_draft_pr` reuses the open PR, and the plan link is appended only when
+the issue body lacks it. Recovery refreshes that PR's managed plan body before
+accepting the attachment, so an approved recovery edit cannot be lost. A binding
+or progress file that is unsafe, invalid, missing required data, or bound to
+another session aborts recovery rather than being silently replaced.
+
 ## Hook Guard Layer
 
 wade installs AI-tool hooks that enforce session rules in *code* rather than

{wade_cli-1.2.6 → wade_cli-1.2.7}/docs/dev/extending.md

@@ -43,6 +43,11 @@ The provider system uses `AbstractTaskProvider` ABC (`src/wade/providers/base.py
 3. Add the provider ID to `ProviderID` enum in `models/config.py`
 4. Register the provider in `providers/__init__.py` via `register_provider(ProviderID.YOUR_ID, YourProvider)` (use a lazy loader for optional dependencies)
 
+Providers that support planning handoff recovery must also implement
+`find_tasks_by_body_marker`. It must exhaustively search the provider's open
+tasks for the exact durable marker; a bounded task-list page can miss a task
+created before a local recovery-progress write failed, causing a duplicate.
+
 Non-GitHub providers (ClickUp, Markdown) still need PRs and PR-review APIs, which are GitHub-only. They get these by composing `GitHubPRDelegateMixin` (`providers/_pr_delegate.py`), which routes PR/review calls through `gh` while task CRUD stays on the provider's own backend.
 
 ## Version Bumping

{wade_cli-1.2.6 → wade_cli-1.2.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "wade-cli"
-version = "1.2.6"
+version = "1.2.7"
 description = "WADE — Workflow for AI-Driven Engineering"
 readme = "README.md"
 license = "MIT"

{wade_cli-1.2.6 → wade_cli-1.2.7}/src/wade/__init__.py

@@ -1,3 +1,3 @@
 """WADE (Workflow for AI-Driven Engineering) — AI-agent-driven git workflow management CLI."""
 
-__version__ = "1.2.6"
+__version__ = "1.2.7"

{wade_cli-1.2.6 → wade_cli-1.2.7}/src/wade/cli/main.py

@@ -9,6 +9,7 @@ import typer
 
 import wade
 from wade.config.loader import ConfigError
+from wade.services.ai_resolution import LAUNCH_NETWORK_ACCESS
 
 app = typer.Typer(
     name="wade",
@@ -233,6 +234,11 @@ _SANDBOX_OPT = typer.Option(
 @app.command("plan", rich_help_panel="Workflow")
 def plan_cmd(
     issue: str | None = typer.Option(None, "--issue", "-i", help="Plan an existing issue by ID."),
+    recover: Path | None = typer.Option(  # noqa: B008
+        None,
+        "--recover",
+        help="Revalidate and consume a retained completed planning worktree.",
+    ),
     ai: str | None = typer.Option(
         None, "--ai", help="AI tool to use for planning.", autocompletion=complete_ai_tools
     ),
@@ -308,6 +314,7 @@ def plan_cmd(
         approval_policy=approval_policy,
         trusted_dirs=trusted_dir,
         timeout=timeout,
+        recover=recover,
     )
     raise typer.Exit(0 if success else 1)
 
@@ -620,6 +627,7 @@ def smart_start_cmd(
 @app.command("p", hidden=True)
 def plan_alias(
     issue: str | None = typer.Option(None, "--issue", "-i", help="Plan an existing issue by ID."),
+    recover: Path | None = typer.Option(None, "--recover"),  # noqa: B008
     ai: str | None = typer.Option(
         None, "--ai", help="AI tool to use for planning.", autocompletion=complete_ai_tools
     ),
@@ -640,18 +648,32 @@ def plan_alias(
     refresh_skills: bool = typer.Option(False, "--refresh-skills"),
 ) -> None:
     """Alias for plan."""
-    plan_cmd(
-        issue=issue,
-        ai=ai,
+    from wade.services.plan_service import plan as do_plan
+
+    success = do_plan(
+        ai_tool=ai,
         model=model,
+        issue_id=issue,
+        ai_explicit=ai is not None,
+        model_explicit=model is not None,
         effort=effort,
-        yolo=yolo,
+        effort_explicit=effort is not None,
+        yolo=yolo or None,
         permission_mode=permission_mode,
         sandbox=sandbox,
-        skill=skill,
-        review_skill=review_skill,
+        work_skills=skill,
+        review_skills=review_skill,
         refresh_skills=refresh_skills,
+        recover=recover,
+        # The short alias preserves the retired collector launch default, but
+        # must not turn it into an unsupported native-terminal requirement.
+        network_access=None,
+        collector_network_access=None if recover is not None else LAUNCH_NETWORK_ACCESS,
+        approval_policy="on-request",
+        trusted_dirs=None,
+        timeout=None,
     )
+    raise typer.Exit(0 if success else 1)
 
 
 @app.command("i", hidden=True)

wade_cli-1.2.7/src/wade/models/interactive_plan.py

@@ -0,0 +1,90 @@
+"""WADE-owned handoff from an ordinary native planning terminal."""
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from wade.models.config import KnowledgeConfig, ProjectSettings, ProviderConfig
+from wade.models.plan_bundle import PlanBundle, PlanKnowledgeVote
+
+
+class InteractivePlanState(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    version: Literal[1] = 1
+    session_id: str
+    tool: str
+    model: str | None = None
+    effort: str | None = None
+    sandbox: bool | None = None
+    review_required: bool
+    knowledge_required: bool = False
+    bundle_digest: str
+    bundle: PlanBundle | None = None
+    completed: bool = False
+
+
+class PlanHandoffProgress(BaseModel):
+    """Durable parent-side progress for one completed planning handoff."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    version: Literal[1] = 1
+    session_id: str
+    model: str | None = None
+    # The external task identities below are meaningful only for these exact
+    # settings. Optional fields let old retained files parse so recovery can
+    # reject their missing binding with a clear, safe error.
+    provider: ProviderConfig | None = None
+    project: ProjectSettings | None = None
+    knowledge: KnowledgeConfig | None = None
+    knowledge_required: bool | None = None
+    # The original vote set is persisted before staging any vote. This prevents
+    # a recovered artifact with the same session ID from changing a vote while
+    # retaining its already-delivered event identity.
+    knowledge_votes: tuple[PlanKnowledgeVote, ...] | None = None
+    persisted_issues: dict[str, str] = Field(default_factory=dict)
+    # Each persisted task's draft PR contains this exact plan content. Recovery
+    # must reject a reviewed edit rather than reusing the task with a stale PR.
+    persisted_plan_digests: dict[str, str] = Field(default_factory=dict)
+    # A task body carries each marker before its external creation.  If the
+    # following local progress write fails, recovery can find that exact task
+    # instead of creating a duplicate.
+    pending_issue_markers: dict[str, str] = Field(default_factory=dict)
+    # A recovered task may be renamed to match a reviewed plan after its draft
+    # PR has been created. Retain the pre-rename title that identifies that PR's
+    # branch until the task/PR mapping is durably persisted, so a retry does not
+    # derive a second branch from the new task title.
+    pending_issue_branch_titles: dict[str, str] = Field(default_factory=dict)
+    # Once every split-plan task is durable, the original task's visible
+    # supersede actions are recorded before finalization. Recovery can then
+    # resume finalization without posting the comment or closing it again.
+    superseded_issue_ids: list[str] = Field(default_factory=list)
+
+
+class PlanHandoffBinding(BaseModel):
+    """Immutable launch settings required to safely recover a completed handoff."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    version: Literal[1] = 1
+    model: str | None = None
+    provider: ProviderConfig
+    project: ProjectSettings
+    knowledge: KnowledgeConfig
+    knowledge_required: bool
+
+
+class InteractivePlanReview(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    session_id: str
+    bundle_digest: str
+    content_digest: str
+    self_review_pending: bool = False
+
+
+class InteractivePlanReviews(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    plans: dict[str, InteractivePlanReview] = Field(default_factory=dict)

{wade_cli-1.2.6 → wade_cli-1.2.7}/src/wade/providers/base.py

@@ -84,6 +84,22 @@ class AbstractTaskProvider(ABC):
     ) -> Task:
         """Update task title and/or body."""
 
+    def find_tasks_by_body_marker(
+        self,
+        marker: str,
+        label: str | None = None,
+        state: TaskState | None = TaskState.OPEN,
+    ) -> list[Task]:
+        """Exhaustively find tasks whose body contains an exact durable marker.
+
+        Implementations must not apply a caller-visible task-list limit. This is
+        used only for recovery markers, where silently missing a matching task
+        could create a duplicate external task.
+        """
+        raise NotImplementedError(
+            "This task provider cannot safely reconcile planning handoff markers"
+        )
+
     @abstractmethod
     def close_task(self, task_id: str, reason: CloseReason | None = None) -> Task:
         """Close a task, optionally with a typed reason (e.g. GitHub's "not planned").

{wade_cli-1.2.6 → wade_cli-1.2.7}/src/wade/providers/clickup.py

@@ -171,6 +171,42 @@ class ClickUpProvider(GitHubPRDelegateMixin, AbstractTaskProvider):
 
         return tasks
 
+    def find_tasks_by_body_marker(
+        self,
+        marker: str,
+        label: str | None = None,
+        state: TaskState | None = TaskState.OPEN,
+    ) -> list[Task]:
+        """Exhaustively scan the configured list for one recovery marker."""
+        matches: list[Task] = []
+        page = 0
+        while True:
+            params: dict[str, Any] = {
+                "page": str(page),
+                "subtasks": "false",
+                "include_closed": "true" if state is None or state == TaskState.CLOSED else "false",
+                "list_ids[]": self._list_id,
+            }
+            if label:
+                params["tags[]"] = label
+            data = self._client.get(
+                f"/api/v2/team/{self._team_id}/task",
+                params=params,
+            )
+            raw_tasks: list[dict[str, Any]] = data.get("tasks", [])
+            if not raw_tasks:
+                break
+            for raw in raw_tasks:
+                task = _parse_clickup_task(raw)
+                if state is not None and task.state != state:
+                    continue
+                if marker in task.body:
+                    matches.append(task)
+            if len(raw_tasks) < self._PAGE_SIZE:
+                break
+            page += 1
+        return matches
+
     def create_task(
         self,
         title: str,

{wade_cli-1.2.6 → wade_cli-1.2.7}/src/wade/providers/github.py

@@ -129,6 +129,38 @@ class GitHubProvider(AbstractTaskProvider):
         raw_list = json.loads(result.stdout)
         return [_parse_gh_task(item) for item in raw_list]
 
+    def find_tasks_by_body_marker(
+        self,
+        marker: str,
+        label: str | None = None,
+        state: TaskState | None = TaskState.OPEN,
+    ) -> list[Task]:
+        """Exhaustively scan matching GitHub issues for one recovery marker."""
+        nwo = self.get_repo_nwo()
+        state_value = "all" if state is None else state.value
+        query = f"repos/{nwo}/issues?state={state_value}&per_page=100"
+        if label:
+            query += f"&labels={quote(label, safe='')}"
+        result = run(
+            ["gh", "api", "--paginate", "--slurp", query],
+            check=True,
+            retries=3,
+        )
+        pages = json.loads(result.stdout)
+        tasks: list[Task] = []
+        for page in pages:
+            for raw in page:
+                # GitHub's REST issues endpoint includes pull requests. The
+                # issue-list command used elsewhere excludes them, so preserve
+                # that task-provider contract here too.
+                if "pull_request" in raw or marker not in (raw.get("body") or ""):
+                    continue
+                raw["url"] = raw.get("html_url", raw.get("url", ""))
+                raw["createdAt"] = raw.get("created_at")
+                raw["updatedAt"] = raw.get("updated_at")
+                tasks.append(_parse_gh_task(raw))
+        return tasks
+
     def create_task(
         self,
         title: str,

{wade_cli-1.2.6 → wade_cli-1.2.7}/src/wade/providers/markdown.py

@@ -466,6 +466,25 @@ class MarkdownIssueProvider(GitHubPRDelegateMixin, AbstractTaskProvider):
 
         return tasks
 
+    def find_tasks_by_body_marker(
+        self,
+        marker: str,
+        label: str | None = None,
+        state: TaskState | None = TaskState.OPEN,
+    ) -> list[Task]:
+        """Exhaustively scan the central Markdown file for one recovery marker."""
+        _, sections = self._load_sections()
+        matches: list[Task] = []
+        for section in sections:
+            task = _section_to_task(section)
+            if state is not None and task.state != state:
+                continue
+            if label and label not in {item.name for item in task.labels}:
+                continue
+            if marker in task.body:
+                matches.append(task)
+        return matches
+
     def create_task(
         self,
         title: str,

{wade_cli-1.2.6 → wade_cli-1.2.7}/src/wade/services/implementation_service/draft_pr.py

@@ -17,6 +17,7 @@ from wade.git.repo import GitError
 from wade.models.config import ProjectConfig
 from wade.models.task import Task
 from wade.ui.console import console
+from wade.utils.body_markers import upsert_marked_block
 
 logger = structlog.get_logger()
 
@@ -318,6 +319,8 @@ def bootstrap_draft_pr(
     config: ProjectConfig,
     repo_root: Path,
     base_branch: str | None = None,
+    refresh_existing_plan: bool = False,
+    refresh_title: str | None = None,
 ) -> dict[str, str | int] | None:
     """Create branch + push + draft PR for an issue.
 
@@ -332,6 +335,11 @@ def bootstrap_draft_pr(
         repo_root: Repository root directory.
         base_branch: When set, branch from this instead of main and target
             the PR at it (stacked PR for chain execution).
+        refresh_existing_plan: Rewrite an existing PR's managed plan body before
+            accepting a recovered task as persisted.
+        refresh_title: When refreshing a recovered task, update the existing
+            draft PR title (or use it for a newly created PR) after locating
+            the branch from ``issue_title``.
 
     Returns:
         Dict with "number" (int) and "url" (str) keys, or None on failure.
@@ -387,6 +395,26 @@ def bootstrap_draft_pr(
                     _restore_scaffold_head(repo_root, branch_name, pre_reroot_sha, existing.number)
                 return None
             console.detail(f"Retargeted PR #{existing.number} base to {base_branch}")
+        if refresh_existing_plan:
+            current_body = git_pr.get_pr_body(repo_root, existing.number)
+            if current_body is None:
+                console.error(f"Failed to read the body of draft PR #{existing.number}.")
+                return None
+            refreshed_body = (
+                upsert_marked_block(current_body, PLAN_MARKER_START, PLAN_MARKER_END, plan_body)
+                if current_body
+                else _build_draft_pr_body(plan_body, issue_number)
+            )
+            if not git_pr.update_pr_body(repo_root, existing.number, refreshed_body):
+                console.error(f"Failed to refresh the plan in draft PR #{existing.number}.")
+                return None
+        if (
+            refresh_title is not None
+            and existing.title != refresh_title
+            and not git_pr.update_pr_title(repo_root, existing.number, refresh_title)
+        ):
+            console.error(f"Failed to refresh the title in draft PR #{existing.number}.")
+            return None
         logger.info(
             "bootstrap_draft_pr.existing",
             branch=branch_name,
@@ -431,7 +459,7 @@ def bootstrap_draft_pr(
     try:
         pr_info = git_pr.create_pr(
             repo_root=repo_root,
-            title=issue_title,
+            title=refresh_title or issue_title,
             body=body,
             base=effective_base,
             head=branch_name,