[jnyross]

Summary

Lisbon family dogfood v4 (skill 0.4.4 / #13) blocked before collection: all three research workers stayed pending_setup with clientThreadId only. Frozen graph applied environment: worktree to every create_thread, including read-only research nodes. v3 used local for research and got ready threadIds.

Root cause was skill guidance that could be read as graph-level (“worktree when the graph can write”) rather than per-node.

Changes

• Per-node environment: read-only → local; writers → worktree; never global worktree because one writer exists
• Prefer root-orchestrator writes for final project-root artifacts (latent P1: report stranded in worktree)
• Pending setup: correlate by clientThreadId when listed; allow run-tag match while projectId absent during loading; chat-scale vs provisioning-scale bounds
• Validator phrases so the guidance cannot regress silently
• CHANGELOG Unreleased note

Evidence

• Lab: mac-vm-harness--codexgraph-test commit 2f51adf / candidates/frozen-lisbon-v4/
• Terminal: blocked, Required research starts failed: N2A, N2B, N2C, handles preserved

Test plan

• python3 skills/codex-graph/scripts/validate_skill.py
• node --test skills/codex-graph/scripts/task_collection_harness.test.js (14/14)
• After merge: re-run Lisbon dogfood as v5; expect research on local, fix: collect handoffs when workers finish before wait sees them #13 collection exercised, real LISBON-FAMILY-DAY.md

---

---

Note

Low Risk
Changes are limited to skill documentation, reference patterns, and validator string checks—no runtime orchestration or application code.

Overview
Fixes Lisbon dogfood v4 guidance where read-only research workers inherited a graph-wide worktree environment and stayed pending_setup with only clientThreadId.

Per-node environments: read-only nodes use local; nodes that write repo files use worktree with disjoint scopes—never worktree on every create because one writer exists. Final project-root artifacts should be written from the root orchestrator (or a single integration owner), not only inside a disposable worker worktree.

Pending setup resolution is tightened: poll with chat-scale bounds for local starts and provisioning-scale bounds for worktree; match run tags in title/summary without requiring projectId on early list rows; correlate by clientThreadId when listed. Example handle shape and findExactThread logic in task-lifecycle.md reflect this.

validate_skill.py gains required phrases so this guidance cannot regress silently; CHANGELOG records the unreleased fix.

^{Reviewed by Cursor Bugbot for commit 345a22a. Bugbot is set up for automated code reviews on this repo. Configure here.}

Summary by CodeRabbit

• New Features

  • Saved-project workflows now select execution environments per task node, using isolated workspaces for repository-writing tasks.
  • Improved task setup matching during provisioning using run tags and client thread identifiers.
  • Added guidance for coordinating disjoint writing scopes and root-owned final artifacts.

• Documentation

  • Updated task lifecycle and Code Mode guidance with environment-specific setup and polling behavior.
  • Expanded validation checks to verify the new workflow requirements.

[coderabbitai]

📝 Walkthrough

Walkthrough

The PR documents per-node task environments, strengthens pending task setup correlation, updates skill validation requirements, and adds an Unreleased changelog entry.

Changes

Task lifecycle guidance

Layer / File(s)	Summary
Per-node task environments skills/codex-graph/SKILL.md, skills/codex-graph/references/code-mode-script-patterns.md, skills/codex-graph/references/task-lifecycle.md	Read-only nodes use local environments. Repository-writing nodes use isolated worktrees. Task handles retain the selected environment.
Pending setup resolution skills/codex-graph/SKILL.md, skills/codex-graph/references/code-mode-script-patterns.md, skills/codex-graph/references/task-lifecycle.md	Pending tasks use exact project IDs when available, support run-tag matching, correlate by clientThreadId, normalize project and thread fields, and apply environment-specific polling bounds.
Validation and release documentation skills/codex-graph/scripts/validate_skill.py, CHANGELOG.md	Validation requires the new per-node, provisioning-scale, reread, and client-thread guidance. The changelog records the updates.

Estimated code review effort: 2 (Simple) | ~10 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the primary changes: per-node environment selection and pending clientThreadId resolution.
Description check	✅ Passed	The description explains the problem, changes, evidence, validation results, and planned follow-up, with only minor template differences.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/per-node-environment-pending-setup

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@skills/codex-graph/scripts/validate_skill.py`:
- Around line 178-179: Extend the validation checks in validate_skill.py for
each environment-contract mapping to require its complete clause, not just
generic phrases such as “per node” or “provisioning-scale”. Require read-only
nodes to specify local execution, repository-writing nodes to specify worktrees,
and local starts to specify chat-scale polling, covering the related checks near
the existing mapping phrase lists.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 47730d7c-85e0-4055-90e6-da3dfd2ca9d1

📥 Commits

Reviewing files that changed from the base of the PR and between 0d2c8f5 and 345a22a.

📒 Files selected for processing (5)

• CHANGELOG.md
• skills/codex-graph/SKILL.md
• skills/codex-graph/references/code-mode-script-patterns.md
• skills/codex-graph/references/task-lifecycle.md
• skills/codex-graph/scripts/validate_skill.py

[coderabbitai]

🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Require the validator to check the complete environment contract.

The new checks only require generic phrases such as per node and provisioning-scale. They do not require local execution for read-only nodes, worktrees for repository-writing nodes, or chat-scale polling for local starts. A later edit can remove these mappings and still pass validation. Add checks for each required mapping clause.

Also applies to: 211-215, 256-258

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@skills/codex-graph/scripts/validate_skill.py` around lines 178 - 179, Extend
the validation checks in validate_skill.py for each environment-contract mapping
to require its complete clause, not just generic phrases such as “per node” or
“provisioning-scale”. Require read-only nodes to specify local execution,
repository-writing nodes to specify worktrees, and local starts to specify
chat-scale polling, covering the related checks near the existing mapping phrase
lists.