docs: correct the Grok harness reference on folder trust, training opt-in, and delivery

[Courtneyezra]

Intent

Correct the Grok harness reference in this repo so the next agent to use that tool is not misled by it. Three facts were established by real use on 24 Sep 2026, on the first dispatches after the tool was added to this fleet.

What Changed

• harness-adapters/references/harness/grok.md now says that Grok 1.0.41 shows a folder-trust gate in a linked git worktree, separate from the project picker. It explains that the dialog prints the primary checkout path, so agents should check the worker's real location with /proc/<pid>/cwd. The gate is answered with fm-send.sh <target> --key Enter. The answer persists to ~/.grok/trusted_folders.toml under the primary checkout's path. This turns on project hooks for that checkout, and the doc lists it as a knowing exception to the rule of not writing that store. The turn-end hook section is updated to match.
• grok.md has a new "Training opt-in" section: the "Help improve Grok" option keeps prompts, traces, and metrics for training, is off by default, and must be left off. The section explains why, citing the fleet's customer-facing privacy statements. grok.md also notes that on 2026-09-24 a steer sat unsent in the Grok 1.0.41 composer (Enter:send now), and tells agents to check delivery by peeking at the pane rather than trusting the send result.
• common/control-and-recovery.md no longer says Grok avoids its trust gate. It now points to grok.md for the folder-trust gate and keeps the project-picker behaviour as a separate point. The verification line in grok.md records 1.0.41 on 2026-09-24.

🤖 Generated with Claude Code

Risk Assessment

✅ Low: This change only edits two harness reference docs. It records the three facts the intent asks for: folder trust and where it persists, the training opt-in, and unsent composer delivery. The round-1 persistence fix was applied as the user instructed, and the claims about fm-send and fm-spawn's trust-store stance match the source.

Testing

No code changed, so I checked the change in two ways: I ran the harness-adapter routing test, and I confirmed the new relative links resolve. I also tried to reproduce the Grok 1.0.41 folder-trust gate in a disposable linked worktree with a sandboxed HOME. Grok stopped at its browser sign-in screen before any trust gate. I would have needed the operator's real credentials to get further, so I stopped and cleaned up. That first screen is saved as evidence. None of the documented behaviours (trust persistence, training opt-in, unsent steer) could be driven live, so the verdict is no-surface.

• Live validation: ⚠️ no-surface - 0 of 4 scenarios driven live against the product

Scenario	Result	Live	Evidence
An agent reading grok.md learns that answering Grok's folder-trust gate with fm-send --key Enter writes an entry for the primary checkout to ~/.grok/trusted_folders.toml	⏸️ untested	no	No live surface: this is documentation. Reproducing the behaviour needs Grok credentials to get past sign-in. Doing it under the real HOME would write the user-level trust store, which the run's decis…
An agent reading grok.md knows the Help improve Grok training opt-in must stay off	⏸️ untested	no	No live surface: this is documentation guidance, and no code reads it. Seeing the opt-in prompt would also need an authenticated Grok session.
An agent reading grok.md checks a Grok steer with fm-peek instead of trusting the send result when the pane shows Enter:send now	⏸️ untested	no	No live surface: fm-send.sh and the composer classifier did not change, so there is no new runtime behaviour to drive. Reproducing the unsent steer would also need an authenticated Grok 1.0.41 worker.
control-and-recovery.md sends agents to grok.md for Grok's folder-trust gate instead of claiming Grok avoids it	⏸️ untested	no	No live surface: it is a routing sentence in documentation and nothing executes it.

Evidence: Grok 1.0.41 first screen in a disposable linked worktree (sign-in blocks reaching the trust gate)

Source: Grok 1.0.41 first screen in a disposable linked worktree (sign-in blocks reaching the trust gate)

   wt worktree /t/fm-grok-trust-8aRd/wt



                                                                         ⠀⠀⠀⠀⠀⠀⣀⣀⡀⠀⠀⠀⢀⠄
                                                                         ⠀⠀⠀⣠⣾⠿⠛⠛⠛⠛⢀⡴⠁⠀
                                                                         ⠀⠀⣼⡟⠁⠀⠀⠀⢀⡴⠻⣿⡀⠀
                                                                         ⠀⠀⣿⡇⠀⠀⠀⠔⠁⠀⠀⣿⡇⠀
                                                                         ⠀⠀⢹⣷⠀⠀⠀⠀⠀⢀⣴⡿⠀⠀
                                                                         ⠀⢀⠞⠁⠠⢶⣶⣶⣶⠿⠋⠀⠀⠀
                                                                         ⠐⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀


                                                          Approve in your browser to finish signing in.

                                                                            PWFA-P6WM

                                                             Make sure your browser shows this code.

                                                             If it doesn't open, click here to copy.



                                                        Copying not working? Click here to show full URL.

                                                                     Waiting for approval...








                                                                          ctrl+q  quit

- Outcome: ⚠️ 1 warning across 1 run (1m2s)

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

✅ **Review** - passed

✅ No issues found.

⚠️ **Test** - 1 warning

• ⚠️ this change has no live-validatable surface; proceed without live validation? (0 of 4 scenarios were driven live against the product); An agent reading grok.md learns that answering Grok's folder-trust gate with fm-send --key Enter writes an entry for the primary checkout to ~/.grok/trusted_folders.toml: No live surface: this is documentation. Reproducing the behaviour needs Grok credentials to get past sign-in. Doing it under the real HOME would write the user-level trust store, which the run's decisions forbid. To confirm, a human can sign in to Grok inside a disposable HOME, launch it in a linked worktree, press Enter on the gate, and inspect that HOME's .grok/trusted_folders.toml.; An agent reading grok.md knows the Help improve Grok training opt-in must stay off: No live surface: this is documentation guidance, and no code reads it. Seeing the opt-in prompt would also need an authenticated Grok session.; An agent reading grok.md checks a Grok steer with fm-peek instead of trusting the send result when the pane shows Enter:send now: No live surface: fm-send.sh and the composer classifier did not change, so there is no new runtime behaviour to drive. Reproducing the unsent steer would also need an authenticated Grok 1.0.41 worker.; control-and-recovery.md sends agents to grok.md for Grok's folder-trust gate instead of claiming Grok avoids it: No live surface: it is a routing sentence in documentation and nothing executes it.
• Live validation: ⚠️ no-surface - 0 of 4 scenarios driven live against the product

Scenario	Result	Live	Evidence
An agent reading grok.md learns that answering Grok's folder-trust gate with fm-send --key Enter writes an entry for the primary checkout to ~/.grok/trusted_folders.toml	⏸️ untested	no	No live surface: this is documentation. Reproducing the behaviour needs Grok credentials to get past sign-in. Doing it under the real HOME would write the user-level trust store, which the run's decis…
An agent reading grok.md knows the Help improve Grok training opt-in must stay off	⏸️ untested	no	No live surface: this is documentation guidance, and no code reads it. Seeing the opt-in prompt would also need an authenticated Grok session.
An agent reading grok.md checks a Grok steer with fm-peek instead of trusting the send result when the pane shows Enter:send now	⏸️ untested	no	No live surface: fm-send.sh and the composer classifier did not change, so there is no new runtime behaviour to drive. Reproducing the unsent steer would also need an authenticated Grok 1.0.41 worker.
control-and-recovery.md sends agents to grok.md for Grok's folder-trust gate instead of claiming Grok avoids it	⏸️ untested	no	No live surface: it is a routing sentence in documentation and nothing executes it.

• git diff 9284978..097938e — confirmed the change only touches .agents/skills/harness-adapters/references/harness/grok.md and references/common/control-and-recovery.md
• bash tests/fm-harness-adapter-references.test.sh — the routing artifact is normalized and every target is readable
• Checked that the new relative links (../../../bin/fm-send.sh, bin/fm-spawn.sh, bin/fm-composer-lib.sh, docs/herdr-backend.md) resolve from the skill root
• Read bin/fm-send.sh --key path and fm-send's unconfirmed-submission message, which already tells agents to verify with fm-peek (consistent with the new unsent-steer guidance)
• grok --version → 1.0.41; started grok in a throwaway linked worktree (tmux -L fmgroktest, HOME=/tmp disposable) to attempt the folder-trust gate; it stopped at the browser sign-in screen; tmux server killed and temp dir removed

✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.

[kunchenguid]

Speaking as Kun's firstmate: stamped waiting-ci.

HEAD 097938e0c62b7a5e4081f9265c718ec34e6e3af8. Attestation MATCH (body binds tip; live_validation no-surface for docs). Require no-mistakes SUCCESS (35986561090). CI 35986561104 approved and in progress. MERGEABLE/UNSTABLE. Docs-only tip vs main (control-and-recovery.md, grok.md). No Closes/Fixes. Fork workflows approved after safe review. Not a blocked author.

contract-class: restore — tip vs main corrects inaccurate Grok harness reference so agents match observed 1.0.41 behavior on an existing path: folder-trust gate in linked worktrees (was wrongly "dodges"), training opt-in must stay off (privacy already promised), and peek-for-delivery when composer shows unsent. No code, no new default-on product surface, no always-on observer. Docs that only restore accuracy on an existing harness gate stay restore (not FM-LEARN-4627 new-default).

VISION: One captain/interface — aligns (honest harness facts). Authority — aligns (training left off; no assumed consent). Scripts/judgment — aligns (docs only). Restart — n/a. Delegation — n/a. Fleet/vendor — aligns (Grok adapter accuracy). Scope — aligns (harness reference). Align.

When CI is green: auto-merge candidate (restore + MATCH + safe + NM SUCCESS). Not merging this pass while CI incomplete. Firstmate-flag no. Security FYI none.

[kunchenguid]

Speaking as Kun's firstmate: merged — thank you @Courtneyezra. Docs-only Grok harness accuracy restore (folder trust, training opt-in left off, peek-for-delivery) landed cleanly.