[dolho]

⚠️ Merge order: after #3016, #3017 and #3018 (and #3015). ent#705 says this default must not ship before those blockers land. The branch is stacked on them, so until they merge the diff against dev includes their commits; this PR's own changes are the last two commits (5369fa1f, 5a32230a). After they land: rebase onto dev, then merge.

Summary

Operator ruling 2026-09-24: the repository is the agent; the container is a cache of it.

• Create-time kind: agent (the default) or deployment, on POST /api/agents and MCP create_agent. This absorbs the API half of ent#704; its UI half stays there. An explicit source_mode always wins, so every existing caller keeps its behaviour. No UI, MCP or CLI caller sent one, which is why the default matters.
• An agent gets a working branch it alone writes, auto_sync_enabled=1 and freeze_schedules_if_sync_failing=1. It only gets them when the bug: git-sync write access is never validated — a read-only credential fails silently forever (ls-remote and the REST permissions.push field both lie) #2107 push probe says its token can push to that repo.
• Everything else stays pull-only, with the reason on the create response's git_mode (set after the /ws broadcast, never on it; feat: agent-reported structured reports via MCP + dashboard display #918). The cases:
  • a deployment
  • an ephemeral ghost (ent#69)
  • no token (was admitted before, stays admitted, not ent#123's 400)
  • a refused probe (the reason points to fork-to-own)
  • an unverifiable probe
• Why the probe gate is load-bearing: without it, a create from a template someone else owns (a shared public upstream above all) with a platform token that happens to have write there would push the agent's branches into that repo. That's the ent#162 class.
• Cornelius is pinned kind=deployment for exactly that reason.
• Fork-to-own gets the trio; it owns its fork.
• Not changed:
  • existing agents: the default applies to new creates, and the per-agent migration is an explicit runbook
  • freeze paging (the sync_failing item)
  • the pull cycle: on when ent#703 lands
  • divergence-age freeze semantics: ent#706
• Open-core by operator ruling (recorded on ent#705).

Changes

• src/backend/models.py: AgentConfig.kind, AgentStatus.git_mode
• src/backend/services/agent_service/crud.py:
  • _apply_agent_kind_default, called before validation and branch reservation
  • _validate_github_access(push_verified=), which skips the duplicate probe
  • freeze-on at creation beside the bug(git-sync): the auto-sync toggle is not authoritative — OFF never takes effect (the baked env is OR'd forward at recreate), ON waits for the next recreate #3010 auto-sync write
• src/backend/services/cornelius_agent_service.py: pinned pull-only
• src/mcp-server/src/tools/agents.ts: create_agent gains kind
• Docs:
  • requirements/github.md §11.17
  • feature-flows/github-sync.md ("Which mode a new agent gets")
  • architecture/agent-lifecycle.md
  • runbook docs/migrations/AGENT_WORKING_BRANCH_DEFAULT_2026-09.md: migrate a live agent (get the disk into git first, switch, recreate, verify), plus the exclusions stated generically
• Tests (test_1484_create_agent_characterization.py, through the full create_agent_internal):
  • push ok → the trio, probed once
  • denied → pull-only with the fork hint, no 400
  • unverifiable → pull-only
  • deployment or explicit source_mode → never probed
  • an explicit working branch with a read-only token → bug: git-sync write access is never validated — a read-only credential fails silently forever (ls-remote and the REST permissions.push field both lie) #2107's 400 still stands
  • tokenless → pull-only, not a 400
  • ghost → pull-only
  • Cornelius pinned
  • Three older tests that pinned "a bare github create is pull-only" now say kind="deployment" explicitly, with their assertions unchanged.

Test Plan

• Related suites green in random order: 1484 58, fork_to_own 40, ent123 53, 2069 35, 69 ephemeral 42, 1759, 2107, 3010, 3011, ent109 seam, models-centralized, gitignore doc sync. lint_sys_modules and root placement clean.
• Mutation: with crud.py and the Cornelius pin reverted, 8 of 9 new tests fail. The one that stays green is the bug: git-sync write access is never validated — a read-only credential fails silently forever (ls-remote and the REST permissions.push field both lie) #2107 explicit-request 400, which is preserved on purpose.
• MCP server tsc --noEmit clean
• Merge after fix(git-sync): auto-sync heartbeat fetches and rebases before push; refuses on a shared source-mode branch (#3011) #3016, fix(git-sync): the auto-sync toggle is authoritative and live (#3010) #3017, fix(git-sync): validate push access where GitHub enforces it (#2107) #3018 (+fix(ci): cap test SQLAlchemy below 2.1 — pg-migrations broke on the new default driver #3015), then rebase onto dev

Related to abilityai/trinity-enterprise#705 (cross-repo; close at release)

🤖 Generated with Claude Code

[dolho]

/review Report

Scope reviewed: the ent#705 commits (5369fa1f, review fixes in 5a32230a). The stacked commits of #3016, #3017, #3018 and #3015 were reviewed on their own PRs.
Scope check: CLEAN. The changes are the create-time kind, the default resolver, freeze-on at creation, the Cornelius pin, MCP kind, and docs plus the runbook. Nothing unrelated.

Plan completion (ent#705 AC):

AC	Status
Agent default → working branch + auto_sync_enabled=1 + freeze on; deployment → source, no push, freeze off	DONE: crud.py::_apply_agent_kind_default and freeze-on in _materialize_agent_files. Changed: granted only when the push probe says ok (see the PR description)
Pull cycle on	NOT DONE, by the operator's scope ruling: ent#703
Fork-to-own gets the trio	DONE
Existing fleet not flipped	DONE: the default applies at create only; kind is not persisted
Migration runbook for a live agent	DONE: docs/migrations/AGENT_WORKING_BRANCH_DEFAULT_2026-09.md
Exclusions recorded and enforced	DONE in the runbook, stated generically (public repo); enforcement is #3016's shared-branch refusal
Freeze paging unchanged; freeze keys on divergence age	Paging unchanged. Divergence age is ent#706; the current trigger is now stated in the requirement
Wizards / template.yaml gain nothing	DONE: nothing added

Execution coverage

changed symbol	executed by	live consumer	verdict
_apply_agent_kind_default	11 test_ent705_* through the full create_agent_internal	_resolve_template → every github: create (routers/agents.py, MCP create_agent)	✅ executed
push_verified	…gets_the_trio (probe awaited once)	_validate_github_access	✅ executed
freeze-on write	…gets_the_trio, …deployment…never_probed, …without_push_access…	scheduler freeze check (routers/internal.py)	✅ executed
AgentStatus.git_mode	asserted on the create result	create response (REST + MCP)	✅ executed
Cornelius pin	AST guard over its AgentConfig	the startup seed	🛡 guard (the behaviour it selects, explicit source_mode, is executed)
MCP kind	tsc --noEmit	backend AgentConfig.kind	⚠️ typecheck only

Mutation: with crud.py and the Cornelius pin reverted, 8 of 9 new tests fail. The survivor is the #2107 explicit-request 400, which is preserved on purpose.

Critical Findings

None.

Informational Findings (fixed in 5a32230a)

• [I1] Doc overclaim (8/10): "an explicit source_mode wins, every caller unchanged". The mode is unchanged, but an explicit working branch and fork-to-own now also get freeze-on. That's intended; the wording now says so.
• [I2] Edge inconsistency (7/10): a fork asked for as kind="deployment" was reported as kind: agent while the freeze write read deployment. It's now reported as asked, pinned by a new test.
• [I3] A blank line between models was dropped; restored.
• [I4] Freeze trigger before ent#706 (8/10): freeze-on means schedules pause after 3 consecutive failed syncs (~45 min), including a rebase conflict. That's consistent with ruling 2 ("not only after three failed pushes"), and it's now stated in the requirement.

Noted, not changed

• Every default github: create with a token now makes one extra receive-pack round trip (the probe; 20 s timeout at worst). There's no second probe, because validation reuses the result.
• The MCP kind is covered by a typecheck, not a test; it's a straight pass-through.

Clean categories

• SQL: no new queries.
• Auth: kind can only lower capability. agent requires a verified push, and ghosts are excluded.
• Credential exposure: the git_mode reason names the repo, never the token or the probe's stderr. It's set after the /ws broadcast, which only sends name, status and port anyway.
• Enterprise-docs guard: clean.

Summary

• Critical: 0
• Informational: 4, all fixed
• Merge order: fix(ci): cap test SQLAlchemy below 2.1 — pg-migrations broke on the new default driver #3015 → fix(git-sync): auto-sync heartbeat fetches and rebases before push; refuses on a shared source-mode branch (#3011) #3016, fix(git-sync): the auto-sync toggle is authoritative and live (#3010) #3017, fix(git-sync): validate push access where GitHub enforces it (#2107) #3018 → rebase this onto dev → merge.

🤖 Generated with Claude Code

[vybe]

merge-train: ejected from this train (and #3021 / #3022 with it, since they are stacked on this branch). #3016, #3017 and #3018 are riding without it.

Needs a ruling, probe vs. ownership: _apply_agent_kind_default in crud.py (the outcome == "ok" branch) grants a working branch plus auto_sync_enabled=1 whenever the push probe succeeds. Being able to push is not owning the repo. The token comes from resolve_github_pat, which can return the global platform PAT for any creator (the tier is never checked). So on an install whose platform PAT can write to a shared template repo, every UI/MCP/CLI/manifest create would auto-push that agent's workspace to a branch on that repo. That is the ent#162 class the docstring says is excluded. test_ent705_agent_default_with_push_access_gets_the_trio asserts exactly this for a shared template + platform PAT.

Possible directions: require a per-user or per-agent PAT tier and/or a private repo before defaulting to push. If the risk is accepted as-is, this is otherwise READY. Explicit source_mode wins, ghosts and deployments stay pull-only, git_mode is attached after the broadcast, and 131 own tests plus 786 related tests pass.

Once #3016–#3018 land, rebase this onto dev.

[github-actions]

✅ Nightly unit-suite clean when this PR is merged into dev, all 3 seeds (head_sha: c370041a71a11948be1be9c7979a7dbae6c46f56).

[github-actions]

⚠️ Live-instance suite skipped — merge conflict against dev.

Resolve by merging dev locally and pushing the result; the next nightly re-tests.

[dolho]

Ruling on probe vs. ownership (vybe, 09-25): being able to push is not owning the repo.

• 7c87ba59a: _apply_agent_kind_default now takes the tier resolve_github_pat returned. It grants the working branch, auto-sync and freeze only for per_user (the creator's own token) or per_agent (the agent's own token).
  • With only the global platform PAT, the agent is created pull-only and the probe is never called. The git_mode reason names the fix: add your own GitHub token in Settings.
  • This closes the case vybe described: a platform PAT that can write a shared template repo no longer gives every default create a branch on it (the ent#162 class).
  • test_ent705_agent_default_with_push_access_gets_the_trio asserted the old behaviour (shared template + platform PAT). It now runs on a creator-owned token.
  • New: test_ent705_the_platform_token_never_earns_a_working_branch (fails before the change) and a per_agent case.
  • The requirement, flow, lifecycle doc and runbook are updated.
• 8b20c1714: the MCP kind description and the AgentConfig.kind comment say the same.
• 6617c1ce9 merges dev now that fix(git-sync): auto-sync heartbeat fetches and rebases before push; refuses on a shared source-mode branch (#3011) #3016–fix(git-sync): validate push access where GitHub enforces it (#2107) #3018 have landed.
  • migrations.py takes dev's list.
  • crud.py and the refactor(agents): decompose create_agent_internal (830 lines, CC 120) with characterization tests first #1484 characterization test keep this branch's push_verified side.
  • The registry is rebuilt from the merge stages.
  • Single head 0079_telegram_group_context.

Tests: 133 in #1484 + fork files. 2,775 across the git, sync, fork and create suites; the only 4 failures are the ent14 IPv4-mapped SSRF cases that fail locally on py3.12 on every branch. tsc clean. CI green.

#3021 and #3022 are re-merged on top of this.

[AndriiPasternak31]

The shape is right: explicit source_mode wins, ghosts and deployments stay pull-only, git_mode is set after the /ws broadcast, and the probe is only run once. One real blocker is left. The tier gate from the 09-25 ruling still treats "can push" as "owns the repo" for any creator who has their own token. Everything else is should-fix or smaller. #3021 builds on this default, so the fix here carries into it.

1. [blocking] A creator's own token still gets a working branch on a template they don't own. src/backend/services/agent_service/crud.py:943-950
   The ruling says being able to push is not owning the repo. The fix only drops the global tier. A per_user token that passes the probe still gets the full trio. A classic PAT with repo scope, or an org-wide fine-grained token, can write every repo in the member's orgs. So a member who creates an agent from their org's shared public template gets a trinity/<agent>/<id> branch on that template. The heartbeat then pushes the agent's workspace there every 15 minutes, publicly. That is the ent#162 class that §11.17 and the flow table say is excluded ("a template someone else owns never receives an agent's branches").
   The PR's own test pins it. test_ent705_agent_default_with_push_access_gets_the_trio (tests/unit/test_1484_create_agent_characterization.py:1319-1332) creates from Abilityai/cornelius with a per_user token and asserts a working branch. That is the same shared public upstream Cornelius is pinned away from in cornelius_agent_service.py.
   Fix: add an ownership signal next to the tier, and fall back to pull-only when it fails. The cheapest one is already fetched: _validate_github_access gets repo_info.private from check_repo_exists, so a public repo would stay pull-only. The stronger check is repo owner == the token's login. A catalog template (gh_template set) should never qualify. Then flip that test so it asserts pull-only for a shared public repo.

2. [should-fix] Following the runbook moves a live agent onto main and auto-pushes there. docs/migrations/AGENT_WORKING_BRANCH_DEFAULT_2026-09.md:25-33

   • Step 2 flips the row to source_mode = 0.
   • Step 3 recreates the container. On a recreate, lifecycle.py:878 clears GIT_SOURCE_MODE. startup.sh:254 keeps the branch already checked out on the volume, which is the default branch for a source-mode agent. GIT_WORKING_BRANCH is only read when cloning, so nothing checks out the working branch.
   • Step 4 turns auto-sync on. #3011's refusal (agent_server/routers/git.py:771, :882) only fires when GIT_SOURCE_MODE=true, so the heartbeat runs git push origin HEAD straight to main. The issue says this must never happen for repos that deploy on push.
   • Step 2 also has no supported path. No endpoint writes source_mode on an existing agent, so an operator would be editing the DB by hand.
     Fix: add a step that checks out the working branch in the workspace before auto-sync is enabled, and a check that fails closed if HEAD is still the default branch. Name the exact supported way to flip the row, or say this waits for ent#230.

3. [should-fix] Two create paths can't say "deployment", so they silently get the agent default.

   • System manifests: SystemAgentConfig (src/backend/models.py:1234) has no kind. system_service.py:1921 builds AgentConfig without source_mode, so every manifest agent from a shared template takes the new default with no way to opt out. It also runs one push probe per agent, one after another.
   • CLI: trinity deploy --repo (src/cli/trinity_cli/commands/deploy.py:232) is by name a deployment of a codebase, but it now creates an agent.
     Fix: add kind to SystemAgentConfig and pass it through, and send kind: "deployment" from trinity deploy. If that's out of scope, list both in §11.17 as known gaps.

4. [nit] The per_agent tier can't happen at create. _resolve_github_repo_and_pat calls resolve_github_pat(owner_id=...) without agent_name (crud.py:704, :722), so the tier is never per_agent on this path. test_ent705_an_agents_own_token_earns_it_like_the_creators calls the helper directly with a tier production can't produce. Either drop "or the agent's own" from the docs and the AgentConfig.kind comment, or say it's there for future callers.

5. [nit] Stale status line. docs/memory/requirements/github.md:820 still says "Merges only after #3016, #3017 and #3018". Those have landed.

What I checked

• Scope: the PR's own diff only (origin/dev...8b20c171, 11 files), not the merged-in dev commits.
• Auth: there's no new endpoint or gate. An agent-scoped key creating a child resolves to the owner's per_user token, same as before. That could already ask for source_mode=false over REST, so it's not a new grant.
• Data and ordering: no schema change and no new trigger, so Invariant #18 doesn't apply. git_mode is set after the broadcast (#918). The MCP kind field matches the backend.
• Tests: 12 related suites (1484, fork_to_own, ent14, models_centralized, 2107, 3010, 3011, ent123, 2069, 69 ephemeral, ent109 seam and extraction) pass with seeds 12345 and 99999: 362/362 each run. MCP: tsc --noEmit clean, npm test 550/550. gh pr checks is green.

[dolho]

Review of 09-28 addressed in d8a9fd0f8 and 325be3ae8.

1. [blocking] Pushable ≠ owned. d8a9fd0f8. I went with the stronger signal: repo owner == the token's GitHub login.

• The login costs one GET /user (GitHubService.validate_token_detailed, the same call Settings uses to validate a personal token). The check runs only after the tier gate passes, so it adds one call on the per_user path.
• A catalog template (gh_template set) never qualifies and is never probed.
• If the login can't be read (invalid, unreachable, empty), the agent is pull-only: "could not confirm the repository is yours".
• If the owner isn't the login, the agent is pull-only, and the reason names the owner and the login and points to fork-to-own.
• Tradeoff to flag: an org-owned repo stays pull-only by default, private ones included. An explicit source_mode=false over REST or MCP still asks for a working branch, and bug: git-sync write access is never validated — a read-only credential fails silently forever (ls-remote and the REST permissions.push field both lie) #2107's 400 still guards that path. If you'd rather also admit private org repos, it's a one-line or repo_info.private. I left it out because a private org repo is still a repo someone else owns.
• Tests: …with_push_access_gets_the_trio is replaced.
  • …a_shared_catalog_template_stays_pull_only_even_when_pushable: Abilityai/cornelius with a per_user token and probe=ok stays pull-only and is never probed.
  • …a_repo_someone_else_owns_stays_pull_only_even_when_pushable: the same repo named directly.
  • Positive case: …on_the_creators_own_repo_gets_the_trio (alice/brain, login alice).
  • Also added: a case-insensitive login match and three unknown-login cases.
  • The 5 new negative cases fail on 8b20c1714.

Fork reason (from the #3022 review). d8a9fd0f8. The fork branch now runs before the explicit-source_mode branch, because _apply_fork_to_own's assignment lands in model_fields_set. test_ent705_a_fork_is_reported_as_a_fork_after_fork_to_own_ran assigns source_mode the way the fork does, asserts the trap, and then asserts the fork reason. It fails before the fix.

2. [should-fix] Runbook. 325be3ae8.

• It now says in-place migration waits for ent#230: no endpoint writes source_mode, and the DB must not be edited by hand. The alternative it gives today is a new agent from the same repo, or "Bind to your own repo".
• For after ent#230, it adds two steps before auto-sync:
  • an explicit git checkout -B trinity/<agent>/<id> plus push -u, because a recreate keeps the checked-out default branch;
  • a fail-closed shell check that must print ok: HEAD is not the default branch and is a trinity/* branch.
• It explains why: bug(git-sync): the auto-sync heartbeat pushes without fetch or rebase — on a shared branch it fails non-fast-forward forever after the first foreign push #3011's refusal only fires in source mode.

3. [should-fix] Create paths that can't say "deployment".

• CLI: 325be3ae8. trinity deploy --repo sends kind: "deployment", guarded by an AST test, tests/unit/test_ent705_cli_deploy_kind.py. It's static because the unit job doesn't install click/rich.
• Manifests: the per-agent kind is feat(git-sync): ask "what is this repository?" at create (trinity-enterprise#704) #3022's manifest passthrough. Until that lands, the ownership rule already keeps manifest agents off shared templates. §11.17 now says both.

4. [nit] per_agent. The docs, the helper docstring and the test now say it's accepted for future callers; no create path resolves it today.

5. [nit] Stale status line. Fixed.

Verification

• The 1484, fork_to_own, ent14, models_centralized, 2107, 3010, 3011, ent123, 2069, 69-ephemeral, ent109, ent162 and new CLI suites: 791 passed on seeds 12345 and 99999.
• This excludes test_ent14_registry_url_ssrf.py, whose 4 IPv4-mapped cases fail locally on py3.12 on the unmodified branch too.
• MCP tsc --noEmit is clean. Merging with dev is clean (merge-tree).

🤖 Generated with Claude Code

[obasilakis]

Approving.

Checked locally on c370041a (py3.13, seed 12345): the PR's suites pass 145/145. Mutating each of the tier gate, catalog-template gate, owner==login gate and the freeze-on write turns at least one test red, so the new tests execute the decision path. CI is green, merge with dev is clean.

Two things to be aware of, neither blocking:

• Org-owned repos (private included) never get the working-branch default; only repos owned by the token's own login do. Worth an explicit product call from vybe, since most team repos are org-owned.
• Freeze-on-sync-failure is now written for every auto-pushing create whose kind is unset, which includes existing callers that send source_mode=false explicitly, and ghosts.

After merge, ent#705 needs status-in-dev set by hand (cross-tracker ref). #3021 and #3022 merge after this.

All five points from this review are addressed in d8a9fd0 and 325be3a (owner == token login gate, runbook waits for ent#230, CLI sends kind=deployment, per_agent documented, stale line fixed). Re-verified and approved; dismissing to unblock merge.