fix: preserve staged and unstaged changes per file (#3104)

This commit is contained in:
José Almeida
2026-08-30 13:26:18 +00:00
committed by GitHub
parent c946140812
commit cc2ee0b43d
48 changed files with 2075 additions and 112 deletions
@@ -0,0 +1,77 @@
# ADR-2026-08-27-mixed-git-change-facets: Preserve mixed Git changes as path facets
**Status:** accepted
**Date:** 2026-08-27
**Area:** backend, agentctl, frontend, protocol
## Context
Git porcelain reports the index and working tree independently. A tracked path can therefore have a
staged edit and a later unstaged edit (`MM`), while a newly staged path can receive another unstaged
edit (`AM`). Kandev currently collapses both columns into one `FileInfo`. The parser prioritizes the
working-tree column, so the file appears only under Unstaged, and its `HEAD`-relative diff merges both
layers.
The file path is still one mutation and review identity. Duplicating the path in the status map would
distort changed-file counts, path-based stage operations, multi-repository keys, carry-forward logic,
and Review deduplication. Replacing the wire shape outright would also break stored snapshots and
older frontend consumers. The model needs to retain one path identity while exposing two independently
selectable change layers.
## Decision
`GitStatusUpdate.Files` remains a map with one entry per repository-relative path. `FileInfo` keeps
its existing flattened fields and adds two optional facet objects: `staged_change` and
`unstaged_change`. A facet carries status, additions, deletions, old path, diff content, and diff skip
reason.
Agentctl emits both facet objects when the porcelain index and working-tree columns both describe a
change. Single-layer paths retain the existing compact shape. For mixed paths, the flattened fields
remain the existing compatibility projection: worktree-priority classification plus the combined
`HEAD`-to-working-tree diff. The staged facet is computed from `HEAD` to the index, and the unstaged
facet from the index to the working tree.
New consumers use the facets when present and fall back to the flattened fields otherwise. Changes
may project two temporary rows, but raw status, Review aggregation, badges, and Git mutations remain
keyed once by `(repository, path)`. A diff target is keyed by `(repository, path, layer)` so opening
the staged and unstaged rows cannot resolve to the same content or pinned panel.
Every serialized diff representation participates in the existing total snapshot budget and retains
the existing per-representation output cap and skip reasons. Facet metadata survives even when its
diff content is skipped. Git unmerged/conflict states are not redefined by this decision.
## Consequences
- Desktop and mobile Changes can show one path in both Staged and Unstaged with accurate layer stats
and diffs.
- Existing snapshots and clients remain decodable because the flattened fields stay present and the
new fields are optional.
- Mixed entries can serialize more diff content than single-layer entries, but the shared snapshot
threshold still bounds total enrichment.
- Frontend equality checks, diff identities, and focus fingerprints must include the layer/facet data
or facet-only updates can be missed.
- Stage, unstage, discard, Review deduplication, and changed-file totals must never treat a projected
facet row as a second path mutation.
## Alternatives Considered
### Add two status-map entries with synthetic path keys
Rejected. Synthetic keys would leak into path operations, changed-file counts, multi-repository
identity, editor synchronization, and Review deduplication.
### Replace `FileInfo` with an array of layer records
Rejected. This is a breaking wire and stored-snapshot migration for a state that can be represented
additively. Older consumers would fail to decode or render ordinary status snapshots.
### Keep one record and concatenate staged and unstaged diffs
Rejected. A separator can make both hunks visible, but it cannot give each section accurate status,
line totals, selection identity, or staging transitions.
### Fetch a layer-specific diff only after row selection
Rejected for this repair. It avoids duplicate streamed diff content but adds a new request lifecycle,
loading and failure states, and cache invalidation path to a panel that already receives bounded diff
data. The existing snapshot budget is sufficient for the additive facet contract.
+1
View File
@@ -214,4 +214,5 @@ Read individual ADRs for full context. Create new ones via `/record decision` or
| 2026-08-27-bounded-agent-profile-recency | [Store Agent Profile Recency in Bounded Context Rows](2026-08-27-bounded-agent-profile-recency.md) | accepted | backend, frontend, protocol | 2026-08-27 |
| 2026-08-27-protect-deferred-launch-attribution | [Protect Deferred Launch Attribution](2026-08-27-protect-deferred-launch-attribution.md) | accepted | backend, protocol | 2026-08-27 |
| 2026-08-27-preserve-legacy-sqlite-before-default-initialization | [Preserve Legacy SQLite Data Before Default Initialization](2026-08-27-preserve-legacy-sqlite-before-default-initialization.md) | accepted | backend, cli, operations | 2026-08-27 |
| 2026-08-27-mixed-git-change-facets | [Preserve mixed Git changes as path facets](2026-08-27-mixed-git-change-facets.md) | accepted | backend, agentctl, frontend, protocol | 2026-08-27 |
| 2026-08-28-bind-github-auto-merge-attempts-to-reviewed-head | [Bind GitHub Auto-Merge Attempts to the Reviewed Head](2026-08-28-bind-github-auto-merge-attempts-to-reviewed-head.md) | accepted | backend, frontend, protocol, security, GitHub | 2026-08-28 |
@@ -0,0 +1,120 @@
---
created: 2026-08-27
status: completed
requirements:
- REQ-PLATFORM-WORKSPACE-GIT-STATUS-001
system_design:
- ../../specs/platform/system-design/workspace-git-status.md
legacy_specs: []
---
# Implementation Plan: Mixed Staged and Unstaged Changes
## Overview
Preserve both Git layers for one path, then project them into accurate Changes rows and diff targets.
Implementation starts with red backend, desktop, and mobile regressions; publishes the additive
agentctl contract next; then consumes it in the shared frontend so both platform layouts turn green.
## Scope
### In scope
- Preserve staged and unstaged facets for ordinary mixed porcelain states such as `MM` and `AM`.
- Keep one raw repository/path identity while rendering facet-specific rows, stats, and diffs.
- Route desktop and mobile diff selection by change layer.
- Preserve current file-level stage, unstage, discard, Review, and unique changed-file counts.
- Keep facet diff content inside the established status-snapshot budget.
### Out of scope
- Hunk-level staging.
- New conflict or unmerged-state semantics.
- A Changes panel visual redesign.
- A new on-demand diff API.
## Technical approach
### Agentctl status contract
Add `FileChangeFacet` plus optional `StagedChange` and `UnstagedChange` fields to
`apps/backend/internal/agentctl/types/streams/git.go`. Refactor `applyPorcelainLine` in
`workspace_git_status.go` to interpret the `X` and `Y` columns independently while preserving the
one-path compatibility projection.
Extend `workspace_git_diff.go` so a mixed path retains its existing `HEAD`-relative flattened diff,
gets a staged `git diff --cached HEAD -- <path>` facet, and gets an unstaged
`git diff -- <path>` facet. Teach diff-budget accounting and same-HEAD carry-forward to traverse the
optional facets. No facet diff may bypass the shared threshold or existing skip-reason vocabulary.
### Frontend projection
Mirror the optional facet type in both frontend wire models. Add a pure projection helper under
`apps/web/hooks/domains/session/` that returns staged and unstaged `FileInfo` views for Changes while
keeping `allFiles` unique. `useSessionGit` and multi-repository summaries use those projected arrays
for section and action availability. Store equality, editor synchronization, and Changes focus
fingerprints include facet data so a layer-only update is observable.
Review's aggregate uncommitted source continues to use the flattened compatibility file. Mutation
dispatch continues to receive only repository plus path, even when both projected rows exist.
### Layer-qualified diff selection
Add a staged/unstaged layer to `OpenDiffOptions` and file-mode `DiffSheetMode`. Propagate it through
Changes rows, TaskChangesPanel selection, Dockview preview/pinned IDs, and the mobile diff drawer.
Layer-qualified selections project the matching facet; legacy and non-layer selections keep the
combined uncommitted view. The same shared Changes body remains in desktop and mobile layouts.
This approach implements
[ADR-2026-08-27-mixed-git-change-facets](../../decisions/2026-08-27-mixed-git-change-facets.md).
## Tests
- `AC-PLATFORM-WORKSPACE-GIT-STATUS-001.7` and `.9`: add
`apps/backend/internal/agentctl/server/process/workspace_git_mixed_changes_test.go` covering `MM`,
`AM`, independent numstat/diff content, carry-forward, and shared budget accounting.
- `AC-PLATFORM-WORKSPACE-GIT-STATUS-001.10` and `.11`: add
`apps/web/hooks/domains/session/git-change-facets.test.ts` for unique raw identity, two projections,
layer stats, and mutation-path deduplication; extend Git summary and status equality tests.
- `AC-PLATFORM-WORKSPACE-GIT-STATUS-001.10`: extend
`apps/web/components/task/task-changes-panel.test.ts` and
`apps/web/lib/state/dockview-panel-actions.test.ts` for layer-specific content and panel identity.
- `AC-PLATFORM-WORKSPACE-GIT-STATUS-001.12`: add focused mobile component coverage proving the same
facet target reaches the existing full-height diff drawer.
## E2E tests
- Desktop, `AC-PLATFORM-WORKSPACE-GIT-STATUS-001.10` and `.11`: extend
`apps/web/e2e/tests/git/git-changes-panel.spec.ts` with a tracked `MM` file. Assert the same path is
present in both sections, each row shows its own line count and diff, and unstage leaves the
unstaged facet.
- Mobile, `AC-PLATFORM-WORKSPACE-GIT-STATUS-001.12`: extend
`apps/web/e2e/tests/task/mobile-changes-panel.spec.ts` with the same setup and assert both sections,
layer-specific drawer content, and touch staging behavior.
## Work orders
- [x] [Task 01: Capture mixed-change regression](task-01-capture-mixed-change-regression.md)
- [x] [Task 02: Publish mixed-change facets](task-02-publish-mixed-change-facets.md)
- [x] [Task 03: Render layer-specific changes](task-03-render-layer-specific-changes.md)
## Verification results
- Task 01 RED evidence captured. Agentctl omitted `staged_change`; desktop and mobile could not find
the staged section for the mixed path.
- Task 02 published additive staged and unstaged facets with independent diffs, bounded shared
accounting, and budget-aware carry-forward. The focused and package-level Go suites passed.
- Task 03 projected one raw path into two layer-qualified rows and diff targets while retaining
unique totals and mutation identity. Focused frontend tests, typecheck, lint guards, and fresh
desktop/mobile Playwright regressions passed, including the unstage transition.
## Risks
- Compatibility and facet diffs duplicate content for mixed paths; incorrect budget accounting could
exceed the bounded snapshot contract.
- A path shown twice can accidentally double-count badges or dispatch the same mutation twice unless
raw identity and projected presentation remain separate.
- Omitting the layer from a Dockview or mobile selection key would reopen the bug by showing the
combined or wrong facet diff.
- Rename/delete combinations use different porcelain and numstat path shapes; parser tests must prove
that ordinary supported mixed states retain the correct final path.
@@ -0,0 +1,85 @@
---
id: "01-capture-mixed-change-regression"
title: "Capture mixed-change regression"
status: completed
wave: 1
depends_on: []
plan: "plan.md"
requirements:
- REQ-PLATFORM-WORKSPACE-GIT-STATUS-001
acceptance_criteria:
- AC-PLATFORM-WORKSPACE-GIT-STATUS-001.9
- AC-PLATFORM-WORKSPACE-GIT-STATUS-001.10
- AC-PLATFORM-WORKSPACE-GIT-STATUS-001.12
system_design:
- ../../specs/platform/system-design/workspace-git-status.md
---
# Task 01: Capture mixed-change regression
## Summary
Create permanent backend, desktop, and mobile tests that reproduce the confirmed `MM` failure before
production changes. Record red results showing that the staged facet is missing and the diff is
combined.
## In scope
- Add a focused backend mixed-status test file.
- Add one desktop and one mobile Playwright regression using a real tracked file.
- Capture the expected red reason for each test before implementation.
## Out of scope
- Production contract or UI changes.
- Broad E2E suite execution.
## Acceptance
- The backend test expects independent staged and unstaged facets from one path.
- Both browser tests expect the same path in both sections and layer-specific diff content.
- Before correction, each targeted test fails only because current code collapses the two layers.
## Verification
```bash
cd apps/backend
go test ./internal/agentctl/server/process -run 'TestWorkspaceGitStatusPreservesMixedChangeFacets'
cd apps/web
pnpm e2e:run tests/git/git-changes-panel.spec.ts -- --grep "same path in staged and unstaged sections"
pnpm e2e:run --project mobile-chrome tests/task/mobile-changes-panel.spec.ts -- --grep "same path in staged and unstaged sections"
```
The commands are expected to fail at this red checkpoint. Save the precise assertion failures in the
work-order Results section before continuing.
## Files likely touched
- `apps/backend/internal/agentctl/server/process/workspace_git_mixed_changes_test.go`
- `apps/web/e2e/tests/git/git-changes-panel.spec.ts`
- `apps/web/e2e/tests/task/mobile-changes-panel.spec.ts`
## Dependencies
None.
## Risks
- E2E setup must mutate only its disposable fixture worktree and wait on observable status updates.
## Parallelism
`sequential`
## Inputs
- Requirement acceptance criteria `.9`, `.10`, and `.12`.
- Existing workspace Git process tests and desktop/mobile Changes E2E fixtures.
- Manual reproduction evidence from `MM README.md` and `AM mixed-stage-panel-test.txt`.
## Results
- `go test -json ./internal/agentctl/server/process -run '^TestWorkspaceGitStatusPreservesMixedChangeFacets$' -count=1` failed at the intended assertion: the `FileInfo` wire had one combined `+2` diff and no `staged_change` facet.
- Desktop Chromium failed at the intended assertion: `staged-files-section-collapse-toggle` was absent.
- Mobile Chrome failed twice at the same intended assertion: `staged-files-section-collapse-toggle` was absent.
@@ -0,0 +1,88 @@
---
id: "02-publish-mixed-change-facets"
title: "Publish mixed-change facets"
status: completed
wave: 2
depends_on:
- "01-capture-mixed-change-regression"
plan: "plan.md"
requirements:
- REQ-PLATFORM-WORKSPACE-GIT-STATUS-001
acceptance_criteria:
- AC-PLATFORM-WORKSPACE-GIT-STATUS-001.7
- AC-PLATFORM-WORKSPACE-GIT-STATUS-001.8
- AC-PLATFORM-WORKSPACE-GIT-STATUS-001.9
system_design:
- ../../specs/platform/system-design/workspace-git-status.md
---
# Task 02: Publish mixed-change facets
## Summary
Extend the agentctl status wire additively and populate independent staged and unstaged metadata for
mixed paths. Preserve legacy fields and the established enrichment limits.
## In scope
- Add the optional facet type and fields to `FileInfo`.
- Parse index and working-tree porcelain columns independently for ordinary supported states.
- Enrich `HEAD -> index`, `index -> worktree`, and flattened compatibility diffs.
- Include facet content in budget, truncation, carry-forward, and skip-reason logic.
## Out of scope
- Frontend facet rendering.
- New behavior for unmerged/conflict states.
- New Git routes.
## Acceptance
- `MM` and `AM` produce one path entry with both accurate facets.
- Pure staged, pure unstaged, and untracked paths retain the legacy compact representation.
- Facet content cannot bypass the 256 KiB representation cap or shared 2 MiB threshold.
## Verification
```bash
cd apps/backend
go test ./internal/agentctl/server/process -run 'TestWorkspaceGitStatusPreservesMixedChangeFacets|TestMixedChangeFacetDiffs|TestMixedChangeFacetBudget|TestCarryForwardMixedChangeFacets'
go test ./internal/agentctl/types/streams ./internal/agentctl/server/process
```
## Files likely touched
- `apps/backend/internal/agentctl/types/streams/git.go`
- `apps/backend/internal/agentctl/server/process/workspace_git_status.go`
- `apps/backend/internal/agentctl/server/process/workspace_git_diff.go`
- `apps/backend/internal/agentctl/server/process/workspace_git_mixed_changes_test.go`
- `apps/backend/internal/agentctl/server/process/workspace_git_diff_test.go`
## Dependencies
Task 01 red regression evidence.
## Risks
- Rename numstat paths and compatibility projections can address different old/new names.
- Carrying prior facet content after an enrichment failure must not overwrite a fresh sibling facet.
## Parallelism
`sequential`
## Inputs
- Requirement acceptance criteria `.7`, `.8`, and `.9`.
- Mixed-change section of the workspace Git status design.
- ADR-2026-08-27-mixed-git-change-facets.
## Results
- Added optional `staged_change` and `unstaged_change` wire facets while preserving the flattened
compatibility fields and compact pure-change representation.
- Parsed supported porcelain index/worktree states independently and enriched mixed paths with
`HEAD -> index` and `index -> worktree` diffs.
- Shared representation accounting now includes both facets; same-HEAD carry-forward preserves each
facet independently without bypassing an exhausted budget.
- `go test ./internal/agentctl/types/streams ./internal/agentctl/server/process` passed.
@@ -0,0 +1,114 @@
---
id: "03-render-layer-specific-changes"
title: "Render layer-specific changes"
status: completed
wave: 3
depends_on:
- "02-publish-mixed-change-facets"
plan: "plan.md"
requirements:
- REQ-PLATFORM-WORKSPACE-GIT-STATUS-001
acceptance_criteria:
- AC-PLATFORM-WORKSPACE-GIT-STATUS-001.10
- AC-PLATFORM-WORKSPACE-GIT-STATUS-001.11
- AC-PLATFORM-WORKSPACE-GIT-STATUS-001.12
system_design:
- ../../specs/platform/system-design/workspace-git-status.md
---
# Task 03: Render layer-specific changes
## Summary
Consume mixed facets as two presentation rows while retaining one raw file identity and one mutation
target. Carry the selected layer through desktop Dockview and the existing mobile diff drawer, then
turn the red browser regressions green.
## In scope
- Mirror and project the optional facet contract in frontend state.
- Derive staged/unstaged sections and action availability from projected facets.
- Keep overall counts, Review aggregation, and mutation dispatch unique by repository/path.
- Include facet data in status equality, editor synchronization, and focus fingerprints.
- Add layer to desktop and mobile diff targets and pinned identities.
- Add focused unit/component tests and satisfy both Playwright regressions.
## Out of scope
- New layout, copy, controls, or localization keys.
- Hunk staging.
- Changing the combined Review source.
## Acceptance
- One mixed raw entry produces accurate Staged and Unstaged rows without doubling the overall file
count or Git mutation.
- Selecting either row renders only its facet and may coexist with the other layer as a pinned diff.
- Desktop and mobile targeted E2E tests pass using the same backend snapshot contract.
## Verification
```bash
cd apps
pnpm --filter @kandev/web test -- hooks/domains/session/git-change-facets.test.ts hooks/domains/session/use-session-git-grouping.test.ts hooks/domains/session/use-session-git-summary.test.ts lib/state/slices/session-runtime/set-git-status-return.test.ts components/task/changes-panel-focus.test.ts components/task/task-changes-panel.test.ts lib/state/dockview-panel-actions.test.ts components/task/mobile/mobile-changes-panel.test.tsx
cd apps/web
pnpm run typecheck
pnpm e2e:run tests/git/git-changes-panel.spec.ts -- --grep "same path in staged and unstaged sections"
pnpm e2e:run --project mobile-chrome tests/task/mobile-changes-panel.spec.ts -- --grep "same path in staged and unstaged sections"
pnpm run lint:e2e-sleeps
```
## Files likely touched
- `apps/web/lib/state/slices/session-runtime/types.ts`
- `apps/web/lib/types/backend.ts`
- `apps/web/hooks/domains/session/git-change-facets.ts`
- `apps/web/hooks/domains/session/git-change-facets.test.ts`
- `apps/web/hooks/domains/session/use-session-git.ts`
- `apps/web/hooks/domains/session/use-session-git-summary.ts`
- `apps/web/lib/state/slices/session-runtime/session-runtime-slice.ts`
- `apps/web/components/task/changes-panel-focus.ts`
- `apps/web/components/task/changes-diff-target.ts`
- `apps/web/components/task/task-changes-panel.tsx`
- `apps/web/components/task/dockview-panel-content.tsx`
- `apps/web/components/task/dockview-shared.tsx`
- `apps/web/lib/state/dockview-panel-actions.ts`
- `apps/web/lib/state/dockview-store.ts`
- `apps/web/components/task/mobile/mobile-changes-panel.tsx`
- `apps/web/components/task/mobile/mobile-diff-sheet.tsx`
- `apps/web/e2e/tests/git/git-changes-panel.spec.ts`
- `apps/web/e2e/tests/task/mobile-changes-panel.spec.ts`
## Dependencies
Task 02 additive wire contract and green backend regression.
## Risks
- Preview and pinned panel IDs must include the layer without breaking legacy file and commit targets.
- Selected-diff compatibility paths can reopen combined-diff behavior if they omit the layer.
## Parallelism
`sequential`
## Inputs
- Requirement acceptance criteria `.10`, `.11`, and `.12`.
- Mixed-change and mobile-parity sections of the workspace Git status design.
- Existing shared Changes body, Dockview preview machinery, and mobile diff drawer.
## Results
- Added shared facet projection and layer-qualified desktop/mobile diff targets while preserving one
aggregate Review file and one repository/path mutation target.
- Included facet updates in state equality, editor synchronization, focus fingerprints, summary
projection, and Dockview identity.
- Coarse-pointer tree rows now expose an always-visible 44px stage action; fine-pointer hover layout
remains unchanged.
- Focused Vitest coverage, frontend typecheck, targeted ESLint, i18n ratchet, and E2E sleep ratchet
passed. The repository-wide `lint:e2e-sleeps` command still reports unrelated baseline violations;
both changed E2E files pass its dedicated ESLint configuration.
- Fresh desktop Chromium and mobile Chrome regressions passed, proving independent row counts and
diffs plus the unstage transition that removes only the staged facet.
@@ -2,7 +2,7 @@
status: active
system: platform
created: 2026-07-19
updated: 2026-08-19
updated: 2026-08-27
owners:
- kandev
---
@@ -26,8 +26,12 @@ Users opening or focusing Changes and Review need a current workspace snapshot w
- **AC-PLATFORM-WORKSPACE-GIT-STATUS-001.4:** Every non-cancelled caller receives the same completed snapshot or error from a shared observation. A caller whose own context is cancelled returns promptly without cancelling or otherwise poisoning the result for other callers.
- **AC-PLATFORM-WORKSPACE-GIT-STATUS-001.5:** Tracker shutdown or the bounded shared-observation deadline cancels the underlying work. Cancelled work does not publish or cache a partial snapshot.
- **AC-PLATFORM-WORKSPACE-GIT-STATUS-001.6:** After Git output is parsed, changed-file and synthetic untracked-diff enrichment performs work proportional to the number of changed entries plus the bounded content processed.
- **AC-PLATFORM-WORKSPACE-GIT-STATUS-001.7:** Existing diff limits remain in force: 10 MiB maximum source file size, 256 KiB maximum emitted diff per file, and a 2 MiB enrichment threshold per status snapshot. Because the threshold is checked before enriching each file, the final accepted file may preserve the existing overshoot of up to the 256 KiB per-file cap. Existing skip reasons remain unchanged.
- **AC-PLATFORM-WORKSPACE-GIT-STATUS-001.7:** Existing diff limits remain in force: 10 MiB maximum source file size, 256 KiB maximum per emitted diff representation, and a 2 MiB enrichment threshold per status snapshot. Flattened compatibility diffs and layer-specific diffs all participate in the same snapshot threshold. Because the threshold is checked before enriching each representation, the final accepted representation may preserve the existing overshoot of up to the 256 KiB cap. Existing skip reasons remain unchanged.
- **AC-PLATFORM-WORKSPACE-GIT-STATUS-001.8:** Large changed sets retain every path and its status metadata. Once the total diff budget is exhausted, files that are not enriched retain `budget_exceeded` as their diff skip reason.
- **AC-PLATFORM-WORKSPACE-GIT-STATUS-001.9:** When one path has both index and working-tree changes, the workspace snapshot preserves the staged and unstaged change facets independently, including each facet's status, line totals, rename origin, diff content, and diff skip reason when applicable.
- **AC-PLATFORM-WORKSPACE-GIT-STATUS-001.10:** Changes lists a mixed path in both Staged and Unstaged, with facet-specific status and line totals. Opening either row shows only that layer's diff. Overall changed-file totals continue to count the repository and path once.
- **AC-PLATFORM-WORKSPACE-GIT-STATUS-001.11:** Staging or unstaging a mixed path operates once on its repository-qualified path and the next snapshot removes the consumed facet while preserving any facet that remains.
- **AC-PLATFORM-WORKSPACE-GIT-STATUS-001.12:** Desktop and mobile Changes surfaces expose the same mixed-path sections, facet-specific diff selection, and staging actions without replacing their established platform-native layouts.
## System design
@@ -4,7 +4,7 @@ system: platform
requirements:
- REQ-PLATFORM-WORKSPACE-GIT-STATUS-001
created: 2026-07-19
updated: 2026-08-19
updated: 2026-08-27
owners:
- kandev
---
@@ -18,7 +18,7 @@ This design preserves the technical source detail for `REQ-PLATFORM-WORKSPACE-GI
| Requirement | Design section |
| --- | --- |
| `REQ-PLATFORM-WORKSPACE-GIT-STATUS-001` | [Migrated source detail](#migrated-source-detail) |
| `REQ-PLATFORM-WORKSPACE-GIT-STATUS-001` | [Migrated source detail](#migrated-source-detail), [Mixed index and working-tree changes](#mixed-index-and-working-tree-changes), [API surface](#api-surface) |
## Migrated source detail
@@ -34,11 +34,52 @@ Users opening or focusing Changes and Review need a current workspace snapshot w
- Every non-cancelled caller receives the same completed snapshot or error from a shared observation. A caller whose own context is cancelled returns promptly without cancelling or otherwise poisoning the result for other callers.
- Tracker shutdown or the bounded shared-observation deadline cancels the underlying work. Cancelled work does not publish or cache a partial snapshot.
- After Git output is parsed, changed-file and synthetic untracked-diff enrichment performs work proportional to the number of changed entries plus the bounded content processed.
- Existing diff limits remain in force: 10 MiB maximum source file size, 256 KiB maximum emitted diff per file, and a 2 MiB enrichment threshold per status snapshot. Because the threshold is checked before enriching each file, the final accepted file may preserve the existing overshoot of up to the 256 KiB per-file cap. Existing skip reasons remain unchanged.
- Existing diff limits remain in force: 10 MiB maximum source file size, 256 KiB maximum per emitted diff representation, and a 2 MiB enrichment threshold per status snapshot. Every flattened or layer-specific representation participates in that threshold. Because the threshold is checked before enriching each representation, the final accepted representation may preserve the existing overshoot of up to the 256 KiB cap. Existing skip reasons remain unchanged.
- Large changed sets retain every path and its status metadata. Once the total diff budget is exhausted, files that are not enriched retain `budget_exceeded` as their diff skip reason.
- Multi-repository responses retain repository identity and partial-success behavior.
- Verification tooling preserves shared managed Go and lint caches for reuse while keeping invocation scratch and command output outside repository worktrees. The root-level `.verify-cache` and `.tmp` paths are ignored as safeguards against legacy or misconfigured verification runs.
### Mixed index and working-tree changes
Git porcelain reports two independent status columns for each path: the index state (`X`) and the
working-tree state (`Y`). A path such as `MM README.md` or `AM new-file.txt` is one file identity with
two change facets. The workspace model MUST preserve both columns instead of selecting one as the
file's only state.
`GitStatusUpdate.Files` remains keyed once by repository-relative path. `FileInfo` retains its
flattened fields as a compatibility projection and adds optional `staged_change` and
`unstaged_change` objects. Each object carries the facet's status, additions, deletions, old path,
diff, and diff skip reason. Agentctl emits the facet objects for a mixed path; a path with only one
layer continues to use the existing flattened representation. Consumers MUST accept both shapes.
For a mixed path, agentctl computes three intentional views:
- the flattened compatibility view compares `HEAD` with the working tree and preserves the existing
worktree-priority `staged=false` classification for older consumers;
- `staged_change` compares `HEAD` with the index using `git diff --cached`; and
- `unstaged_change` compares the index with the working tree using `git diff` without a base ref.
All serialized diff strings, including the compatibility projection, participate in the existing
snapshot-wide enrichment budget. Each representation retains the existing output cap and skip
reasons. Budget exhaustion may omit one representation without discarding either facet's status
metadata.
The frontend keeps the raw file map unique by `(repository_name, path)` for task badges, Review
aggregation, mutation routing, and change-file totals. Changes derives two temporary `FileInfo`
views from a mixed entry, one per facet, and falls back to the flattened fields when facet objects
are absent. Stage, unstage, and discard operations continue to send only the repository-qualified
path, never the temporary view identity.
Diff navigation adds the change layer to its target identity. Desktop preview and pinned diff tabs
use `(repository_name, path, layer)` so the staged and unstaged views of one path cannot alias each
other. The mobile full-height diff drawer carries the same layer while retaining its existing sheet,
touch-target, and scroll behavior. Review's all-files source remains a single combined uncommitted
file; only a layer-qualified Changes selection projects a facet-specific diff.
Status equality, editor synchronization signatures, and Changes focus fingerprints include the
optional facet fields. A snapshot that changes only one facet must therefore publish and render.
This contract follows [ADR-2026-08-27-mixed-git-change-facets](../../../decisions/2026-08-27-mixed-git-change-facets.md).
### Base-commit staleness and refresh
The commits panel (`git log <base>..HEAD`) and cumulative diff anchor to a base commit derived from the session's stored `base_commit_sha` and `base_branch`. That anchor becomes stale when the branch history moves relative to the true integration branch after the base was recorded — most commonly a stacked-PR parent that merges and disappears, a rebase onto the integration branch, or a base branch that was deleted upstream. When the anchor is stale, the panel enumerates commits that are not part of the branch's own contribution, inflating the count.
@@ -73,6 +114,7 @@ Existing Git-status routes remain in place. Their result and stream payloads add
- `GET /api/v1/git/status/multi?fresh=<bool>` returns the existing `MultiRepoGitStatusResult` shape containing `PerRepoGitStatus` entries.
- The `fresh` query parameter continues to select a live observation rather than a cached tracker snapshot.
- A repository status MAY include `comparison_target` with its credential-free display identity and `comparison_error_code` when the explicit target is unavailable.
- A mixed-path `FileInfo` MAY include `staged_change` and `unstaged_change`. Each facet uses the same bounded status, line-total, rename, diff, and skip-reason vocabulary as the flattened file fields. Their absence preserves the legacy single-layer shape.
- Commit and cumulative-diff requests use agentctl's configured repository-qualified ref when present. A caller-supplied branch name cannot override it.
- The internal agentctl control API adds a per-repository comparison-target update alongside the existing base-branch update. It validates identities and refs, materializes the exact ref, replaces tracker state, and triggers a refresh.
- The bounded task Git summary adds `comparison_unavailable`; when true, additions/deletions are not rendered as authoritative task-card statistics.
@@ -83,6 +125,8 @@ Existing Git-status routes remain in place. Their result and stream payloads add
|---|---|
| Primary branch or porcelain observation fails | The live observation fails and the prior cached snapshot remains available. |
| Secondary diff enrichment fails | The established same-HEAD carry-forward behavior is preserved. |
| A path has both index and working-tree changes | One raw file entry carries both facets. Changes renders one row in Staged and one in Unstaged, while overall file totals count the path once. |
| A mixed path's layer diff exceeds its cap or the snapshot budget | The affected facet retains status metadata and reports the existing `truncated` or `budget_exceeded` skip reason; the other facet remains independently usable. |
| One caller cancels while a shared observation is running | That caller returns its context cancellation promptly; other callers remain eligible to receive the shared result. |
| The tracker stops or the shared deadline expires | Underlying work is cancelled and no partial result is published or cached. |
| One repository fails during a multi-repository request | Successful repository entries remain available and the failure is reported on its repository entry. |
@@ -104,6 +148,9 @@ Existing Git-status routes remain in place. Their result and stream payloads add
- **GIVEN** one waiter cancels during a shared observation, **WHEN** other waiters remain, **THEN** the cancelled waiter returns promptly and the remaining waiters receive the completed result.
- **GIVEN** tracker shutdown or the shared-observation deadline while enrichment is running, **WHEN** cancellation reaches the observation, **THEN** filesystem iteration stops and no partial snapshot is cached.
- **GIVEN** approximately 15,000 untracked text files, **WHEN** fresh status is computed, **THEN** every path is present, emitted diff content obeys the existing limits, files not enriched after total-budget exhaustion have `budget_exceeded`, and post-porcelain enrichment remains linear in the number of entries.
- **GIVEN** a tracked file with one staged edit and a different unstaged edit, **WHEN** fresh status is computed, **THEN** its one path entry contains staged and unstaged facets with independent line totals and `HEAD -> index` and `index -> working tree` diffs.
- **GIVEN** a newly added staged file that receives another unstaged edit, **WHEN** Changes opens on desktop or mobile, **THEN** the same path appears in both Staged and Unstaged, selecting each row shows only that layer, and the overall changed-file count remains one.
- **GIVEN** a mixed path visible in both sections, **WHEN** the user stages or unstages it, **THEN** one repository-qualified Git mutation runs and the next snapshot shows only the facet that remains.
- **GIVEN** one invalid repository in a multi-repository request, **WHEN** other repositories succeed, **THEN** the response retains the successful entries and reports the failure only on the invalid repository.
- **GIVEN** verification needs writable scratch space, **WHEN** it selects a location, **THEN** the location is outside every Git worktree and existing shared caches remain reusable; if a legacy run creates root-level `.verify-cache` or `.tmp`, Git status ignores it.
- **GIVEN** a session whose stored `base_commit_sha` is a strict ancestor of `merge-base(HEAD, <resolved integration candidate>)` (for example a stacked-PR parent branch that has since merged into the integration branch and lost its upstream ref), **WHEN** the commits panel is requested, **THEN** the enumerated commit count matches `git rev-list --first-parent --count $(git merge-base HEAD <resolved integration candidate>)..HEAD` and excludes the commits that already landed on the integration branch.
@@ -131,7 +178,10 @@ Existing Git-status routes remain in place. Their result and stream payloads add
- Granting a new Git credential scope for a private comparison repository.
- Periodically fetching a moving target branch on every status poll. Targets are refreshed on association, retarget, launch/resume, and explicit comparison refresh.
- Automatically changing the checkout, push remote, upstream, or `origin` because a comparison target changes.
- Redesigning the desktop Changes panel or compressing it into the mobile layout.
- Adding hunk-level staging or changing the existing whole-file stage, unstage, and discard semantics.
- Defining new behavior for Git's unmerged/conflict porcelain states; those continue to follow their existing handling.
## Implementation plan
See [Workspace Git Status Scalability plan](../../../plans/workspace-git-status-scalability/plan.md) and [Fork PR Comparison Targets plan](../../../plans/fork-pr-comparison-targets/plan.md).
See [Workspace Git Status Scalability plan](../../../plans/workspace-git-status-scalability/plan.md), [Fork PR Comparison Targets plan](../../../plans/fork-pr-comparison-targets/plan.md), and [Mixed Staged and Unstaged Changes plan](../../../plans/mixed-staged-unstaged-changes/plan.md).