On a pod the bundle's agents and skills, and Troupe's built-in agents, beat the working copy's of the same name unless the profile sets repositoryOverridesBundle; the losers are listed as skipped, onboarding refuses there, and a worktree reads its main checkout's committed files¶
Decision 826 · accepted · 2026-10-09 · issue #516
Issue #516, slice 7, and its decision 6 as the maintainer took it: on a pod the bundle wins, with a profile setting to let the repository's files win instead. The maintainer then settled the question this slice left open: Troupe's built-in agents (and built-in skills, were there any) win on a pod as the bundle's do, and the same setting lets the repository's win over both.
- The rule, in one place.
Definitions.bundle_wins?/1: wherever a session is pinned to a bundle, which only a pod is, the bundle's agents and skills and Troupe's built-in agents beat every file on the pod's disk of the same name, unless the pin carriesrepository_overrides: true. The agent merge (load/2, given the pin) and the skill merge (Skills.available/3, through its privatelocal/2) both ask it. On a pod the order is: the pod's config directory, the working copy (.troupe/agents/,.troupe/skills/, and whateverSkills.Localreads besides,.agents/skills/included once Decision 822's layer is there), then the built-ins, then the bundle, then its ACP agents; a bundle still replaces a built-in only withoverride: true, as its validation says. The setting puts back the order there was before: built-ins, bundle, directories. - Built-ins too. A repository's
.troupe/agents/build.mdon a pod whose bundle publishes nobuildwould otherwise replace the agent every session starts as, which a clone should not be able to do any more than replace one an admin published. So a working copy's file of a built-in's name is skipped as well, with its own reason (an agent Troupe ships). Troupe ships no skills, so for skills the bundle's names are the only ones; one it shipped would win the same way. - A pod pinned to nothing. A pod whose channel has nothing published used to activate
a session with no pin at all, which would have read as a laptop. The worker now pins
such a session to nothing (
versionanddirnil, the profile's word on the setting carried as on any pin), so the built-ins win there too and the setting still reaches it. Nothing else reads a pin with no version or directory differently from none: nobundle_versionis recorded, noskills:/mount is made, no entitled set applies. - Only those names. A working copy's agent or skill of another name is read as on a
laptop. A skill on disk of a name the bundle has is left out whether or not the agent at
hand may consult the bundle's one, for the reason
load/2gives for applying the entitled set after the merge: a file standing in for one somebody was not given is a different skill answering to that name. - A loser is not read, and is listed. It is taken out of its layer before the merge,
not parsed and then replaced, so a broken one cannot even warn.
Definitions.skipped/1andSkills.skipped/2give each as{kind, name, path, reason}; the reason says the bundle has that name, or that it is an agent Troupe ships, and that the profile does not allow the repository's. The session writes them into its log asfiles_skipped(a new durable event, an addition within version 1) at a start whose list differs from the one the log last recorded, an empty list included: the definitions are read again at every activation, a working copy can gain or lose the file between two, and a session that keeps the same file through a hundred wakes says so once. A durable event rather than a log line because the person whose repository it is reads the session, not the pod's log, and because a log is where "what could this session have used" is already answered (session_created'sentitlements,mounts_resolved). Not onsession_created, which is written once, before a session's first clone has run. - The setting:
spec.repositoryOverridesBundleon theWorkerProfile. A boolean, off unless it istrue. It lives in the resource's spec, so the plane's row keeps it in its existingspecmap with no migration, a repository's manifest holds it in gitops mode, and the CRD declares it (type: boolean, no default, so no existing resource changes). The plane refuses a value that is not a boolean inFleet.Profile's changeset, whichadmin.profile.putand the gitops reader both go through: a"true"saved as text would be on to the admin and off to the pod. The console's editor has it as a toggle, loaded and written back asorgMountis, so a save from there does not turn it off. - It travels with the pin, at every activation.
Harness.bundle_params/1reads it from the profile's row and sendsrepository_overrides_bundlebesidebundle_versioninsession.activate, on a session's first start and every wake; the worker puts it on the bundle map asrepository_overrides, besideentitlements, for the reason that comment already gives: every place that reads the bundle has to apply it, and something carried separately is something one of them forgets. Not an environment variable the operator sets: that would restart every pod to change it, and ansshprofile has no pod template. Anything buttrueon the wire is the bundle winning, so a plane that says nothing leaves pods on the safe side. - Commands (Decision 763). They follow the same rule and have nothing to lose to: a
bundle carries no commands, so a working copy's
.troupe/commands/are read on a pod as everywhere, and a command named like a built-in or an agent is still skipped as 763 says. When bundles carry commands, they join this rule. - Onboarding refuses on a pod.
Troupe.Onboard.Pod.refusal/1is the one check, fortroupe onboardand for the onboarding tool (#516 slice 3) alike: given a session id, ateamsession is refused; givennil, as a command line has no session, a machine markedTROUPE_WORKER_AUTOSTART=trueis, which the operator sets on every pod and a host sets for its worker, and which a command a session's shell runs there inherits. The sentence says to onboard on your own machine and commit the result. On a pod the working copy is a clone the bundle beats and the config directory is the pod's, read by every session it runs: neither is a place to write Troupe's own files. - A worktree reads its main checkout's committed files. A git worktree is made at a
commit, so one made before onboarding has no
.troupe/agents/or.troupe/skills/while the main checkout's sessions read them.Troupe.Worktree.main/1recognises one as trust does (Troupe.Config.Trust.root/1): its.gitfile names the checkout's.git/worktrees/<name>and that names it back. The project layer is then the worktree's own directory over the main checkout's, and of the main checkout's only the files its HEAD commits (git ls-tree) are read. A file there that is not committed — onboarded and not reviewed yet, untracked or only staged — is not read and is listed as skipped, saying to commit it; one the worktree has its own of is not listed. A committed file is read where it is, so an edit to it not yet committed is read with it: what is committed decides which files, not which bytes. The main checkout's.troupe/skillsbecomes a read root of the worktree's session, for the files beside its skills. Commands, workflows andmcp.jsonin a worktree are not part of this slice. - Not decided here, as the chunk said: Cursor rules at runtime or onboarded, automatic
onboarding, the deprecation, and a repository without
AGENTS.md(#516's decisions 1, 4, 5 and 7). The precedence ladder is Decision 822's; this decision is its pod line.
Governs: apps/troupe_core/lib/troupe/agent/definitions.ex, apps/troupe_core/lib/troupe/skills.ex, apps/troupe_core/lib/troupe/onboard/pod.ex, apps/troupe_worker/lib/troupe/worker/plane/commands.ex