feat(profiles): route launches, status and Usage through the frozen session profile (#1064 3b-ii 3/3)

[matraket]

Review size: 384 changed lines (+315/-69). #1825 and #1826 are merged and this branch is rebased on main, so the Files tab shows exactly this slice (commits c6a48a2a and 9c3fdb7e). Review follow-ups are in #2007.

Summary

Part of #1064, slice 3b-ii. Wires the frozen session profile into every consumer that slice 2 (#1557/#1558) covered, through the single resolver from PR 1, and documents it.

• Launch and non-Git writer admission (extensions/gentle-agents.ts) resolve the session profile once per request through resolveSessionProfile, so admission and launch cannot disagree (the feat(profiles): resolve the session binding in launches, status, and usage (#1064 2/2) #1558 "Writer effective profile or session changed during preparation" class).
• Startup freeze in the parent-only session_start of gentle-agents, for every reason Pi reports (startup also covers --resume/--continue/--session). Idempotent per session id, so /reload keeps it.
• Drift notice on each launch from a frozen session, measured against the session's own directory, never the delegated target.
• Footer status and Usage scope (extensions/gentle-shell.ts) use the same rule and keep the existing labels; no new UI and no "frozen" wording.
• Docs: new section "Session profile frozen at startup" in docs/readme-reference.md, plus the Usage scope wording in docs/gentle-shell.md.

Behavior change for unpinned sessions. Without a pin or declaration, launches now use the global active profile from profiles.json, replacing the materialized subagents.json routing wholesale like a pin does. Before, an unpinned launch read the materialized stores. With no pin and no active, nothing changes. This moves unpinned sessions off the materialization ahead of PRD PR 5, which removes it.

This is PR 3 of 4.

follow is opt-in through the environment variable GENTLE_PI_PROFILE_FOLLOW=1 only. There is no Pi flag yet: flags are registered per extension, so it was deferred (the earlier "flag or env" wording in #1826 referred to the plan).

Issue

Part of #1064

PR type

• New feature (type:feature)

Changes

Commit	Change
c6a48a2a	Launch, admission, startup freeze and drift notice in gentle-agents; status reader and Usage in gentle-shell; their tests.
9c3fdb7e	Docs.

Existing tests whose expectations changed, each by design:

• gentle-agents fixtures pin GENTLE_PI_CONFIG_HOME to the scratch config home; otherwise the new global layer read the developer's own profiles.json.
• The writer-admission fixture writes its repository declaration before session_start, since a declaration added after start no longer applies to the open session.
• The status polling test runs with GENTLE_PI_PROFILE_FOLLOW=1 to keep exercising live refresh.
• The Usage profile-switch test switches through an explicit binding.

Test plan

Rebased on main (833054d9) after #1825 and #1826 merged; the only conflict was the Usage paragraph in docs/gentle-shell.md, resolved by keeping main's Codex-window text and this PR's scope wording. Re-verified after the rebase:

• Full unit suite before the rebase: 4991 pass, 0 fail, 44 skipped. provider-contract and runtime-harness pass.
• Focused (session-profile-freeze, gentle-agents, gentle-shell, session-profile-binding, profile-pin, gentle-ai): 692 pass, 0 fail.
• New launch-seam tests: freeze at start with a later pin change and one notice across two launches; unpinned session routed through and frozen on the global active; no profile anywhere keeps today's routing after a pin appears; explicit binding wins without notice; follow re-resolves and Enter makes it explicit. New shell tests: status and Usage keep the frozen profile after the defaults change; follow shows the live default. Both shell tests fail against the previous gentle-shell.ts.
• check-types: no regressions.
• Independent verification (read-only subagent): no blocking findings; its one gap (no-profile foreign launch) is fixed in PR 2.
• Native review (RDD): approved before and again after the rebase, no corrections.
• Not verified: a real Pi --resume, /reload or /new run, and extension load order in a live process.

Review follow-ups (non-blocking, from the native review)

• Warning: no launch-seam test for a foreign repository_root launch from a frozen session. Added in chore(profiles): review follow-ups for the frozen session profile (#1064 3b-ii 4/4) #2007, together with the cheap seam test @barbatdev suggested on feat(profiles): add follow mode, the drift notice and per-target routing (#1064 3b-ii 2/3) #1826.
• Warning: drift notice edge cases at the launch seam (:1469-1478).
• Warning: the status reader falls back to the global name when cwd is undefined (extensions/gentle-shell.ts:204); not reachable today, since bind always sets cwd and reset unbinds.
• Suggestions: the footer can freeze before gentle-agents' session_start (correct, but order-dependent); a failed startup freeze is swallowed and retried lazily on the next launch.

Known limitations

• The /gentle:profiles "Current routing (effective)" table still reads the explicit binding or the materialized routing (extensions/gentle-ai.ts:4841,4857). It is a slice 3c consumer, so it can differ from launches until then.
• The status reader resolves the config home with ?? while launch uses ||; only GENTLE_PI_CONFIG_HOME="" is affected. Pre-existing; PRD PR 1 unifies it.
• RDD reviewer routing (readReviewerModelConfig, extensions/gentle-ai.ts:2203, from fix(profiles): apply orchestrator and reviewer routing per session #1886) reads the explicit binding, then the pin, then models.json, so reviewers do not see the frozen profile yet. Another slice 3c consumer.
• In-memory freeze until 3b-i (see feat(profiles): freeze the inherited session profile at startup (#1064 3b-ii 1/3) #1825).

Chain Context

Field	Value
Chain	#1064 slice 3b-ii: inherited profile freeze, drift notice, follow
Tracker PR	Not needed
Position	3 of 4
Base	main (each PR is opened against main; until its predecessors merge, its diff also shows their commits, and I rebase it as they land)
Depends on	#1825, #1826 (both merged)
Follow-up	#2007 (review follow-ups); startup entry write, stacked on @noxsystems' 3b-i chain
Review budget	384 changed lines (+315/-69), of which 208 are tests and 46 are docs.

main
 ├─ #1825 freeze core (merged)
 ├─ #1826 follow, drift notice, per-target routing (merged)
 └─ #1827 launch, admission, status, Usage, docs       📍 this PR
   └─ #2007 review follow-ups

Review only the commits listed under Changes.

Summary by CodeRabbit

• New Features
  • Sessions retain the profile and routing resolved at startup, so later changes to defaults, repository settings, or profile content apply to new sessions rather than changing existing ones.
  • Selecting a profile in a session updates provider routing and the profile used for Usage and Status. In follow mode, default changes are reflected on the next refresh.
  • The profile indicator distinguishes session-selected profiles and shows the profile resolved at startup.
• Documentation
  • Clarified profile resolution, session behavior, and usage-source routing.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository UI
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: 5b92b60e-b299-4034-a17e-27b4d32e5c7a

---

📥 Commits

Reviewing files that changed from the base of the PR and between 97a5244 and 9c3fdb7.

---

📒 Files selected for processing (6)

• docs/gentle-shell.md
• docs/readme-reference.md
• extensions/gentle-agents.ts
• extensions/gentle-shell.ts
• tests/gentle-agents.test.ts
• tests/gentle-shell.test.ts

---

Included review availability: This review used your included allowance. Your plan provides up to 4 included reviews per hour; 3 remain after this review.

---

---

📝 Walkthrough

Walkthrough

Parent sessions now resolve and freeze inherited profiles at startup. Agent launches, Status, and Usage use the session profile resolution. The changes also add follow mode, drift notices, routing rules for foreign repositories, tests, and documentation.

Changes

Session profile resolution and routing

Layer / File(s)	Summary
Resolve and freeze inherited profiles lib/session-profile-freeze.ts, tests/session-profile-freeze.test.ts, odd/tasks/1064-inherited-profile-freeze.md	The new resolver applies local, repository, and global profile precedence, and freezes inherited profiles per session. It also handles explicit bindings, follow mode, target routing, profile labels, and drift notices. Unit tests cover these behaviors.
Apply session profiles to agent launches extensions/gentle-agents.ts, tests/gentle-agents.test.ts	Agent request creation uses the resolved parent session profile for writer admission and target routing. Session startup attempts to freeze inherited routing. Tests cover profile changes, bindings, follow mode, and launch fixtures.
Use session profiles in Status and Usage extensions/gentle-shell.ts, tests/gentle-shell.test.ts, docs/readme-reference.md, docs/gentle-shell.md	Status labels and Usage provider scope use session profile resolution. Tests cover frozen and follow-mode refresh behavior. The documentation describes profile display, freezing, routing, drift notices, and refresh scope.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant Parent as Parent session
  participant Startup as session_start
  participant Resolver as resolveSessionProfile
  participant Request as buildRequest
  participant Routing as sessionProfileRoutingAt
  Startup->>Resolver: freeze inherited profile
  Request->>Resolver: resolve profile for writer admission
  Request->>Routing: select routing for target
  Routing-->>Request: target model profiles

Loading

Suggested reviewers: alan-thegentleman, danielgap

---

Merge Risk: ⚪ Minimal · up to 9c3fd

No actionable issue remains from this review; the change is mergeable after normal checks.

Pre-merge checks | 4 | 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 48.28% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 29 functions across 6 files. (2 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly and concisely describes the main change: routing launches, status, and Usage through the frozen session profile.

---

Full details: Docstring Coverage

Explanation

Docstring coverage is 48.28% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 29 functions across 6 files. (2 skipped: 2 unsupported.)

---

---

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

---

---

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

---

_{Comment @coderabbitai help to get the list of available commands.}

[danielgap]

Approve, with two non-blocking observations. Verified locally: 473/473 across gentle-agents.test.ts and gentle-shell.test.ts, which includes the #1558 invariants (admission/launch parity, queue freeze); the composition preserves them: the seam still resolves once per task request, before admission, now through resolveSessionProfile. #1824's files (the gentle-ai.ts panel and its tests) are untouched by this chain, so the overlap is the docs file only.

1. The branches stack, so GitHub shows cumulative diffs (689 and 1073 lines) while the per-slice increments are 314 and 315. Consider noting the true increment in each PR body so the review load is visible.
2. The #1558 native-review advisory (the explicit-binding branch of the usage path in activeRoutingModels) is now covered for the frozen profile by the new status+Usage test, but the explicit-binding usage branch remains incidental. A small follow-up test fits either here or with 3b-i's coverage plans; happy to take it.

[matraket]

Thanks @danielgap for checking all three slices locally, and for going straight at the foreign-repository semantics.

1. Fair point. I moved each slice's own size to the top of the three descriptions, with the commits to review, so the cumulative Files tab does not hide the real load.
2. You are right, and I overstated it on the issue: the profile-switch test here only touches the explicit-binding branch of activeRoutingModels in passing. test(profiles): cover the explicit session binding's Usage scope (#1064) #1837 is the direct assertion it was missing, thanks for taking it.

[danielgap]

Thanks @matraket, putting each slice’s own size and review commits at the top makes the chain much easier to review.

Agreed on the coverage distinction: the profile-switch test exercises the explicit-binding branch incidentally, while #1837 provides the direct assertion. That addresses the two non-blocking observations from my review; my approval stands.