pdd-cli 0.0.274__tar.gz → 0.0.276__tar.gz

pdd_cli-0.0.276/.pdd/meta/agentic_sync_runner_python.json

@@ -0,0 +1,21 @@
+{
+  "pdd_version": "0.0.275.dev3",
+  "timestamp": "2026-06-16T01:31:18.161464+00:00",
+  "command": "fix",
+  "prompt_hash": "0784d6ff7f749b74e6938bfdd945a1cf97aed961ebea4bf3849fe512bf7163f9",
+  "code_hash": "587d51aaed8470de39bbefbb0882f481f269431cca8b50e45b22e90dbd2eb695",
+  "example_hash": "fcb36209abb5ab882ad551754fb574d62509c968f8c564e18163be7f2b7ef35a",
+  "test_hash": "781deb083113a3c96b990501f24cdf41e0742190be5cfbe85553639c25e62e22",
+  "test_files": {
+    "test_agentic_sync_runner.py": "781deb083113a3c96b990501f24cdf41e0742190be5cfbe85553639c25e62e22"
+  },
+  "include_deps": {
+    "context/agentic_change_example.py": "a8308b2af708c804d626a4a96012c5a67f5bc6469e33857cafc07627213828d7",
+    "context/agentic_common_example.py": "f9cdb30a932973d341b795faf510056b95573610af5ac48e3849cf42c205998e",
+    "context/agentic_langtest_example.py": "dbc5c87dc1b75d3299dbfb67b17df1838f9ba2c9bdb457097df0832cea112c3f",
+    "context/agentic_test_orchestrator_example.py": "473901f6f62844c81a047fa69387c4116d91a522c62d5c6ad30188e2e99dfaa5",
+    "context/architecture_sync_example.py": "b6158dbc7ca3fd32665528562225f6739ec521a071d845acab0f7caaea221ae0",
+    "context/python_preamble.prompt": "0388ed131bf986f8752e1bc4c81e4da0460cfe2908ec8c60b1314edbab768254",
+    "context/sync_order_example.py": "b4eb1e167e7604c7dbac703bdcba7287188fa9d2d5ef6d490216d003cdc542fa"
+  }
+}

pdd_cli-0.0.276/.pdd/meta/agentic_sync_runner_python_run.json

@@ -0,0 +1,11 @@
+{
+  "timestamp": "2026-06-16T01:31:18.161464+00:00",
+  "exit_code": 0,
+  "tests_passed": 180,
+  "tests_failed": 0,
+  "coverage": 81.25,
+  "test_hash": "781deb083113a3c96b990501f24cdf41e0742190be5cfbe85553639c25e62e22",
+  "test_files": {
+    "test_agentic_sync_runner.py": "781deb083113a3c96b990501f24cdf41e0742190be5cfbe85553639c25e62e22"
+  }
+}

pdd_cli-0.0.276/.pdd/meta/durable_sync_runner_python.json

@@ -0,0 +1,18 @@
+{
+  "pdd_version": "0.0.275.dev3",
+  "timestamp": "2026-06-16T02:09:40.279393+00:00",
+  "command": "fix",
+  "prompt_hash": "607af0a8fd816de522eed6823ffa1865e52fd97893ea7a1d2c62381f3aaa1681",
+  "code_hash": "b95c3f7c268f7e91650068af248a25ad89ac9c133673c550cace9e22c4079265",
+  "example_hash": null,
+  "test_hash": "088d55daf37c57130e44c01d4e13fd2f259e2a83dba229f693aa2653abcd15dd",
+  "test_files": {
+    "test_durable_sync_runner.py": "088d55daf37c57130e44c01d4e13fd2f259e2a83dba229f693aa2653abcd15dd"
+  },
+  "include_deps": {
+    "context/agentic_sync_example.py": "9bcc2f199a1463e8c424d8210ea6d5f34ad6fb5fcb1022aa879a9ecba0f8d5d6",
+    "context/agentic_sync_runner_example.py": "fcb36209abb5ab882ad551754fb574d62509c968f8c564e18163be7f2b7ef35a",
+    "context/python_preamble.prompt": "0388ed131bf986f8752e1bc4c81e4da0460cfe2908ec8c60b1314edbab768254",
+    "context/sync_order_example.py": "b4eb1e167e7604c7dbac703bdcba7287188fa9d2d5ef6d490216d003cdc542fa"
+  }
+}

pdd_cli-0.0.276/.pdd/meta/durable_sync_runner_python_run.json

@@ -0,0 +1,11 @@
+{
+  "timestamp": "2026-06-16T02:09:40.279393+00:00",
+  "exit_code": 0,
+  "tests_passed": 24,
+  "tests_failed": 0,
+  "coverage": 80.0,
+  "test_hash": "088d55daf37c57130e44c01d4e13fd2f259e2a83dba229f693aa2653abcd15dd",
+  "test_files": {
+    "test_durable_sync_runner.py": "088d55daf37c57130e44c01d4e13fd2f259e2a83dba229f693aa2653abcd15dd"
+  }
+}

{pdd_cli-0.0.274/pdd_cli.egg-info → pdd_cli-0.0.276}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pdd-cli
-Version: 0.0.274
+Version: 0.0.276
 Summary: PDD (Prompt-Driven Development) Command Line Interface
 Author: Greg Tanaka
 Author-email: glt@alumni.caltech.edu

{pdd_cli-0.0.274 → pdd_cli-0.0.276}/README.md

@@ -1157,7 +1157,7 @@ pdd --context backend --force sync calculator # Explicit context override with v
 When a GitHub issue URL is passed instead of a basename, sync enters agentic mode:
 1. **Module Identification**: Fetches the issue content and uses an LLM to identify which modules need syncing
 2. **Dependency Validation**: Validates architecture.json dependencies and applies corrections if needed
-3. **Parallel Execution**: Dispatches parallel sync via `AsyncSyncRunner` with dependency-aware scheduling (max 4 concurrent workers)
+3. **Parallel Execution**: Dispatches parallel sync via `AsyncSyncRunner` with dependency-aware scheduling (up to 4 concurrent workers by default; set `PDD_SYNC_MAX_WORKERS` to cap concurrency lower — e.g. `1` on memory-constrained runners)
 4. **Live Progress**: Posts and updates a GitHub comment with real-time module sync status
 
 ```bash
@@ -2529,7 +2529,7 @@ The 13-step workflow:
 
 **Cross-Machine Resume**: By default, workflow state is stored in a hidden comment on the GitHub issue, enabling resume from any machine. If you start the workflow on machine A, you can continue from machine B by checking out the branch and running `pdd change` again. Use `--no-github-state` to disable this feature and use local-only state persistence. You can also set the `PDD_NO_GITHUB_STATE=1` environment variable to disable GitHub state globally.
 
-**Clean Restart** (`--clean-restart`, issue #1149): For `pdd change`, discards any persisted solving state for the issue and runs a fresh 13-step `pdd-issue` flow from the default base branch, ignoring any previously generated `change/issue-N` branch or PR. Use when recovering from a stopped or wrong-model run (e.g. you cancelled a Gemini-based run and want to rerun cleanly under Opus on the same issue). The orchestrator posts a `## Step 0/13: Workflow Startup` comment on the issue naming the mode, model, base branch, and command so reviewers can tell at a glance whether a run is resuming or clean-starting. The same restart intent is also available for `pdd bug`, `pdd test`, and `pdd fix` agentic GitHub issue workflows. Cannot be combined with `--manual`.
+**Clean Restart** (`--clean-restart`, issue #1149): For `pdd change`, discards any persisted solving state for the issue and runs a fresh 13-step `pdd-issue` flow from the default base branch, ignoring any previously generated `change/issue-N` branch or PR. Use when recovering from a stopped or wrong-model run (e.g. you cancelled a Gemini-based run and want to rerun cleanly under Opus on the same issue). The orchestrator posts a `## Step 0/13: Workflow Startup` comment on the issue naming the mode, model, base branch, and command so reviewers can tell at a glance whether a run is resuming or clean-starting. The same restart intent is also available for `pdd bug`, `pdd test`, and `pdd fix` agentic GitHub issue workflows. If the standard issue branch (`{command}/issue-N`) is checked out in another local worktree (e.g. a concurrent runner), the clean restart does not fail: it prunes stale worktree registrations and, if the branch is still genuinely locked, creates a fresh unique fallback branch (`{command}/issue-N-job-<id>`) from the base branch, pushes and opens/updates the PR on that branch, and leaves the locked worktree untouched. Cannot be combined with `--manual`.
 
 **Review Loop**: Steps 11-12 form a review loop that identifies and fixes issues iteratively. The loop runs until no issues are found (max 5 iterations).
 
@@ -3562,6 +3562,7 @@ PDD uses several environment variables to customize its behavior:
 - **`PDD_VERIFY_PROGRAM_OUTPUT_PATH`**: Default path for the final program file generated by the `verify` command.
 - **`PDD_CLOUD_TIMEOUT`**: Cloud request timeout in seconds. Default is 900 (15 minutes). Increase this value if you experience timeouts with long-running cloud operations.
 - **`PDD_MODULE_TIMEOUT_SECONDS`**: Per-module wall-clock cap for `pdd sync --agentic` runs in seconds. Default is 2700 (45 minutes).
+- **`PDD_SYNC_MAX_WORKERS`**: Maximum number of modules `pdd sync` (agentic and durable issue sync) runs concurrently. Default is 4; values are clamped to the range 1–4 (non-integer values fall back to 4). Lower it (e.g. `PDD_SYNC_MAX_WORKERS=1`) to reduce peak memory on constrained runners such as Cloud Run. A sync given an explicit `--budget` always runs sequentially regardless of this value; durable runs honor an explicit `--durable-max-parallel` over this default.
 - **`PDD_AUTO_SUBMIT_AUTH_TIMEOUT_S`**: Timeout in seconds for the JWT auth call used by `pdd sync` / `pdd fix --auto-submit` example submission. Default is 300 (5 minutes). Auto-submit is skipped automatically when running inside a Cloud Run / Cloud Functions executor.
 
 ### Configuration Priority

{pdd_cli-0.0.274 → pdd_cli-0.0.276}/architecture.json

@@ -2218,9 +2218,15 @@
     }
   },
   {
-    "reason": "Determines needed dependencies and inserts them into a prompt with optional deduplication.",
+    "reason": "Determines needed dependencies via auto_include and inserts them into a prompt, handling both new and updated includes.",
     "description": "Adds <include> tags for dependencies. Supports auto-dependency detection.",
-    "dependencies": [],
+    "dependencies": [
+      "llm_invoke_python.prompt",
+      "load_prompt_template_python.prompt",
+      "auto_include_python.prompt",
+      "preprocess_python.prompt",
+      "path_resolution_python.prompt"
+    ],
     "priority": 60,
     "filename": "insert_includes_python.prompt",
     "filepath": "pdd/insert_includes.py",
@@ -2234,19 +2240,8 @@
         "functions": [
           {
             "name": "insert_includes",
-            "signature": "(input_prompt: str, directory_path: str, csv_filename: str, prompt_filename: Optional[str] = None, strength: float = DEFAULT_STRENGTH, temperature: float = 0.0, time: float = DEFAULT_TIME, verbose: bool = False, progress_callback: Optional[Callable[[int, int], None]] = None, include_docs: bool = False, max_workers: int = 1, dedup: bool = True)",
-            "returns": "Tuple[str, str, float, str]",
-            "sideEffects": [
-              "None"
-            ]
-          },
-          {
-            "name": "main",
-            "signature": "()",
-            "returns": "None",
-            "sideEffects": [
-              "None"
-            ]
+            "signature": "(input_prompt: str, directory_path: str, csv_filename: str, prompt_filename: Optional[str] = None, strength: float = DEFAULT_STRENGTH, temperature: float = 0.0, time: float = DEFAULT_TIME, verbose: bool = False, progress_callback: Optional[Callable[[int, int], None]] = None, include_docs: bool = False, max_workers: int = 1, dedup: bool = True, compress: bool = False)",
+            "returns": "Tuple[str, str, float, str]"
           }
         ]
       }
@@ -5113,9 +5108,13 @@
     }
   },
   {
-    "reason": "Applies targeted patches to existing code based on prompt changes.",
+    "reason": "Analyzes prompt changes and incrementally patches existing code or triggers full regeneration.",
     "description": "Detects changes between prompt versions and generates minimal code patches. More efficient than full regeneration for small modifications.",
-    "dependencies": [],
+    "dependencies": [
+      "llm_invoke_python.prompt",
+      "preprocess_python.prompt",
+      "postprocess_python.prompt"
+    ],
     "priority": 149,
     "filename": "incremental_code_generator_python.prompt",
     "filepath": "pdd/incremental_code_generator.py",
@@ -5131,10 +5130,7 @@
           {
             "name": "incremental_code_generator",
             "signature": "(original_prompt: str, new_prompt: str, existing_code: str, language: str, strength: float = DEFAULT_STRENGTH, temperature: float = 0.0, time: float = 0.25, force_incremental: bool = False, verbose: bool = False, preprocess_prompt: bool = True) -> Tuple[Optional[str], bool, float, str]",
-            "returns": "Tuple[Optional[str], bool, float, str]",
-            "sideEffects": [
-              "None"
-            ]
+            "returns": "Tuple[Optional[str], bool, float, str]"
           }
         ]
       }
@@ -5436,7 +5432,7 @@
     }
   },
   {
-    "reason": "Applies guarded incremental PRD changes to architecture.json and related prompts without full regeneration.",
+    "reason": "Incrementally propagates PRD changes into architecture.json and affected prompt Requirements using validated targeted patches.",
     "description": "Reads a PRD diff from hash/provenance metadata and ignored local raw-baseline cache, asks the LLM for a structured architecture patch, validates dependency, prompt filename, filepath, and file invariants deterministically, rejects unsafe or secret-like code filepaths before reads, retries invalid patches with explicit validation feedback, writes targeted architecture updates atomically, validates prompt previews under the write lock to avoid lost edits, syncs prompt metadata tags, creates prompts for new modules, deletes prompts for removed modules, updates prompt Requirements through detect_change/change, and avoids persisting raw PRD or GitHub issue/comment text in tracked metadata.",
     "dependencies": [
       "architecture_sync_python.prompt",
@@ -5459,13 +5455,13 @@
         "functions": [
           {
             "name": "run_incremental_prd_propagation",
-            "signature": "(prd_source: str, *, architecture_path: Path | str, prompts_dir: Path | str, project_root: Path | str | None, issue_content: Optional[str], dry_run: bool, verbose: bool, quiet: bool, strength: float, temperature: float, time: float, max_patch_attempts: int, update_prompt_requirements: bool, generate_new_prompts: bool)",
-            "returns": "Tuple[bool, str, float, str, List[str]]"
+            "signature": "(prd_source: str, *, architecture_path: Path | str = \"architecture.json\", prompts_dir: Path | str = \"prompts\", project_root: Path | str | None = None, issue_content: Optional[str] = None, dry_run: bool = False, verbose: bool = False, quiet: bool = False, strength: float = DEFAULT_STRENGTH, temperature: float = 0.0, time: float = DEFAULT_TIME, max_patch_attempts: int = 3, update_prompt_requirements: bool = True, generate_new_prompts: bool = True) -> Tuple[bool, str, float, str, List[str]]",
+            "returns": "Tuple of success flag, message, cost, model, and changed files"
           },
           {
             "name": "apply_architecture_patch",
-            "signature": "(raw_architecture: Any, patch: ArchitecturePatch)",
-            "returns": "PatchApplication"
+            "signature": "(raw_architecture: Any, patch: ArchitecturePatch) -> PatchApplication",
+            "returns": "Validated in-memory architecture patch application result"
           }
         ]
       }
@@ -7229,7 +7225,7 @@
   },
   {
     "reason": "Parallel dependency-aware sync runner that forwards compressed-context sync settings.",
-    "description": "Manages pdd sync subprocesses using ThreadPoolExecutor, preserves architecture subdirectory basenames, strips architecture filename/target language suffixes via PDD's known-language catalog so compound languages such as TypeScriptReact and JavaScriptReact resolve correctly, respects dependency ordering from architecture.json, enforces total-budget sequential execution when requested, shrinks each child/retry budget by persisted module costs plus current-module in-flight retry cost, posts live progress to GitHub issue comments with a total body cap below GitHub's comment limit, keeps unrelated ready modules running after a module failure while blocking transitive failed-dependency dependents, and stops all new scheduling when total budget is exhausted. Detects three repairable generation failures from per-module sync subprocesses — architecture-conformance ('Architecture conformance error for ' line prefix, parsed by _parse_conformance_failure), public-surface regression ('Public surface regression for ' line prefix, parsed by _parse_public_surface_failure, issue #1012), and test-churn ('Test churn threshold exceeded for ' line prefix, parsed by _parse_test_churn_failure, issue #1012) — and retries each up to MAX_CONFORMANCE_ATTEMPTS=3 with a PDD_REPAIR_DIRECTIVE env var that names the exact offending symbols / churn ratio and forbids editing architecture.json or rewriting unrelated tests. Every child/retry forwards the parent's resolved .pddrc context, --strength, and --temperature on the retry command so a flaky regeneration cannot silently switch model or context between attempts. Stops retrying before launching another repair child if the in-flight repair cost exhausts total_budget, short-circuits when the failure signature (sorted missing/removed symbols, or (rounded churn_ratio, pre_line_count)) repeats, and on hard failure records the matching structured block — '=== architecture conformance failure ===', '=== public surface regression ===', or '=== test churn threshold exceeded ===' (built by build_conformance_hard_failure_from_error / build_public_surface_hard_failure_from_error / build_test_churn_hard_failure_from_error, all importable from pdd.agentic_sync_runner so sync_main and sync_orchestration reuse them verbatim) — plus a 'Reproduce locally:' line and an '--- env ---' fingerprint (pdd.__file__, pdd --version, git SHA, dirty flag, repo-vs-site-packages) so the GitHub App surface is actionable without exceeding GitHub comment size limits.",
+    "description": "Manages pdd sync subprocesses using a ThreadPoolExecutor whose worker count is read by _read_sync_max_workers() from the PDD_SYNC_MAX_WORKERS env var at construction (default 4, non-integer falls back to 4, clamped to 1-4, forced to 1 when total_budget is set; MAX_WORKERS stays a backwards-compatible module constant), preserves architecture subdirectory basenames, strips architecture filename/target language suffixes via PDD's known-language catalog so compound languages such as TypeScriptReact and JavaScriptReact resolve correctly, respects dependency ordering from architecture.json, enforces total-budget sequential execution when requested, shrinks each child/retry budget by persisted module costs plus current-module in-flight retry cost, posts live progress to GitHub issue comments with a total body cap below GitHub's comment limit, keeps unrelated ready modules running after a module failure while blocking transitive failed-dependency dependents, and stops all new scheduling when total budget is exhausted. Detects three repairable generation failures from per-module sync subprocesses — architecture-conformance ('Architecture conformance error for ' line prefix, parsed by _parse_conformance_failure), public-surface regression ('Public surface regression for ' line prefix, parsed by _parse_public_surface_failure, issue #1012), and test-churn ('Test churn threshold exceeded for ' line prefix, parsed by _parse_test_churn_failure, issue #1012) — and retries each up to MAX_CONFORMANCE_ATTEMPTS=3 with a PDD_REPAIR_DIRECTIVE env var that names the exact offending symbols / churn ratio and forbids editing architecture.json or rewriting unrelated tests. Every child/retry forwards the parent's resolved .pddrc context, --strength, and --temperature on the retry command so a flaky regeneration cannot silently switch model or context between attempts. Stops retrying before launching another repair child if the in-flight repair cost exhausts total_budget, short-circuits when the failure signature (sorted missing/removed symbols, or (rounded churn_ratio, pre_line_count)) repeats, and on hard failure records the matching structured block — '=== architecture conformance failure ===', '=== public surface regression ===', or '=== test churn threshold exceeded ===' (built by build_conformance_hard_failure_from_error / build_public_surface_hard_failure_from_error / build_test_churn_hard_failure_from_error, all importable from pdd.agentic_sync_runner so sync_main and sync_orchestration reuse them verbatim) — plus a 'Reproduce locally:' line and an '--- env ---' fingerprint (pdd.__file__, pdd --version, git SHA, dirty flag, repo-vs-site-packages) so the GitHub App surface is actionable without exceeding GitHub comment size limits. Bounds per-attempt child stdout/stderr capture with a _BoundedTextCapture tail (capped by STDOUT_CAPTURE_LINE_LIMIT=5000 lines and STDOUT_CAPTURE_BYTE_LIMIT=1 MiB per stream, allocated fresh each attempt) so verbose repair retries cannot grow memory unbounded and trigger SIGKILL on Cloud Run; reads child pipes as bytes and decodes UTF-8 incrementally; tracks dropped line/byte counts surfaced via _log_dropped_output() and appended to failure/timeout summaries without injecting diagnostics into captured child output. The 'Overall status: ... Failed' verdict is recorded as the stdout line streams in (sticky), so a failure marker evicted from the bounded tail by trailing output still yields a failed verdict and a correct failure reason.",
     "dependencies": [
       "architecture_sync_python.prompt",
       "agentic_langtest_python.prompt",
@@ -7293,7 +7289,7 @@
   },
   {
     "reason": "Durable issue-sync execution engine that isolates each module in a dedicated git worktree and checkpoints successful module output to a durable branch.",
-    "description": "Subclass of AsyncSyncRunner used when run_agentic_sync is invoked with durable=True. Prepares a `sync/issue-<N>` durable branch (or an explicit override) and a `.pdd/worktrees/durable-issue-<N>` worktree, runs each scheduled module inside its own per-module worktree, and on success applies the module diff to the durable branch as a checkpoint commit carrying a `PDD-Sync-Checkpoint-V1: issue=<N> module=<basename>` trailer. Pushes checkpoints with bounded retries, halts further checkpointing on patch conflict or non-fast-forward push, refuses to operate on `main`/`master`/the repository default branch, ignores `.pdd/agentic_sync_state.json` for resume, and emits stdout markers (`PDD_CHECKPOINT: issue=<N> module=<m> commit=<sha> empty=<bool>`) only after a successful push.",
+    "description": "Subclass of AsyncSyncRunner used when run_agentic_sync is invoked with durable=True. Worker concurrency follows the same precedence as the parent: total_budget forces one worker, an explicit durable_max_parallel overrides, otherwise it reads the shared PDD_SYNC_MAX_WORKERS default via _read_sync_max_workers(). Prepares a `sync/issue-<N>` durable branch (or an explicit override) and a `.pdd/worktrees/durable-issue-<N>` worktree, runs each scheduled module inside its own per-module worktree, and on success applies the module diff to the durable branch as a checkpoint commit carrying a `PDD-Sync-Checkpoint-V1: issue=<N> module=<basename>` trailer. Pushes checkpoints with bounded retries, halts further checkpointing on patch conflict or non-fast-forward push, refuses to operate on `main`/`master`/the repository default branch, ignores `.pdd/agentic_sync_state.json` for resume, and emits stdout markers (`PDD_CHECKPOINT: issue=<N> module=<m> commit=<sha> empty=<bool>`) only after a successful push.",
     "dependencies": [
       "agentic_sync_runner_python.prompt"
     ],
@@ -7314,7 +7310,7 @@
             "signature": "(*, basenames: List[str], dep_graph: Dict[str, List[str]], sync_options: Dict[str, object], github_info: Optional[Dict[str, object]], issue_number: int, project_root: Path, durable_branch: Optional[str] = None, no_resume: bool = False, durable_max_parallel: Optional[int] = None, quiet: bool = False, verbose: bool = False, issue_url: Optional[str] = None, module_cwds: Optional[Dict[str, Path]] = None, initial_cost: float = 0.0)",
             "returns": "DurableSyncRunner",
             "sideEffects": [
-              "Resolves durable branch name and durable worktree path; total_budget in sync_options forces sequential scheduling, otherwise durable_max_parallel caps concurrency"
+              "Resolves durable branch name and durable worktree path; total_budget in sync_options forces sequential scheduling, else an explicit durable_max_parallel caps concurrency, else concurrency falls back to the shared PDD_SYNC_MAX_WORKERS default via agentic_sync_runner._read_sync_max_workers()"
             ]
           },
           {
@@ -7896,7 +7892,9 @@
   {
     "reason": "Module providing CI polling, log retrieval, and fix-iteration loop infrastructure for post-push CI validation.",
     "description": "Module providing CI polling, log retrieval, and fix-iteration loop infrastructure for post-push CI validation.",
-    "dependencies": [],
+    "dependencies": [
+      "agentic_common_python.prompt"
+    ],
     "priority": 221,
     "filename": "ci_validation_python.prompt",
     "filepath": "pdd/ci_validation.py",
@@ -7916,6 +7914,11 @@
               "expected_head_sha_override forces the poll to wait for a specific PR head SHA instead of _get_head_sha(cwd); used by the post-checkup CI re-validation gate where cwd's local HEAD is stale relative to the PR remote because the checkup pushed from its own worktree"
             ]
           },
+          {
+            "name": "run_github_checks_gate",
+            "signature": "(cwd, repo_owner, repo_name, pr_number, quiet, expected_head_sha=None, required_only=False)",
+            "returns": "Tuple[bool, str, str]"
+          },
           {
             "name": "post_ci_failure_comment",
             "signature": "(repo_owner, repo_name, pr_number, failures, attempts, cwd)",

{pdd_cli-0.0.274 → pdd_cli-0.0.276}/pdd/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.0.274'
-__version_tuple__ = version_tuple = (0, 0, 274)
+__version__ = version = '0.0.276'
+__version_tuple__ = version_tuple = (0, 0, 276)
 
-__commit_id__ = commit_id = 'gee6256d52'
+__commit_id__ = commit_id = 'g6c9ab157b'

{pdd_cli-0.0.274 → pdd_cli-0.0.276}/pdd/agentic_bug_orchestrator.py

@@ -15,6 +15,9 @@ from rich.console import Console
 from rich.markup import escape
 
 from .agentic_common import (
+    branch_checked_out_worktree,
+    clean_restart_fallback_branch,
+    current_worktree_branch,
     run_agentic_task,
     load_workflow_state,
     save_workflow_state,
@@ -205,16 +208,64 @@ def _setup_worktree(
 
     # Clean up branch if it exists
     reset_after_attach = False
+    fallback_branch: Optional[str] = None
     branch_exists = _branch_exists(cwd, branch_name)
     if branch_exists and (clean_restart or not resume_existing):
         success, _err = _delete_branch(cwd, branch_name)
         if success:
             branch_exists = False
         elif clean_restart:
-            return None, (
-                f"Cannot perform clean restart: local branch {branch_name!r} "
-                "could not be deleted. Remove the worktree using it, then retry."
+            # The common cause is a stale worktree registration: prune and
+            # retry the delete first (resolves it without a fallback).
+            subprocess.run(
+                ["git", "worktree", "prune"],
+                cwd=git_root, capture_output=True,
             )
+            success, _err = _delete_branch(cwd, branch_name)
+            if success:
+                branch_exists = False
+            else:
+                # Still locked. Only fall back when the branch is genuinely
+                # checked out in ANOTHER live worktree (issue #1596). Use a
+                # fresh unique fallback branch off main so the locked worktree
+                # is left untouched.
+                holder = branch_checked_out_worktree(git_root, branch_name)
+                if holder and Path(holder).resolve() != worktree_path.resolve():
+                    fallback_branch = clean_restart_fallback_branch(branch_name)
+                    # The fallback name is stable across retries of the same
+                    # job (JOB_ID-derived), so a prior attempt may have left
+                    # this branch behind after its worktree was removed. Delete
+                    # it (best effort) so we recreate it fresh from main rather
+                    # than failing `git worktree add -b` on a name clash.
+                    _delete_branch(cwd, fallback_branch)
+                    # Fetch the FALLBACK branch's own tracking ref so Step 12's
+                    # `git push --force-with-lease origin {head_branch}` has
+                    # lease info. On a same-job retry in a fresh clone,
+                    # origin/{fallback} already exists but the local tracking
+                    # ref does not — without this fetch the push is rejected
+                    # with "stale info". Best effort.
+                    fallback_lease = (
+                        f"+refs/heads/{fallback_branch}:refs/remotes/origin/{fallback_branch}"
+                    )
+                    try:
+                        subprocess.run(
+                            ["git", "fetch", "origin", fallback_lease],
+                            cwd=git_root, capture_output=True, check=True,
+                        )
+                    except subprocess.CalledProcessError:
+                        pass
+                    branch_exists = False
+                    if not quiet:
+                        console.print(
+                            f"[bold cyan]Clean restart: branch {branch_name!r} is locked by "
+                            f"worktree {holder} — creating fresh fallback branch "
+                            f"{fallback_branch!r} from main instead.[/bold cyan]"
+                        )
+                else:
+                    return None, (
+                        f"Cannot perform clean restart: local branch {branch_name!r} "
+                        "could not be deleted. Remove the worktree using it, then retry."
+                    )
         else:
             # Branch couldn't be deleted — will reuse with --force,
             # then reset to HEAD so old commits don't pollute the PR.
@@ -236,7 +287,10 @@ def _setup_worktree(
                     "(checked origin/main, origin/master, main, master). Refusing "
                     "to base the fresh bug worktree on current HEAD."
                 )
-            cmd = ["git", "worktree", "add", "-b", branch_name, str(worktree_path), base_ref]
+            # Under a #1596 fallback the canonical branch is locked by another
+            # worktree, so create the unique fallback branch instead.
+            create_branch = fallback_branch or branch_name
+            cmd = ["git", "worktree", "add", "-b", create_branch, str(worktree_path), base_ref]
         subprocess.run(
             cmd,
             cwd=git_root,
@@ -2414,6 +2468,15 @@ def run_agentic_bug_orchestrator(
                 if stage_result.returncode != 0 and not quiet:
                     console.print(f"[yellow]Warning: failed to stage {filepath}: {stage_result.stderr.strip()}[/yellow]")
 
+        # Pre-Step 12: thread the worktree's ACTUAL head branch so a #1596
+        # clean-restart fallback branch is pushed/PR'd, not the (locked)
+        # canonical name. Defaults to the canonical name → byte-identical
+        # rendered output when no fallback occurred.
+        if step_num == 12:
+            context["head_branch"] = (
+                current_worktree_branch(current_work_dir) or f"fix/issue-{issue_number}"
+            )
+
         # Load and preprocess template
         step_str = str(step_num).replace(".", "_")
         template_name = f"agentic_bug_step{step_str}_{name}_LLM"

{pdd_cli-0.0.274 → pdd_cli-0.0.276}/pdd/agentic_change_orchestrator.py

@@ -19,6 +19,9 @@ from rich.console import Console
 from rich.markup import escape
 
 from pdd.agentic_common import (
+    branch_checked_out_worktree,
+    clean_restart_fallback_branch,
+    current_worktree_branch,
     run_agentic_task,
     load_workflow_state,
     save_workflow_state,
@@ -555,6 +558,7 @@ def _setup_worktree(
                 console.print(f"[yellow]Warning: git fetch failed for {branch_name}: {stderr.strip()}[/yellow]")
 
     # Clean up local branch if it exists
+    fallback_branch: Optional[str] = None
     branch_exists = _branch_exists(cwd, branch_name)
     if branch_exists:
         success, _err = _delete_branch(cwd, branch_name)
@@ -566,11 +570,59 @@ def _setup_worktree(
             # base the fresh restart on whatever the previous run
             # left on the local change/issue-{N} branch, violating
             # the Req 15 base-ref guarantee.
-            return None, (
-                f"Cannot perform clean restart: local branch {branch_name!r} "
-                "could not be deleted (it is likely checked out in another "
-                "worktree). Remove that worktree first, then retry."
+            #
+            # The common cause is a stale worktree registration: prune
+            # and retry the delete first (resolves it without a fallback).
+            subprocess.run(
+                ["git", "worktree", "prune"],
+                cwd=git_root, capture_output=True,
             )
+            success, _err = _delete_branch(cwd, branch_name)
+            if success:
+                branch_exists = False
+            else:
+                # Still locked. Only fall back when the branch is genuinely
+                # checked out in ANOTHER live worktree (issue #1596: the
+                # GitHub App executor's). Use a fresh unique fallback branch
+                # off origin/main so the locked worktree is left untouched.
+                holder = branch_checked_out_worktree(git_root, branch_name)
+                if holder and Path(holder).resolve() != worktree_path.resolve():
+                    fallback_branch = clean_restart_fallback_branch(branch_name)
+                    # The fallback name is stable across retries of the same
+                    # job (JOB_ID-derived), so a prior attempt may have left
+                    # this branch behind after its worktree was removed. Delete
+                    # it (best effort) so we recreate it fresh from main rather
+                    # than failing `git worktree add -b` on a name clash.
+                    _delete_branch(cwd, fallback_branch)
+                    # Fetch the FALLBACK branch's own tracking ref (not the
+                    # canonical one) so Step 13's `git push --force-with-lease
+                    # origin {head_branch}` has lease info. On a same-job retry
+                    # in a fresh clone, origin/{fallback} already exists but the
+                    # local tracking ref does not — without this fetch the push
+                    # is rejected with "stale info". Best effort.
+                    fallback_lease = (
+                        f"+refs/heads/{fallback_branch}:refs/remotes/origin/{fallback_branch}"
+                    )
+                    try:
+                        subprocess.run(
+                            ["git", "fetch", "origin", fallback_lease],
+                            cwd=git_root, capture_output=True, check=True
+                        )
+                    except subprocess.CalledProcessError:
+                        pass
+                    branch_exists = False
+                    if not quiet:
+                        console.print(
+                            f"[bold cyan]Clean restart: branch {branch_name!r} is locked by "
+                            f"worktree {holder} — creating fresh fallback branch "
+                            f"{fallback_branch!r} from main instead.[/bold cyan]"
+                        )
+                else:
+                    return None, (
+                        f"Cannot perform clean restart: local branch {branch_name!r} "
+                        "could not be deleted (it is likely checked out in another "
+                        "worktree). Remove that worktree first, then retry."
+                    )
 
     # Resolve base ref once. Under clean_restart, refuse to silently
     # use the literal "HEAD" fallback (the user's CURRENT branch) —
@@ -606,9 +658,12 @@ def _setup_worktree(
             if not quiet:
                 console.print(f"[blue]Reusing remote branch {branch_name} (preserving prior changes)[/blue]")
         else:
-            # No prior work — create new branch from main
+            # No prior work — create new branch from main. Under a #1596
+            # fallback the canonical branch is locked by another worktree, so
+            # create the unique fallback branch instead.
+            create_branch = fallback_branch or branch_name
             subprocess.run(
-                ["git", "worktree", "add", "-b", branch_name, str(worktree_path), base_ref],
+                ["git", "worktree", "add", "-b", create_branch, str(worktree_path), base_ref],
                 cwd=git_root, capture_output=True, check=True
             )
             if clean_restart and not quiet:
@@ -1682,21 +1737,33 @@ def _build_dependency_context(prompts_dir: Path, quiet: bool = False) -> str:
 def _check_existing_pr(repo_owner: str, repo_name: str, issue_number: int) -> Optional[str]:
     """Check if an open PR already exists for this issue's branch.
 
-    Returns the PR URL if found, None otherwise.
+    Matches the canonical ``change/issue-{N}`` head AND any
+    ``change/issue-{N}-job-*`` clean-restart fallback head (issue #1596), so a
+    later normal run does not open a duplicate PR for a fallback branch.
+    Returns the PR URL if found, else None.
+
+    GitHub's ``head:`` search is a PREFIX match, so ``head:change/issue-{N}``
+    also returns unrelated heads like ``change/issue-{N}0``; the results are
+    filtered precisely in Python.
     """
-    branch = f"change/issue-{issue_number}"
+    canonical = f"change/issue-{issue_number}"
+    fallback_prefix = f"{canonical}-job-"
     try:
         result = subprocess.run(
             ["gh", "pr", "list", "--repo", f"{repo_owner}/{repo_name}",
-             "--search", f"head:{branch}", "--state", "open",
-             "--json", "url", "--limit", "1"],
+             "--search", f"head:{canonical}", "--state", "open",
+             "--json", "url,headRefName", "--limit", "30"],
             capture_output=True, text=True, check=False, timeout=30,
         )
         if result.returncode != 0:
             return None
         data = json.loads(result.stdout)
-        if data and isinstance(data, list) and data[0].get("url"):
-            return data[0]["url"]
+        if data and isinstance(data, list):
+            for pr in data:
+                head = pr.get("headRefName", "")
+                if head == canonical or head.startswith(fallback_prefix):
+                    if pr.get("url"):
+                        return pr["url"]
     except (subprocess.TimeoutExpired, json.JSONDecodeError, Exception):
         pass
     return None
@@ -2835,6 +2902,12 @@ def run_agentic_change_orchestrator(
         context["base_branch"] = _normalize_pr_base_branch(
             _resolve_main_ref_name(git_root_for_pr_base)
         )
+        # Thread the worktree's ACTUAL head branch so a #1596 clean-restart
+        # fallback branch is pushed/PR'd, not the (locked) canonical name.
+        # Defaults to the canonical name → byte-identical when no fallback.
+        context["head_branch"] = (
+            current_worktree_branch(current_work_dir) or f"change/issue-{issue_number}"
+        )
         if not quiet: console.print("[bold][Step 13/13][/bold] Create PR and link to issue...")
         s13_template = load_prompt_template("agentic_change_step13_create_pr_LLM")
         # Preprocess to escape curly braces in included content

{pdd_cli-0.0.274 → pdd_cli-0.0.276}/pdd/agentic_common.py

@@ -7,6 +7,7 @@ import os
 import signal
 import sys
 import json
+import secrets
 import shutil
 import subprocess
 import tempfile
@@ -1252,6 +1253,77 @@ def classify_step_output(
         return TokenMatch(tier="llm_classification_error", token="CLASSIFICATION_ERROR")
 
 
+def branch_checked_out_worktree(git_root: Path, branch_name: str) -> Optional[str]:
+    """Return the path of a LIVE worktree that currently has ``branch_name``
+    checked out, or ``None``. Parses ``git worktree list --porcelain`` so the
+    check does not depend on locale-specific ``git branch -D`` stderr text.
+
+    Only a worktree that genuinely holds the branch should trigger the issue
+    #1596 fallback. A stanza marked ``prunable`` (stale registration) or whose
+    path no longer exists on disk MUST NOT count — pruning + retrying the
+    delete clears those, so treating them as a lock would force a needless
+    fallback branch."""
+    try:
+        result = subprocess.run(
+            ["git", "worktree", "list", "--porcelain"],
+            cwd=git_root, capture_output=True, text=True, check=True,
+        )
+    except (subprocess.CalledProcessError, OSError):
+        return None
+    target = f"refs/heads/{branch_name}"
+    # Stanzas are separated by blank lines; the final stanza may have no
+    # trailing blank line. Append one so the flush logic is uniform.
+    path: Optional[str] = None
+    branch: Optional[str] = None
+    prunable = False
+    for line in result.stdout.splitlines() + [""]:
+        if line.startswith("worktree "):
+            path = line[len("worktree "):].strip()
+        elif line.startswith("branch "):
+            branch = line[len("branch "):].strip()
+        elif line == "prunable" or line.startswith("prunable "):
+            prunable = True
+        elif line == "":
+            # End of a stanza — evaluate it.
+            if (
+                path is not None
+                and branch == target
+                and not prunable
+                and Path(path).exists()
+            ):
+                return path
+            path = None
+            branch = None
+            prunable = False
+    return None
+
+
+def clean_restart_fallback_branch(branch_name: str) -> str:
+    """Unique fallback branch name for a clean restart when ``branch_name`` is
+    locked by another worktree (issue #1596). Prefers the executor job id
+    (``JOB_ID`` / ``PDD_JOB_ID`` env) so the name — and therefore the PR — is
+    stable across retries of the same job; otherwise a random token."""
+    raw = os.environ.get("JOB_ID") or os.environ.get("PDD_JOB_ID") or ""
+    slug = re.sub(r"[^A-Za-z0-9]", "", raw)[:8]
+    if not slug:
+        slug = secrets.token_hex(4)  # 8 hex chars
+    return f"{branch_name}-job-{slug}"
+
+
+def current_worktree_branch(cwd: Path) -> Optional[str]:
+    """Return the current branch name of the git worktree at ``cwd``, or
+    ``None`` if detached/unresolvable."""
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "--abbrev-ref", "HEAD"],
+            cwd=cwd, capture_output=True, text=True, check=True,
+        )
+    except (subprocess.CalledProcessError, OSError):
+        return None
+    branch = result.stdout.strip()
+    return branch if branch and branch != "HEAD" else None
+
+
 def substitute_template_variables(
     template: Any,
     context: Dict[str, Any],