RFC: repository-scoped managed agents and live context pressure

[Lakris2407]

RFC: repository-scoped managed agents and live context pressure

Summary

I would like maintainer direction on two small, separately shippable
improvements:

1. Show live context-window pressure in the existing managed-agent session
   surface.
2. Let an owner optionally start a managed agent inside an existing local Git
   repository or worktree.

This RFC intentionally defers automatic project/channel repository switching
and automatic worktree creation.

The proposal was prepared against
3afa129ee785cc74d921d0ba969254a8255c4cc0. Current main is
a35771fc441cdc3c6f517f419037206783b502d2; the intervening agent-catalog
commit changes several agent model, API type, dialog, runtime-test, and
spawn-hash surfaces, so any implementation would first rebase its design on
current main.

Why

Managed agents currently start in the Buzz nest, normally ~/.buzz. That
prevents repository-specific AGENTS.md, CLAUDE.md, Codex configuration, and
Claude-memory project scoping from loading naturally for a selected checkout.
Buzz already passes process cwd into ACP sessions and already receives live
usage_update { used, size } data, so both improvements appear possible without
adding credential or billing systems.

Proposed PR 1: thin live context-pressure indicator

Extend the existing session UI to render a value such as:

72K / 200K · 36%

Semantic states:

• below 60%: normal
• 60–80%: approaching limit
• above 80%: high pressure
• unknown or zero size: token count only, without a percentage
• after rotation: “Fresh session” until the first usage update
• substantial usage decrease within one session: temporarily show “Compacted”

This is current-session context pressure only. It would not add historical
7/30-day charts, subscription allowance, billing estimates, automatic rotation,
or ACP compaction changes.

Proposed PR 2: optional per-agent working directory

Add an advanced agent field named Repository or worktree with an optional
local execution-directory value. Precedence:

1. validated per-agent repository/worktree
2. existing Buzz nest default

Changing it must restart the managed agent and discard cached ACP sessions.
Old agent records without the field must behave as before.

One backend validation path, reused at save and spawn, should:

• require an absolute, existing, readable path
• call git rev-parse --show-toplevel with direct process arguments
• support normal checkouts and worktrees whose .git is a file
• canonicalize to the checkout/worktree root
• reject filesystem root and the user home directory
• fail agent startup with an actionable error if the checkout disappears
• never silently fall back to ~/.buzz

The canonical directory should be included in the spawn configuration hash and
passed to command.current_dir(...).

Buzz should separately expose the coordination nest to buzz-acp, for example
through BUZZ_ACP_NEST_DIR, so prompts distinguish:

• active working directory
• Buzz coordination nest
• configured repository collection

Buzz must not create REPOS, OUTBOX, or other nest folders inside the
selected repository.

Security and compatibility boundaries

Buzz must not:

• store or copy GitHub PATs, Claude/Codex credentials, cookies, or private keys
• add provider login flows
• copy or inject Claude-memory database contents
• construct shell commands from paths
• automatically delete, reuse, push, merge, or modify Git worktrees/branches
• claim filesystem read-only isolation that Buzz does not enforce

The selected cwd should continue using the user's existing local provider login
and Git credential helper without Buzz reading those credentials.

Tests should cover POSIX and Windows absolute paths, symlinks/canonicalization,
normal repositories, .git-file worktrees, deleted checkouts, storage
round-trips, spawn-hash changes, restart/session invalidation, and separation of
nest versus active repository.

Questions for maintainers

1. Is a thin live context-pressure indicator acceptable in the existing agent
   session surface, distinct from historical usage dashboards?
2. Is an optional per-agent repository/worktree override the preferred first
   step for repository-aware managed agents?
3. Should dynamic project/channel repository binding remain a separate later
   design?

If yes, where is the smallest acceptable UI location for the context indicator,
given the existing session surfaces and current file-size limits?

Related work

• Reduce repeated full-context injection for agent turns #3242 — repeated context injection and active-context pressure
• [Bug] Per-channel ACP sessions are never released: on Windows each live session pins a full agent process tree (~33 procs / ~2 GB), exhausting the commit limit until Windows kills the WebView2 host and the desktop silently renders black #2961 — unbounded per-channel ACP sessions and missing resource visibility
• [Bug] macOS: Claude Code agents spawn with cwd=/ each session pins a CPU core on a full-filesystem ripgrep scan #3148 — macOS agents can inherit cwd=/
• Windows agents never receive the [Workspace] system-prompt section: workspace_section() gates on a POSIX-only starts_with('/') predicate #3124 — Windows workspace-path handling
• [Workspace] system-prompt anchor never reaches protocol-v1 harnesses: Claude Code and Codex lose absolute-cwd grounding on all platforms #3126 — workspace grounding missing for protocol-v1 Claude/Codex harnesses
• Isolate Buzz-managed Codex sessions from the user's Codex sidebar and Remote project list #2660 — isolation of Buzz-managed Codex session history
• PR feat(desktop): add Agent Usage UI backed by the NIP-AM local archive #2035 — historical NIP-AM token/cost usage
• PR feat(desktop): add per-agent usage dashboard #3068 — local per-agent usage dashboard
• PR Draft: full-screen shared agent session view (multi-person, live tool streaming) #3050 — draft shared session view with live tokens/tool progress

Sequencing

No large implementation should start before maintainer direction. If accepted:

1. Land PR 1 independently, limited to live context pressure.
2. Land PR 2 independently, limited to an optional per-agent local working
   directory and explicit nest separation.
3. Design project/channel binding and automatic worktree allocation later, with
   separate concurrency, ownership, cleanup, recovery, and credential-failure
   rules.

[Lakris2407]

Investigation addendum — corrected PR 1 premise

Read-only inspection and independent review at
a35771fc441cdc3c6f517f419037206783b502d2 found that the current transcript
does not render a production usage line.

• agentSessionTranscript.ts admits usage only under session/update, while
  in-repository producers emit _goose/unstable/session/update.
• The desktop reads size; the producer-shaped field is contextLimit.
• The current cost branch expects cost.amount/cost.currency; producers
  expose flat accumulatedCost without a display currency.
• Existing desktop tests inject the synthetic desktop shape, so they remain
  green while a producer-shaped frame renders no usage row.

This changes PR 1 from presentation-only work to two distinctly reviewable
concerns:

1. Parser correction: accept the real method and contextLimit, remove the
   unsupported cost display, and pin an exact producer-shaped test frame.
2. Presentation/session state: percentage bands, “Fresh session,” and
   temporary “Compacted” state.

Additional review decisions:

• Keep the RFC behavior for missing or zero contextLimit: if used is valid,
  render the token count without a percentage. buzz-agent deliberately emits
  contextLimit: 0; suppressing it would leave those sessions without an
  indicator.
• Do not reuse UsageTracker decrease logic for “Compacted.” Before that state
  is implemented, define the substantial-drop threshold and temporary
  duration, track previous usage by channel plus session, clear state on
  session change, and test rotation before the next usage frame.
• Treat PR Draft: full-screen shared agent session view (multi-person, live tool streaming) #3050 as semantic ownership overlap. It already adds live token/cost
  status from transcript lifecycle text. Please choose one owning surface and
  one typed derivation; this proposal should not add a second parser of rendered
  transcript text.
• Keep [Bug] macOS: Claude Code agents spawn with cwd=/ each session pins a CPU core on a full-filesystem ripgrep scan #3148 as a known fail-loud cwd regression requirement. Current main
  intends to apply the resolved Buzz nest/home; the field report does not yet
  identify why some macOS sessions inherited /.
• agentSessionTranscript.ts is 1173 lines against a 1202-line override.
  Parser edits should remain near net-zero, with formatting and session-state
  logic moved to a new tested module.
• If accessibility text promises exact token counts, validate finite,
  nonnegative JavaScript safe integers or carry decimal strings end-to-end for
  full u64 exactness.

No implementation, dependency installation, commit, push, or PR was made. The
local verification environment currently lacks sufficient disk space, so
pnpm test, pnpm typecheck, pnpm check, and just ci have not run.

Updated maintainer questions:

1. Should the parser correction land as a small PR before context-pressure
   presentation, or should both be one PR with distinctly reviewable commits?
2. Which existing session surface should own the live indicator given PR
   Draft: full-screen shared agent session view (multi-person, live tool streaming) #3050, and what typed source should both surfaces share?
3. What numeric drop threshold and display duration should define
   “Compacted”?