// Use when authoring an AgentWorkforce persona's `mount` field — covers when to use mount, the gitignore allow-list idiom and its non-obvious `!web` vs `!web/` walker bug, `readonlyPatterns` scope rules, the per-agent dotfile overlay, and `.git` sandbox behavior
| name | persona-relayfile-mount |
| description | Use when authoring an AgentWorkforce persona's `mount` field — covers when to use mount, the gitignore allow-list idiom and its non-obvious `!web` vs `!web/` walker bug, `readonlyPatterns` scope rules, the per-agent dotfile overlay, and `.git` sandbox behavior |
You are advising an author writing the mount field on an AgentWorkforce persona spec. Use mount when the persona should run in a filesystem sandbox: it should see only some files, treat others as read-only, or both. Omit mount when the persona is fine running in-place with full project access (the default for most personas).
"mount": {
"ignoredPatterns": ["..."],
"readonlyPatterns": ["..."]
}
Both arrays use gitignore-style globs (powered by the ignore library).
ignoredPatterns — matches are omitted from the mount entirely; the agent cannot see or write them.readonlyPatterns — matches are copied into the mount but chmod 444; agent edits to these paths never sync back to the project.Mount gates files. permissions gates tools. They compose — a persona that shouldn't see .env AND shouldn't shell out needs both.
The persona's id is passed to relayfile as agentName. At launch, relayfile also loads:
.{id}.agentignore.{id}.agentreadonlyfrom the project root, appending their contents to the persona spec's patterns. Persona authors control the in-spec baseline; deployers can layer per-agent dotfiles on top without editing the persona JSON.
Use gitignore negation, NOT a broad ** exclude.
Correct:
"ignoredPatterns": ["/*", "!web", "!web/**", "secrets/", ".env"]
Four rules to avoid bricking the mount:
/* as the broad-exclude, never **. Gitignore semantics skip excluded parent directories entirely. Once ** excludes a directory, a later !dir/** cannot bring its contents back — the dir was never walked. /* only excludes root-level entries, so subdirs of allowed paths stay visible.!web, NOT !web/. This one is non-obvious and breaks every "obvious" allow-list. The relayfile walker calls the ignore library twice per directory entry — once with the bare name (web) and once with the trailing-slash form (web/) — and OR's the results. The bare-name check fires first, and /* matches web regardless of type. A trailing-slash negation !web/ only counters the trailing-slash form, so the bare-name check still returns "ignored" and the walker skips the directory. !web (no slash) negates BOTH forms, which is what you need. If your allow-listed subtree isn't appearing in the mount, this is almost always the bug.!web re-includes the directory node so the walker recurses into it; !web/** re-includes everything inside it. You need both../ prefixes. The ignore library expects bare relative patterns; ./web/** is treated as a literal path that almost never matches.Wrong (looks right, silently empty mount):
"ignoredPatterns": ["/*", "!web/", "!web/**"]
Right:
"ignoredPatterns": ["/*", "!web", "!web/**"]
readonlyPatterns is for paths the agent should READ but never MODIFY — lockfiles, vendor code, configs the persona references but shouldn't touch.
Never include the persona's primary work directory. If you do, the agent's writes to that directory are silently filtered out on sync-back. The persona looks like it ran successfully but produced zero project-side changes — one of the worst failure modes because nothing complains.
Example: a blog-writer persona whose job is to author files under web/content/blog/ must NOT have web/** in readonlyPatterns.
The mount auto-includes .git, so git status/log/diff work inside the sandbox. Sync rules:
.git/** flow INTO the mount (e.g. teammate moves HEAD while the agent runs)..git/** are NOT synced back. Branches, commits, and refs the agent creates in the mount stay sandboxed and are discarded on cleanup unless the agent pushes to a remote.mount entirely./* (not **) plus paired !dir (NO trailing slash) and !dir/** for each allowed path?readonlyPatterns?.env, and any private dirs in ignoredPatterns?permissions cover the tool-side scope (Bash, file edits, MCP) the persona should and shouldn't have?Use before auto-merging any PR in an autonomous run, and between consecutive merges that touch overlapping code. Covers the per-PR auto-merge bar (live CI verification, substantive review by area, bot-finding stale-vs-actionable triage) and the cross-PR composition discipline (serialize through green main, rebase + re-CI between merges, dormant-safety audit, force-reset over half-merged commits).
Use at the start of every autonomous, multi-PR, cutover-class delegated run. Authors the binding contract between operator and agent — the gates, the flip mechanism, the rollback triggers, the standing constraints, and the explicit escalate-to-human conditions — and surfaces it to the operator for explicit grant of (a) auto-merge authority, (b) flip-the-switch authority, (c) swarm-blockers authority. No autonomous work begins until the contract is acknowledged.
Use when designing or executing a cutover-class change (migration, ingestion path swap, provider relink, flag enablement). Encodes the dark-launch + single-switch flip pattern, the refusal to flip on amber, and the pre-authorized rollback procedure — the canonical way to make irreversible-feeling infra changes reversible-feeling.
Use when a fix has failed two consecutive times for the same symptom. Encodes the discipline that the third action must be a temporary diagnostic (a /_diag endpoint, an enriched structured log, a runtime-captured snapshot) rather than another fix attempt. Also covers the discipline for removing those diagnostics once the real root cause is in.
Use during an autonomous run to (a) dispatch supporting codex-impl + claude-review agent pairs against hard blockers when the orchestrator cannot make progress alone, and (b) maintain the live RED / GREEN gate scoreboard the orchestrator reads to authorize the flip. Encodes the file-based reporting convention that keeps the channel readable.
Use when a single gate would require deep proof across a large set (44 models × 10 providers; 60+ resources; every region; every plan tier). Splits the acceptance into tier-1 (deep proof on high-volume / high-fidelity slice) and tier-2 (smoke proof on low-volume tail), documents the explicit accepted trade-off, and preserves safety through dormant-default + per-item enable + rollback.