bug(review): candidate-view preflight rejects WSL DrvFS repositories with an opaque permission error

[jparradog]

Summary

A review of tracked workspace changes on a WSL Windows-mounted DrvFS repository returned ready / review.start from gentle_review inspect, but following that transition failed before native START with candidate-view-invalid. No lineage, mutation, or consent envelope was created.

Read-only source and filesystem diagnosis strongly points to candidate-view permission attestation on DrvFS without POSIX metadata. This is a high-confidence diagnosis, not a newly reproduced isolated test: the failed temporary view was already cleaned up, so its exact first failing assertion could not be inspected.

Environment

• Pi: 0.85.0
• gentle-pi package: 2.4.0, commit 525812fb8f2ba5f5e26c867d4a18321b6eda46ba
• gentle-ai CLI: 2.4.0-rc.8
• Repository under /mnt/<drive>/<repo> on WSL
• findmnt -T <repo> reports 9p, aname=drvfs, without metadata
• stat reports 0777 for repository files and the candidate-views parent directory
• git config core.filemode: false
• Negotiated STATUS: gentle-ai.review-integration.status/v7, contract gentle-ai.review-integration/v2, workspace projection

Observed flow

1. Open a repository with a normal tracked workspace diff on the mount described above.
2. Call gentle_review with {"operation":"inspect"}. Result offers review.start with the correct target and changed paths.
3. Follow the offered route using gentle_review START with ordinary mode and a fresh idempotency key.
4. The facade returns:

{
  "operation": "start",
  "status": "blocked",
  "outcome": "native-operation-failed",
  "lineage_created": false,
  "mutation_performed": false,
  "mutation_outcome": "none",
  "reset_eligible": false,
  "diagnostics": {
    "code": "candidate-view-invalid",
    "message": "candidate view rejected before native START"
  },
  "next_action": "resolve-native-operation-failure"
}

This occurred twice for the same unchanged candidate. No reset, recovery, or security-check bypass was attempted. This report does not claim a clean-main synthetic reproduction or a tested fix.

Technical evidence and likely cause

At the pinned gentle-pi commit:

• extensions/gentle-ai.ts:5094-5112: inspect obtains/maps target STATUS; it does not materialize/verify the candidate view.
• extensions/gentle-ai.ts:5499-5537: START materializes the candidate view and verifies it before setting nativeStartAttempted and invoking native START.
• lib/review-candidate-view.ts:583-610,799-855: the view is placed under the Git common directory and protected using chmod with 0444/0555.
• lib/review-candidate-view.ts:884-906: directory, .git, and file checks reject writable mode bits; file executable modes are also verified.
• lib/review-candidate-view.ts:231-238: candidate-view validation errors default to candidate-view-invalid.
• extensions/gentle-ai.ts:3941-3944: the detailed pre-native error is replaced by the generic message above.

The likely failure is that this mount cannot represent the requested POSIX permission modes. The first directory-mode check is a likely rejection point, but the exact failing entry was not retained. The installed decoder accepts status/v7; version skew alone is not evidence of a schema failure here.

Expected behavior

Either support this filesystem while preserving candidate immutability, or reject the unsupported permission capability early with an actionable, sanitized diagnostic. Recommend a repository whose Git common directory resides on a native Linux filesystem; a linked worktree under Linux with its common directory still on DrvFS would not address this placement constraint.

Do not relax the immutability guard or recommend recovery when no lineage exists. Enabling DrvFS metadata or upgrading has not been tested as a fix in this report.

Suggested acceptance criteria

• Detect or characterize ineffective POSIX permission changes before presenting an opaque START failure.
• Preserve fail-closed immutable candidate validation.
• Provide a specific, sanitized filesystem/permission-capability diagnostic and a safe next step.
• Retain behavior on native Linux filesystems and add regression coverage for ineffective chmod semantics.
• Document the Git common-directory filesystem requirement.

Related issues and secondary observation

Searched open and closed issues for candidate-view-invalid, DrvFS, and WSL candidate permissions. No exact DrvFS report was found. #222 and #252 address related candidate-view safety/diagnostics; #284 concerns cwd equivalence rather than permission semantics.

After the user explicitly chose to leave the candidate unreviewed in chat, the once-per-candidate reminder still requested START. The agent_end handler (extensions/gentle-ai.ts:6039-6102) checks STATUS and a nudged-target set, not that chat decision. Because START never returned a consent envelope, no provider-owned decline could be recorded. This is a secondary UX observation, not proof of a second cause or a request to parse chat as review authority.

[jparradog]

Fresh reproduction confirming this is still unfixed, plus two additional data points from a production sequence today.

Environment (current):

• gentle-ai CLI: main-3a19dbf8961bea9771b4e867cf3872e47ebe2699
• Repository under /mnt/<drive>/... on WSL2; mount reports 9p, aname=drvfs, no metadata; all modes report 0777 and chmod is a silent no-op
• gentle-ai review mode status self-reports: receipt-driven development: off (decided by clone_local) and then prints the unsafe-path error demanding chmod 700 on the review-mode authority path

Reproduction across four independent implementation candidates today (each prepared and committed by a separate agent on its own branch/worktree):

1. inspect returns ready and offers review.start for the committed candidate.
2. START (ordinary mode, fresh idempotency key, two attempts with distinct keys on one candidate) fails pre-lineage with candidate-owner-preparation-failed — lineage_created: false, no mutation, no authority burned.
3. Re-inspect offers the same route again — the failure is deterministic, not transient.

Additional data point 1 — a second distinct opaque failure surface: where the original report saw candidate-view-invalid, our runs failed with candidate-owner-preparation-failed / "candidate view rejected before native START". Same root cause (permission attestation impossible on DrvFS), different opaque code, both unactionable from the lifecycle side. The actionable chmod 700 ... hint only appears on review mode status/mode disable output, never on the START failure.

Additional data point 2 — the documented opt-out is blocked by the same check: gentle-ai review mode disable --scope clone also fails with the same unsafe-path error (it cannot persist its clone-local decision through a 0777-checked path), so on this filesystem the operator can neither complete a review nor cleanly opt out via the CLI. Deleting the runtime state directory only moves the check to the parent path. The only working escape today is the lifecycle-external answer "leave the candidate unreviewed"; the effective mode nevertheless reads off, which is how four candidates still ended up attempting START.

Manual workaround confirmed to exist but not viable as a default: sudo mount -o remount,metadata /mnt/<drive> makes chmod effective and would let the 0700 attestation pass — but it requires sudo and changes mode-bit semantics for the entire drive, which is disproportionate for a per-repo review feature.

Suggested directions consistent with the original report: accept a Windows-ACL-backed attestation equivalence on DrvFS/NTFS mounts, allow relocating the private authority root to a POSIX-metadata filesystem (e.g. an XDG state dir on ext4) for repos that cannot provide it, and/or surface the specific chmod-impossible diagnosis on the START failure code instead of only on mode status.

No private repository names, key material, or identifiers are included.

[jparradog]

Follow-up with a minimal copy-paste reproduction, an A/B filesystem comparison, and source pointers to make the fix concrete.

Minimal reproduction (no candidate needed, ~8 commands)

On WSL2, any repository on a Windows drive mount (9p/drvfs, no metadata option):

REPO=$(mktemp -d /mnt/<drive>/.../repro-XXXX)   # any 9p/drvfs path
cd "$REPO" && git init -q .
touch t && chmod 700 t && stat -c '%a' t        # -> 777   (chmod is a silent no-op)
mkdir -p .git/gentle-ai/review-mode/rar-authority
touch .git/gentle-ai/review-mode/non-interactive-notice-shown
gentle-ai review mode status --cwd .
# Error: the clone-local review mode path ".../review-mode/rar-authority" is unsafe;
# run `chmod 700 '...'`, then rerun the original command

The trigger is the existence of the review-mode state directory (which any review lifecycle operation creates). An empty .git/gentle-ai/review-mode/ alone does not fire it; the check walks down to the rar-authority leaf.

A/B comparison (same binary, same steps, only the filesystem differs)

	9p/drvfs (/mnt/<drive>)	ext4 (WSL native)
chmod 700 effective?	no — mode stays 0777	yes — 0700
review mode status with the state dir present	Error: ... is unsafe; run chmod 700 ...	clean; reports effective mode
review mode disable --scope clone	fails with the same error — the opt-out cannot persist	works

So the check is a pure POSIX-mode attestation that is structurally unsatisfiable on Windows-drive mounts, and it additionally blocks the documented opt-out, leaving an operator unable to either complete a review or disable the switch through the CLI.

Source pointer

• The failing string lives in the compiled binary gentle-ai main-3a19dbf8961bea9771b4e867cf3872e47ebe2699: the clone-local review mode path %s is unsafe; run %s, then rerun the original command.
• The fix belongs in the separate gentle-ai source repository (this package repo only ships release binaries), at the review-mode state store that walks .git/gentle-ai/review-mode/** and requires 0700 at every level.

What we observed end-to-end in production today

Four independent committed candidates on this filesystem: inspect returns ready/review.start for each; START fails pre-lineage with candidate-owner-preparation-failed (lineage_created false, no authority burned), deterministic across retries. The actionable chmod hint never appears on the START failure — only on mode status/mode disable — so an agent following the lifecycle cannot self-diagnose (see earlier comment for that part of the sequence).

Fix directions, refined by the repro

1. Detect the mount class before attesting: a cheap probe (create a temp file, chmod 700, stat) distinguishes POSIX-metadata filesystems from DrvFS/9p. On DrvFS, either skip the mode-bit attestation in favor of an ownership/ACL check (the WSL user is the sole owner; NTFS ACLs are the real enforcement layer) or relocate the private authority root to a POSIX-metadata location (e.g. XDG state dir on ext4) keyed by the repository identity.
2. Never let the attestation block the opt-out: mode disable --scope clone must always succeed — otherwise the tool deadlocks between unusable review and unusable opt-out.
3. Surface the specific diagnosis on the START failure: today the lifecycle only sees candidate-owner-preparation-failed / candidate-view-invalid; emitting the actionable unsafe-path diagnosis there would have saved the whole debugging session.

No private repository names, key material, or identifiers are included.

[barbatdev]

The diagnostic half of this is fixed: #1563 is merged (1d1e78b). On filesystems that can't represent private POSIX modes (WSL DrvFS without metadata), START now reports candidate-owner-parent-chmod-ineffective with guidance that fits the actual situation (move the repo's Git common directory to a POSIX-metadata filesystem or enable metadata support), instead of the old candidate-owner-parent-privacy message that told you to fix permissions you can't fix on that mount.

Your minimal repro and the A/B comparison are what made this concrete, so thank you for that.

What's still open is the capability gap itself: on those filesystems the private-mode requirement can't be satisfied at all, so review-mode START stays blocked. That follow-up (a clone-scope review mode opt-out on filesystems without POSIX metadata) is tracked in Gentleman-Programming/gentle-ai#5112.

[barbatdev]

Closing this one here. The opaque permission error is fixed by #1563, and the new diagnostic tells you exactly what is wrong and what to do about it.

The remaining piece (making review mode usable on filesystems without POSIX metadata, or a clean opt-out for that case) lives in Gentleman-Programming/gentle-ai#5112, so that is where the discussion continues. Reopen or ping me if the new diagnostic ever misfires on a setup like this one.