RFC: repository-scoped managed agents and live context pressure

# 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

- #3242 — repeated context injection and active-context pressure
- #2961 — unbounded per-channel ACP sessions and missing resource visibility
- #3148 — macOS agents can inherit `cwd=/`
- #3124 — Windows workspace-path handling
- #3126 — workspace grounding missing for protocol-v1 Claude/Codex harnesses
- #2660 — isolation of Buzz-managed Codex session history
- PR #2035 — historical NIP-AM token/cost usage
- PR #3068 — local per-agent usage dashboard
- PR #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.

Rebase any investigation on current main, a35771fc441cdc3c6f517f419037206783b502d2. Start with the existing managed-agent session surface and the agent save/spawn paths, including command.current_dir(...) and current usage_update handling. Done means maintainers approve the two separable scopes and their validation, restart, hashing, session-invalidation, and nest-versus-repository test boundaries.

Written by the indexing model from the issue text.