fix(workspace): separate blocked roots from pull failures and nested worktrees #2633

Goal

Make basectl workspace update distinguish a safe refusal from an actual Git pull failure, while keeping PR worktrees from making a clean manifest primary checkout appear dirty.

Background

Base intentionally updates only the repository roots named by the workspace manifest and refuses to stash, reset, switch, or pull unsafe checkouts. That safety behavior is correct, but the current output is misleading in two common worktree-heavy cases:

• a required root with local edits is rendered as SKIP skipped, then counted as failed=1;
• a repository has Git-registered linked worktrees nested beneath its primary root, and Git reports the nested worktree container as an untracked path in the primary checkout even though the primary checkout itself has no change there.

For example, a workspace update can report skipped=2 failed=2 while no git pull command failed. The user cannot tell which repositories had command failures versus which were safely blocked before mutation. Real primary-root edits such as a staged source change or modified uv.lock must continue to block updates.

This follows #2336 and #2341. It is related to the worktree hygiene visibility tracked by #2575, but it changes the workspace update contract rather than adding automatic cleanup.

Scope

• Add an additive blocked aggregate count to text and JSON workspace-update results.
• Count required preflight refusals and required missing repositories as blocked, not as pull failures; preserve a nonzero exit code for blocked required roots.
• Keep optional missing/unsafe repositories non-fatal.
• Discover Git-registered linked worktrees for a primary checkout and exclude only those nested worktree paths from the primary-root status probe.
• Report nested linked worktrees as diagnostics with their exact paths and recommend the canonical sibling worktree root; do not move, delete, stash, reset, or switch them.
• Preserve real primary-checkout dirty paths as blocking diagnostics.
• Update the stable schema, documentation, focused unit/contract coverage, and command output examples.

Acceptance Criteria

• A required dirty primary root produces blocked=1 failed=0 and a nonzero exit status.
• A real git pull failure produces failed=1 blocked=0.
• A primary checkout with only Git-registered nested linked worktree paths can be preflighted without being classified dirty; the nested paths are reported separately.
• A primary checkout with both nested linked worktrees and a real edit remains blocked, with the real edit identified.
• JSON remains schema-valid and exposes the additive blocked count without changing existing per-repository status values.
• No automatic cleanup or history mutation is introduced.

Validation

• Add a real-Git fixture with a primary checkout and a nested linked worktree.
• Add unit coverage for blocked-versus-failed aggregate counts and status-path filtering.
• Run workspace-update tests, workspace contract/schema tests, relevant BATS coverage, git diff --check, and the full Base validation gate.

Non-Goals

• Do not automatically move existing nested worktrees.
• Do not ignore arbitrary untracked directories or files.
• Do not auto-stash, reset, switch branches, pull PR branches, or delete worktrees.
• Do not change the existing manifest target selection policy.

Project Fields

• Status: Ready
• Priority: P1
• Area: Workspace
• Initiative: Workspace Handling
• Size: M
• Category: bug

Agent Assignment

Assignee: codeforester. Use the canonical issue-backed worktree. Preserve user-owned primary-checkout changes and keep the implementation local to workspace-update preflight/reporting.