docs: scheduled imports on macOS — the TCC prompt loop and the Full Disk Access setup

[ss251]

Documents the macOS TCC prompt loop that breaks scheduled imports, and the setup that fixes it. Full diagnosis with tccd evidence in #61.

What's in here:

• docs/scheduled-imports.md — why the "access data from other apps" Allow never persists for launchd/cron runs (session-scoped consent, kTCCServiceSystemPolicyAppData), the stable-path + Full Disk Access setup that makes unattended imports work (TCC keys bare binaries by absolute path, so the versioned Cellar path loses the grant on every upgrade), the post-upgrade cp -p refresh, and the launchd OS_REASON_CODESIGNING trap when a job's binary changes signing identity.
• README: one pointer sentence in Search and automation and an entry in the Documentation list.

Everything documented was reproduced and verified on macOS 26 (Darwin 25.5) with wacrawl 0.3.6 running under launchd on a 2-hour StartInterval — the prompt loop, the session-scoped tccd log lines, the FDA fix, the upgrade-survival behavior, and the codesigning kill.

Happy to fold this into docs/commands.md instead, trim it, or adjust the recommended paths if you prefer a different convention.

Closes #61

🤖 Generated with Claude Code

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed August 7, 2026, 4:46 PM ET / 20:46 UTC.

ClawSweeper review

What this changes

Adds a macOS scheduled-imports guide explaining the TCC prompt loop, a stable signed binary path with Full Disk Access, and a launchd example, then links it from the README.

Merge readiness

⚠️ Ready for maintainer review - 5 items remain

Keep this PR open for maintainer review: it is a focused documentation response to the linked macOS scheduling report, and the revised head resolves the earlier absolute-path launchd concern. The remaining choice is whether to endorse Full Disk Access as official least-privilege guidance.

Priority: P2
Reviewed head: 5102c84eb4d06b744b6487df0835966a3c0b3ad4
Owner decision: Required. See Decision needed.

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	A focused, internally consistent docs patch with no code-level finding; merge readiness depends on the explicit permission-boundary decision.
Proof confidence	🌊 off-meta tidepool	Not applicable: This changes only README and documentation files, so a separate real-behavior proof gate does not apply.
Patch quality	🐚 platinum hermit (4/6)	Security review found an item that needs attention.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: This changes only README and documentation files, so a separate real-behavior proof gate does not apply.
Evidence reviewed	5 items	Focused docs-only patch: The PR changes only the README and a new 106-line scheduled-imports guide; whitespace validation reports no errors. Prior launchd finding addressed: The current guide uses an absolute ProgramArguments executable path and gives matching bootstrap and inspection commands, addressing the prior review’s concern about literal tilde handling. Signing identity matches release policy: The guide’s identifier and team ID match the current macOS release verifier’s required signed-binary identity.
Findings	None	None.
Security	Needs attention	Confirm the Full Disk Access support policy: The guide asks users to grant a dedicated wacrawl binary broad local-data access; its least-privilege caveats mitigate the risk but do not replace a maintainer decision to endorse this remedy.

How this fits together

wacrawl reads WhatsApp Desktop’s protected macOS container and imports a snapshot into its local archive. Scheduled launchd imports can hit macOS TCC consent behavior before the importer can create or refresh that archive.

flowchart LR
  A[WhatsApp Desktop container] --> B[Scheduled launchd job]
  B --> C[Dedicated wacrawl copy]
  C --> D[macOS TCC access check]
  D -->|Full Disk Access granted| E[Import archive]
  D -->|Consent prompt blocks run| F[Stale archive]

Loading

Decision needed

Question	Recommendation
Should official wacrawl documentation endorse granting Full Disk Access to a dedicated signed copy for scheduled macOS imports?	Endorse the least-privilege guide: Merge the dedicated-copy guidance, including signature verification and revocation, as the supported workaround for launchd imports.

Why: This is a user-facing privacy and support-policy choice, not a mechanical documentation correction; the PR already presents the least-privilege implementation.

Before merge

• Add real behavior proof - Not applicable: This changes only README and documentation files, so a separate real-behavior proof gate does not apply.
• Resolve security concern: Confirm the Full Disk Access support policy - The guide asks users to grant a dedicated wacrawl binary broad local-data access; its least-privilege caveats mitigate the risk but do not replace a maintainer decision to endorse this remedy.
• Resolve merge risk (P1) - The guide recommends Full Disk Access, which grants its binary broad local-data access; maintainers should explicitly endorse that privacy tradeoff before publishing it as supported setup guidance.
• Complete next step (P2) - No mechanical repair remains; a maintainer must decide whether this security-sensitive setup recommendation belongs in official documentation.

Findings

• [medium] Confirm the Full Disk Access support policy — docs/scheduled-imports.md:42

Agent review details

Security

Needs attention: No executable or dependency change is present, but publishing a Full Disk Access workaround requires deliberate maintainer approval of its broad permission boundary.

Review metrics

Metric	Value	Why it matters
Documentation scope	109 added, 0 removed, 2 files affected	The branch is limited to one new guide and README discoverability links.

Root-cause cluster

Relationship: fixed_by_candidate
Canonical: #61
Summary: This PR is the candidate documentation remedy for the canonical report about scheduled macOS imports.

Members:

• canonical: macOS: scheduled (launchd) imports hit a recurring 'access data from other apps' prompt — Allow never persists for background runs #61 - The PR explicitly addresses that report’s TCC prompt-loop diagnosis and proposed documentation remedy.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge-risk options

Maintainer options:

1. Confirm the documented permission boundary (recommended)
   Approve the dedicated-copy Full Disk Access recommendation only if maintainers want this broad macOS permission to be an official supported workaround.
2. Pause the FDA recommendation
   Keep the diagnosis but defer the permission-granting setup until a maintainer chooses a narrower supported path.

Technical review

Best possible solution:

Publish the narrow guide with its dedicated-copy, signature-verification, and revocation safeguards if maintainers approve Full Disk Access as the supported remedy for unattended imports.

Do we have a high-confidence way to reproduce the issue?

No—the reported TCC and launchd behavior was not executed in this review; the PR body supplies a concrete macOS environment and observed tccd evidence.

Is this the best way to solve the issue?

Unclear—the documentation path is narrow and avoids changing import behavior, but maintainers must decide whether Full Disk Access is an appropriate official recommendation.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 6a177d040a7d.

Labels

Label changes:

• add merge-risk: 🚨 security-boundary: The guide directs users to grant Full Disk Access, a broad local-data permission, even though it includes dedicated-copy safeguards.

Label justifications:

• P2: Scheduled imports can leave an archive stale, but the change is a bounded macOS documentation improvement rather than an urgent runtime regression.
• merge-risk: 🚨 security-boundary: The guide directs users to grant Full Disk Access, a broad local-data permission, even though it includes dedicated-copy safeguards.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: This changes only README and documentation files, so a separate real-behavior proof gate does not apply.

Evidence

Security concerns:

• [medium] Confirm the Full Disk Access support policy — docs/scheduled-imports.md:42
  The guide asks users to grant a dedicated wacrawl binary broad local-data access; its least-privilege caveats mitigate the risk but do not replace a maintainer decision to endorse this remedy.
  Confidence: 0.94

What I checked:

• Focused docs-only patch: The PR changes only the README and a new 106-line scheduled-imports guide; whitespace validation reports no errors. (docs/scheduled-imports.md:1, 5102c84eb4d0)
• Prior launchd finding addressed: The current guide uses an absolute ProgramArguments executable path and gives matching bootstrap and inspection commands, addressing the prior review’s concern about literal tilde handling. (docs/scheduled-imports.md:52, 5102c84eb4d0)
• Signing identity matches release policy: The guide’s identifier and team ID match the current macOS release verifier’s required signed-binary identity. (scripts/verify-macos-release.sh:6, 6a177d040a7d)
• Current main lacks the guide: Current main lists the existing documentation set but not scheduled-imports.md, while the PR tree adds it; this is not already implemented on main or in v0.3.6. (docs/scheduled-imports.md:1, 6a177d040a7d)
• Release-area provenance: The current release baseline is v0.3.6, and the earlier macOS notarization work is represented by the signing-area commit below. (scripts/codesign-macos.sh:5, 9987e89fc360)

Likely related people:

• Vincent Koc: Authored the current v0.3.6 baseline that owns the existing README and release-verification content. (role: recent release-area contributor; confidence: high; commits: 7f75c9939b37; files: README.md, scripts/verify-macos-release.sh, docs/releasing.md)
• Peter Steinberger: Authored the earlier macOS notarization work relevant to the signing identity the guide asks users to verify. (role: macOS signing-area contributor; confidence: medium; commits: 9987e89fc360; files: scripts/codesign-macos.sh, scripts/verify-macos-release.sh)

Rank-up moves

Optional improvements that raise the rating; they are not merge blockers.

• Obtain maintainer confirmation that the dedicated-copy Full Disk Access guidance is an approved support recommendation.

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

History

Review history (2 earlier review cycles)

• reviewed 2026-08-07T18:57:35.155Z sha 271dd71 :: needs real behavior proof before merge. :: [P2] Use an absolute executable path in the launchd instruction
• reviewed 2026-08-07T19:11:37.805Z sha 5102c84 :: needs real behavior proof before merge. :: none

[ss251]

@clawsweeper re-review

Addressed the P2: the launchd instruction now ships a complete minimal plist with an absolute ProgramArguments path (with an explicit note that launchd performs no tilde expansion), plus bootstrap/inspect commands. Also simplified the copy-refresh to a single symlink-following cp -p for both setup and upgrades, and added a least-privilege section per the review on #61: grant Full Disk Access only to the dedicated copy, verify its signing identity (org.openclaw.wacrawl / FWJYW4S8P8), revoke when unscheduled.

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.

Re-review progress:

• State: Complete
• Detail: The durable review result and its route handoff completed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/31211175285
• Updated: 2026-08-07T19:22:43.092Z

[steipete]

Landed as 10efd170ebe1031b0ced40e5993446ca188b5932.

Proof run before merge:

• go test ./... passed.
• git diff --check origin/main...HEAD passed, and every added README documentation target exists.
• The documented plist extracted from docs/scheduled-imports.md passed plutil -lint -.
• The installed Homebrew wacrawl 0.3.6 reported the documented org.openclaw.wacrawl identifier and FWJYW4S8P8 team, passed strict code-signature verification, and remained valid and runnable after the documented symlink-following cp -p copy.
• Codex autoreview completed cleanly with no accepted/actionable findings.

GitHub did not offer the normal CI matrix for this fork branch; the available dispatch check passed and the executable/doc-specific proof above was run locally on macOS. The reported recurring TCC prompt itself was reproduced by the contributor on macOS 26, as documented in #61.