Skip to content

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 carries repository_overrides: true. The agent merge (load/2, given the pin) and the skill merge (Skills.available/3, through its private local/2) both ask it. On a pod the order is: the pod's config directory, the working copy (.troupe/agents/, .troupe/skills/, and whatever Skills.Local reads 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 with override: 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.md on a pod whose bundle publishes no build would 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 (version and dir nil, 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: no bundle_version is recorded, no skills:/ 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/2 gives 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/1 and Skills.skipped/2 give 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 as files_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's entitlements, mounts_resolved). Not on session_created, which is written once, before a session's first clone has run.
  • The setting: spec.repositoryOverridesBundle on the WorkerProfile. A boolean, off unless it is true. It lives in the resource's spec, so the plane's row keeps it in its existing spec map 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 in Fleet.Profile's changeset, which admin.profile.put and 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 as orgMount is, so a save from there does not turn it off.
  • It travels with the pin, at every activation. Harness.bundle_params/1 reads it from the profile's row and sends repository_overrides_bundle beside bundle_version in session.activate, on a session's first start and every wake; the worker puts it on the bundle map as repository_overrides, beside entitlements, 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 an ssh profile has no pod template. Anything but true on 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/1 is the one check, for troupe onboard and for the onboarding tool (#516 slice 3) alike: given a session id, a team session is refused; given nil, as a command line has no session, a machine marked TROUPE_WORKER_AUTOSTART=true is, 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/1 recognises one as trust does (Troupe.Config.Trust.root/1): its .git file 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/skills becomes a read root of the worktree's session, for the files beside its skills. Commands, workflows and mcp.json in 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