pi-usereq 0.10.0 → 0.11.0

package/pi-usereq/docs/REQUIREMENTS.md

@@ -62,7 +62,7 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **CTN-010**: MUST execute offline harness flows without requiring pi.dev services or `docs/pi.dev/agent-document-manifest.json`.
 - **CTN-011**: MUST store bundled prompt, instruction, template, and guideline resources under `src/resources/{prompts,instructions,templates,guidelines}` and install them under `<installation-path>/resources/{prompts,instructions,templates,guidelines}`.
 - **CTN-012**: MUST NOT persist derived `base-path`, `git-path`, `parent-path`, `base-dir`, `context-path`, `worktree-dir`, or `worktree-path` in `.pi-usereq.json`.
-- **CTN-013**: MUST default `DEBUG_ENABLED=disable`, `DEBUG_LOG_FILE=debug.json`, `DEBUG_STATUS_CHANGES=disable`, `DEBUG_WORKFLOW_EVENTS=disable`, `DEBUG_LOG_ON_STATUS=running`, `DEBUG_ENABLED_TOOLS=[]`, and `DEBUG_ENABLED_PROMPTS=[]` in persisted project configuration.
+- **CTN-013**: MUST default `DEBUG_ENABLED=disable`, `DEBUG_LOG_FILE=/tmp/PI-useReq.json`, `DEBUG_STATUS_CHANGES=disable`, `DEBUG_WORKFLOW_EVENTS=disable`, `DEBUG_LOG_ON_STATUS=running`, `DEBUG_ENABLED_TOOLS=[]`, and `DEBUG_ENABLED_PROMPTS=[]` in persisted project configuration.
 - **CTN-014**: MUST serialize every configured or derived path without a trailing `/`.
 - **CTN-015**: MUST reserve `*-path` names for absolute paths and `*-dir` names for relative paths.
 - **CTN-016**: MUST NOT modify any path under `docs/` during analysis, implementation, verification, or bug fixing.
@@ -115,7 +115,7 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **REQ-065**: MUST make `scripts/pi-usereq-debug.sh tool` accept `--args <text>` by forwarding a JSON object through `--params`, while preserving direct `--params <json>` passthrough.
 - **REQ-006**: MUST provide a `pi-usereq` menu that edits project directories, git automation, static-check settings, tools, notifications, and debug settings, exposes `Show configuration`, confirms reset actions, saves every change immediately, and never renders `Save and close`.
 - **REQ-236**: MUST persist `DEBUG_ENABLED` with allowed values `enable` and `disable`, defaulting to `disable`.
-- **REQ-237**: MUST persist `DEBUG_LOG_FILE` as a non-empty string defaulting to `debug.json`, and resolve relative paths against the original project base when writing logs.
+- **REQ-237**: MUST persist `DEBUG_LOG_FILE` as a non-empty string defaulting to `/tmp/PI-useReq.json`, and resolve relative paths against the original project base when writing logs.
 - **REQ-238**: MUST persist `DEBUG_LOG_ON_STATUS` with allowed values `any`, `idle`, `checking`, `running`, `merging`, and `error`, defaulting to `running`.
 - **REQ-239**: MUST persist enabled debug-tool names and enabled debug-prompt names as normalized arrays defaulting to empty.
 - **REQ-254**: MUST persist `DEBUG_STATUS_CHANGES` with allowed values `enable` and `disable`, defaulting to `disable`.
@@ -152,9 +152,9 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **REQ-251**: MUST default `static-check.Python`, `JavaScript`, and `TypeScript` to `enabled=enable` with their documented Command checker entries.
 - **REQ-252**: MUST default every other supported `static-check.<language>` entry to `enabled=disable` with `checkers=[]`.
 - **REQ-009**: MUST refresh shared runtime path context, apply configured startup tools, reset workflow state to `idle` for `session_start` reasons `startup|new|reload`, and publish single-line `pi-usereq` status text.
-- **REQ-109**: MUST make the single-line status bar render the explicit runtime `current-path` value from `context-path` and omit `base`, `docs`, `src`, and `tests` path fields.
+- **REQ-109**: MUST omit `current-path`, `base`, `docs`, `src`, and `tests` path fields from the single-line status bar.
 - **REQ-111**: MUST omit prompt-delivery mode fields from the single-line status bar.
-- **REQ-112**: MUST render status-bar field names with the active theme `accent` token and non-error field values with the active theme `warning` token.
+- **REQ-112**: MUST render status-bar field names with the active theme `accent` token and non-error field values with the active theme `warning` token unless a field-specific requirement overrides the value token.
 - **REQ-113**: MUST register shared event wrappers for `resources_discover`, `session_start`, `session_before_switch`, `session_before_fork`, `session_before_compact`, `session_compact`, and `session_shutdown`.
 - **REQ-114**: MUST register shared event wrappers for `session_before_tree`, `session_tree`, `context`, `before_provider_request`, `before_agent_start`, `agent_start`, and `agent_end`.
 - **REQ-115**: MUST register shared event wrappers for `turn_start`, `turn_end`, `message_start`, `message_update`, `message_end`, `tool_execution_start`, and `tool_execution_update`.
@@ -162,16 +162,18 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **REQ-117**: MUST route every intercepted hook through `updateExtensionStatus` with the originating hook name and event payload, even when no hook-specific side effect exists.
 - **REQ-118**: MUST obtain latest context-usage facts from `ctx.getContextUsage()` or an equivalent runtime API and store them in extension session state.
 - **REQ-119**: MUST refresh stored context-usage facts during `session_start` and after intercepted events before rebuilding the status bar when newer data is available.
-- **REQ-120**: MUST render single-line status fields in this order: `status`, `current-path`, `context`, `elapsed`, `sound`.
-- **REQ-121**: MUST render `context` immediately after `current-path` with separator ` • ` and one fixed-width gauge icon.
-- **REQ-122**: MUST map `context` usage to `▕_▏`, `▕▂▏`, `▕▄▏`, `▕▆▏`, and `▕█▏` for `0`, `>0-25`, `>25-50`, `>50-90`, and `>90-100` percent bands.
+- **REQ-120**: MUST render single-line status fields in this order: `status`, `branch`, `context`, `elapsed`, `sound`.
+- **REQ-121**: MUST render `branch` immediately after `status` with separator ` • ` and the active git branch name.
+- **REQ-283**: MUST resolve `branch` from the current `context-path` git HEAD during every status-bar rebuild so worktree switches and base-path restoration update immediately.
+- **REQ-284**: MUST render `context` immediately after `branch` with separator ` • ` and one fixed-width gauge icon.
+- **REQ-122**: MUST map `context` usage to `▕_▏`, `▕▂▏`, `▕▄▏`, `▕▆▏`, and `▕█▏` for `0`, `>0-<25`, `>=25-<50`, `>=50-<75`, and `>=75` percent bands.
 - **REQ-123**: MUST render `elapsed` immediately after `context` as `⏱︎ <active> ⚑ <last> ⌛︎<total>`.
 - **REQ-124**: MUST render `⏱︎ --:--` when no prompt is active, and `⚑ --:--` plus `⌛︎--:--` until the corresponding timers receive a normally completed prompt duration.
 - **REQ-125**: MUST render timed `elapsed` segments as `M:SS`, keep minutes unbounded above 59, zero-pad seconds to two digits, and preserve `⚑` plus `⌛︎` when escape-triggered cancellation ends the active run.
-- **REQ-126**: MUST render `context` gauge icons with theme `warning`, except the overflow state uses theme `error`.
-- **REQ-127**: MUST render `context` as blinking theme `warning` `▕█▏` when normalized usage is `>90-100` percent and terminal blink control is supported.
-- **REQ-233**: MUST render `context` as blinking theme `error` `▕█▏` when normalized usage exceeds 100 percent and terminal blink control is supported.
-- **REQ-128**: MUST render `context` as theme `error` `▕█▏` when normalized usage exceeds 100 percent and terminal blink control is unavailable.
+- **REQ-126**: MUST render `context` gauge icons in default terminal color below 90 percent and theme `error` at 90 percent or above.
+- **REQ-127**: MUST render `context` as non-blinking theme `error` `▕█▏` when normalized usage is `>=90-<100` percent.
+- **REQ-233**: MUST render `context` as blinking theme `error` `▕█▏` when normalized usage is `>=100` percent and terminal blink control is supported.
+- **REQ-128**: MUST render `context` as theme `error` `▕█▏` when normalized usage is `>=100` percent and terminal blink control is unavailable.
 - **REQ-131**: MUST persist a sound level with allowed values `none`, `low`, `mid`, and `high`, defaulting to `none`.
 - **REQ-132**: MUST execute the configured sound command when the corresponding prompt-end sound event toggle is enabled and the sound level is not `none`.
 - **REQ-133**: MUST persist configurable shell-command strings for sound levels `low`, `mid`, and `high`, and MUST substitute `%%INSTALLATION_PATH%%` with the runtime extension installation path before execution.
@@ -203,7 +205,7 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **REQ-190**: MUST label top-level rows as `Document directory`, `Source-code directories`, `Unit tests directory`, `Auto git commit`, `Git worktree`, `Worktree prefix`, `Language static code checkers`, `Enable tools`, `Notifications`, `Debug`, and `Show configuration`.
 - **REQ-191**: MUST order top-level rows as `Document directory`, `Source-code directories`, `Unit tests directory`, `Auto git commit`, `Git worktree`, `Worktree prefix`, `Language static code checkers`, `Enable tools`, `Notifications`, `Debug`, `Show configuration`, and `Reset defaults`.
 - **REQ-192**: MUST preserve the selected settings-menu row after toggling or editing a setting value.
-- **REQ-193**: MUST append `Reset defaults` as the final row of every configuration menu and descendant selector menu, and MUST NOT render `Save and close`.
+- **REQ-193**: MUST append `Reset defaults` as a final row without right-aligned value text in every configuration menu and descendant selector menu, and MUST NOT render `Save and close`.
 - **REQ-194**: MUST make top-level `Reset defaults` show changed values with previous and next values, require explicit confirmation, restore full-tree defaults, and save immediately.
 - **REQ-195**: MUST make non-top-level `Reset defaults` show changed values with previous and next values, require explicit confirmation, restore subtree defaults, and save immediately.
 - **REQ-196**: MUST persist a global command-notify enable flag defaulting to disabled.
@@ -222,10 +224,10 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **REQ-206**: MUST derive `worktree-dir` as `<prefix><project>-<sanitized-branch>-<YYYYMMDDHHMMSS>` and `worktree-path` as `<parent-path>/<worktree-dir>/<base-dir>` when worktrees are enabled.
 - **REQ-271**: MUST create one dedicated worktree under `parent-path`, fork the current active session into an execution session file whose header cwd equals `worktree-path`, and switch the active pi CLI session to that file before agent start.
 - **REQ-207**: MUST keep `context-path`, `ctx.cwd`, and `process.cwd()` at `base-path` when worktree creation is disabled.
-- **REQ-208**: MUST restore the original session-backed `base-path`, fast-forward-only merge from `base-path`, and delete the worktree plus branch after successful orchestrated session closure.
+- **REQ-208**: MUST restore the original session-backed `base-path`, fast-forward-only merge from `base-path`, delete the worktree plus branch, and preserve the successful worktree execution transcript in the client-visible session after closure.
 - **REQ-209**: MUST restore the original session-backed `base-path`, notify the pi CLI of closure failure, and retain the worktree plus branch when orchestrated session closure is interrupted, failed, aborted, or incomplete.
 - **REQ-221**: MUST maintain one prompt-orchestration state machine with states `idle`, `checking`, `running`, `merging`, and `error`.
-- **REQ-222**: MUST render `status` immediately before `base` as the current prompt-orchestration state and refresh it on every internal or pi CLI state transition.
+- **REQ-222**: MUST render `status` as the first single-line status field and refresh it on every internal or pi CLI state transition.
 - **REQ-223**: MUST render `status:error` with theme `error` plus terminal blink when supported, and other `status` values with the existing non-error status-bar convention.
 - **REQ-224**: MUST reject a `req-<prompt>` command before any operation when workflow state is not `idle`, surfacing the error to pi CLI.
 - **REQ-225**: MUST transition workflow state to `checking` after the `idle` gate and keep it there through required-doc checks, worktree generation, worktree verification, and prompt handoff preparation.
@@ -332,7 +334,6 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **REQ-144**: MUST default `PI_NOTIFY_SOUND_HIGH_CMD` to `paplay --volume=65535 %%INSTALLATION_PATH%%/resources/sounds/Soft-high-tech-notification-sound-effect.mp3`.
 - **REQ-145**: MUST derive static `git-path` during bootstrap from `base-path` and repository ancestry rules, ignoring project-configuration JSON values.
 - **REQ-146**: MUST NOT read or persist `base-path` or `git-path` in project-configuration JSON.
-- **REQ-148**: MUST render status-bar `current-path` as dynamic `context-path`, home-relative with `~` when applicable.
 - **REQ-149**: MUST label notification settings actions as `Notify command`, `Enable sound`, `Sound toggle hotkey bind`, `Sound command (low|mid|high vol.)`, `Pushover User Key/Delivery Group Key`, and `Pushover Token/API Token Key`.
 - **REQ-150**: MUST omit overview rows and reference-only actions from the main, notification, startup-tool, and static-check configuration menus.
 - **REQ-151**: MUST render `pi-usereq`, notification, static-check, and startup-tool menus with left-aligned labels and right-aligned current values using the active CLI settings-list theme semantics.
@@ -354,23 +355,25 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **TST-078**: MUST verify default configuration persists documented per-language `enabled` flags and checker lists for `C`, `C++`, `Python`, `JavaScript`, and `TypeScript`.
 - **TST-079**: MUST verify `files-static-check` and `static-check` execute zero checkers and expose empty configured-checker lists when the target language `enabled=disable`.
 - **TST-006**: MUST verify `session_start` activates configured startup tools, resets workflow state to `idle` for `startup|new|reload`, and updates the single-line `pi-usereq` status bar.
-- **TST-031**: MUST verify the status bar renders `status` before the home-relative `current-path`, omits `base`, `docs`, `src`, `tests`, `git`, and `tools`, and preserves documented field-value theme separation.
+- **TST-031**: MUST verify the status bar renders `status` before `branch`, omits `current-path`, `base`, `docs`, `src`, `tests`, `git`, and `tools`, and preserves documented field-value theme separation.
 - **TST-032**: MUST verify extension registration installs wrappers for all documented lifecycle hooks and routes replayed hook payloads through `updateExtensionStatus`.
-- **TST-033**: MUST verify the status bar renders ordered `status`, `current-path`, `context`, `elapsed`, and `sound` fields plus the documented icon-based `context` gauge thresholds.
+- **TST-033**: MUST verify the status bar renders ordered `status`, `branch`, `context`, `elapsed`, and `sound` fields plus the documented icon-based `context` gauge thresholds.
 - **TST-037**: MUST verify the `Notifications` menu persists notification and sound settings through `Notification events` and `Sound events` submenus using the documented labels, order, reset-confirmation flows, immediate-save behavior, and no `Save and close` rows.
 - **TST-038**: MUST verify the sound-toggle shortcut cycles persisted sound levels and refreshes the status bar with the updated `sound` field.
 - **TST-047**: MUST verify the `Notifications` menu exposes `Pushover events` before direct Pushover settings, keeps `Enable pushover` dimmed and locked until both credential fields are non-empty, and persists Pushover event and credential values.
 - **TST-072**: MUST verify `Pushover text` displays escaped control sequences in menus and decodes the documented escape sequences from input before persistence.
 - **TST-048**: MUST verify native Pushover requests honor global enable, completed/interrupted/failed Pushover toggles, credentials, priority, title, and text placeholder substitution including `%%RESULT%%` for enabled prompt-end outcomes.
-- **TST-049**: MUST verify the status bar renders ordered `status`, `current-path`, `context`, `elapsed`, and `sound` fields and appends `sound:<level>`.
+- **TST-049**: MUST verify the status bar renders ordered `status`, `branch`, `context`, `elapsed`, and `sound` fields and appends `sound:<level>`.
 - **TST-050**: MUST verify `PI_NOTIFY_CMD` placeholder substitution including `%%RESULT%%` and routing honor global notify enable plus completed/interrupted/failed notify toggles.
 - **TST-034**: MUST verify `ctx.getContextUsage()` snapshots refresh status updates and `elapsed` preserves `⚑` plus `⌛︎` across escape-triggered cancellation.
 - **TST-062**: MUST verify `Show configuration` saves pending config, closes the active configuration menu tree, and writes the persisted `.pi-usereq.json` file text into the editor.
 - **TST-063**: MUST verify `⚑` plus `⌛︎` survive `session_start` reason `new` and reset on `session_start` reason `reload`.
-- **TST-045**: MUST verify default configuration enables auto git commit, disables debug, notify, and Pushover globally, initializes sound to `none`, applies the documented debug and notification defaults, and persists the documented notify and Pushover templates.
+- **TST-045**: MUST verify default configuration enables auto git commit, disables debug, notify, and Pushover globally, initializes sound to `none`, sets `DEBUG_LOG_FILE=/tmp/PI-useReq.json`, and persists the documented notify and Pushover templates.
 - **TST-051**: MUST verify sound routing honors the selected sound state and completed/interrupted/failed sound toggles.
-- **TST-035**: MUST verify unavailable or 0-percent context usage renders `▕_▏` with the theme `warning` token.
-- **TST-036**: MUST verify context usage `>90-100` renders blinking warning `▕█▏`, and `>100` renders blinking error `▕█▏` or non-blinking error `▕█▏` when blink control is unavailable.
+- **TST-035**: MUST verify unavailable or 0-percent context usage renders `▕_▏` with default terminal color.
+- **TST-096**: MUST verify context usage `>0-<25`, `>=25-<50`, `>=50-<75`, and `>=75-<90` render `▕▂▏`, `▕▄▏`, `▕▆▏`, and `▕█▏` in default terminal color.
+- **TST-036**: MUST verify context usage `>=90-<100` renders non-blinking error `▕█▏`, and `>=100` renders blinking error `▕█▏` or non-blinking error `▕█▏` when blink control is unavailable.
+- **TST-095**: MUST verify status-bar `branch` resolves from current `context-path` git HEAD and refreshes across worktree switches plus base-path restoration.
 - **TST-043**: MUST verify configuration menus reuse the active CLI settings-list theme semantics for labels, values, descriptions, cursor, and hints.
 - **TST-009**: MUST verify `package.json` declares ESM packaging, the single pi extension entry, and the standard `test`, `test:watch`, and `cli` scripts.
 - **TST-010**: MUST verify `tsconfig.json` declares `NodeNext`, `strict`, `noEmit`, and includes both `src/**/*.ts` and `tests/**/*.ts`.
@@ -400,7 +403,7 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **TST-042**: MUST verify `package.json` keeps `name` equal to `pi-usereq` so npm publication resolves to `https://www.npmjs.com/package/pi-usereq`.
 - **TST-044**: MUST verify `package.json` keeps npm provenance metadata aligned to the canonical GitHub repository, issues URL, and README homepage.
 - **TST-040**: MUST verify `.pi-usereq.json` omits derived static and dynamic path fields while runtime path context and status rendering still derive them correctly.
-- **TST-041**: MUST verify the `pi-usereq` menu uses the documented labels and order, every configuration menu ends with `Reset defaults` only, dims locked git or debug rows, and preserves the documented summary rows.
+- **TST-041**: MUST verify the `pi-usereq` menu uses the documented labels and order, every configuration menu ends with `Reset defaults` without right-aligned value text, dims locked git or debug rows, and preserves the documented summary rows.
 - **TST-073**: MUST verify the `Debug` submenu persists `DEBUG_ENABLED`, `DEBUG_STATUS_CHANGES`, `DEBUG_WORKFLOW_EVENTS`, `DEBUG_LOG_FILE`, `DEBUG_LOG_ON_STATUS`, and per-item debug toggles through immediate-save, reset-confirmation, and focus-preserving re-render flows.
 - **TST-074**: MUST verify selected custom and embedded tool debug toggles append JSON entries with tool name, workflow state, input, result, and error flag, honoring `DEBUG_ENABLED` plus `DEBUG_LOG_ON_STATUS`.
 - **TST-075**: MUST verify selected `req-*` debug toggles append JSON entries for required-doc checks, worktree creation, fast-forward merge, worktree deletion, `workflow_state`, and `DEBUG_WORKFLOW_EVENTS`-gated workflow events across successful and failing prompt runs.

package/pi-usereq/docs/WORKFLOW.md

@@ -473,9 +473,14 @@
             - `shouldResetWorkflowStateOnSessionStart(...)`: detect `startup|new|reload` workflow-reset boundaries [`src/core/extension-status.ts`]
             - `persistElapsedState(...)`: mirror completed timers into process-scoped persistence [`src/core/extension-status.ts`]
             - `syncPiUsereqStatusTicker(...)`: start or stop the live elapsed ticker [`src/core/extension-status.ts`]
-            - `renderPiUsereqStatus(...)`: render the status/current-path/context/elapsed/sound footer with CLI-theme token overlays [`src/core/extension-status.ts`]
+            - `renderPiUsereqStatus(...)`: render the status/branch/context/elapsed/sound footer with CLI-theme token overlays [`src/core/extension-status.ts`]
               - `createStatusThemeAdapter(...)`: constrain status rendering to CLI-supported `accent`, `warning`, `dim`, and `error` theme tokens [`src/core/extension-status.ts`]
-              - `buildPiUsereqStatusText(...)`: compose the single-line footer payload with workflow state, current-path, elapsed semantics, and sound status fields [`src/core/extension-status.ts`]
+              - `resolveStatusBranchValue(...)`: resolve the active git branch from the current context cwd before footer rendering [`src/core/extension-status.ts`]
+                - `resolveRuntimeGitBranchName(...)`: resolve the active git branch for the current execution path [`src/core/runtime-project-paths.ts`]
+                  - `resolveRuntimeGitPath(...)`: resolve the runtime git root for the active execution path [`src/core/runtime-project-paths.ts`]
+                    - `isInsideGitRepo(...)`: test git work-tree membership [`src/core/runtime-project-paths.ts`]
+                    - `resolveGitRoot(...)`: resolve repository root [`src/core/runtime-project-paths.ts`]
+              - `buildPiUsereqStatusText(...)`: compose the single-line footer payload with workflow state, branch, context gauge, elapsed semantics, and sound status fields [`src/core/extension-status.ts`]
                 - `formatStatusField(...)`: render one colored text field [`src/core/extension-status.ts`]
                 - `formatRenderedStatusField(...)`: render one pre-styled field [`src/core/extension-status.ts`]
                 - `formatWorkflowStateValue(...)`: render the workflow-state value with error highlighting when required [`src/core/extension-status.ts`]
@@ -528,9 +533,14 @@
             - `buildSettingItems(...)`: map menu choices into settings-list rows, apply optional dim tones, and disable non-selectable actions [`src/core/settings-menu.ts`]
           - `saveProjectConfig(...)`: persist menu updates on save-and-close [`src/index.ts`]
           - `setPiUsereqStatusConfig(...)`: cache the saved config for footer rendering [`src/core/extension-status.ts`]
-          - `renderPiUsereqStatus(...)`: render the current-path/context/elapsed/sound footer after save-and-close with CLI-theme token overlays [`src/core/extension-status.ts`]
+          - `renderPiUsereqStatus(...)`: render the status/branch/context/elapsed/sound footer after save-and-close with CLI-theme token overlays [`src/core/extension-status.ts`]
             - `createStatusThemeAdapter(...)`: constrain status rendering to CLI-supported `accent`, `warning`, `dim`, and `error` theme tokens [`src/core/extension-status.ts`]
-            - `buildPiUsereqStatusText(...)`: compose the single-line footer payload with current-path, consolidated elapsed semantics, and sound status fields [`src/core/extension-status.ts`]
+            - `resolveStatusBranchValue(...)`: resolve the active git branch from the current context cwd before footer rendering [`src/core/extension-status.ts`]
+              - `resolveRuntimeGitBranchName(...)`: resolve the active git branch for the current execution path [`src/core/runtime-project-paths.ts`]
+                - `resolveRuntimeGitPath(...)`: resolve the runtime git root for the active execution path [`src/core/runtime-project-paths.ts`]
+                  - `isInsideGitRepo(...)`: test git work-tree membership [`src/core/runtime-project-paths.ts`]
+                  - `resolveGitRoot(...)`: resolve repository root [`src/core/runtime-project-paths.ts`]
+            - `buildPiUsereqStatusText(...)`: compose the single-line footer payload with workflow state, branch, context gauge, consolidated elapsed semantics, and sound status fields [`src/core/extension-status.ts`]
               - `formatStatusField(...)`: render one colored text field [`src/core/extension-status.ts`]
               - `formatRenderedStatusField(...)`: render one pre-styled field [`src/core/extension-status.ts`]
               - `formatContextUsageBar(...)`: render the icon-based context gauge [`src/core/extension-status.ts`]
@@ -544,7 +554,7 @@
               - `buildPiNotifyEventLauncherChoice(...)`: serialize one event-submenu launcher row with a compact enabled-toggle summary [`src/index.ts`]
               - `buildPiNotifyPushoverRows(...)`: serialize direct Pushover rows plus the shared event-submenu launcher [`src/index.ts`]
             - `configurePiNotifyEventMenu(...)`: interactive completed/interrupted/failed event editor for one notification transport [`src/index.ts`]
-              - `buildPiNotifyEventMenuChoices(...)`: serialize shared event rows plus submenu reset/save actions [`src/index.ts`]
+              - `buildPiNotifyEventMenuChoices(...)`: serialize shared event rows plus the submenu reset action [`src/index.ts`]
               - `resetPiNotifyEventMenuToDefaults(...)`: restore default event toggles for one notification transport [`src/index.ts`]
               - `resolvePiNotifyEventLabel(...)`: map one event-toggle key to the human-readable menu label [`src/index.ts`]
               - `togglePiNotifyFlag(...)`: toggle one persisted boolean notification setting [`src/index.ts`]
@@ -627,9 +637,14 @@
       - `transitionPromptWorkflowState(...)`: update workflow state and append gated `workflow_state` debug entries only after the transition completes [`src/index.ts`]
         - `setPiUsereqWorkflowState(...)`: update workflow state before prompt preflight, prompt handoff, or command-side failure [`src/core/extension-status.ts`]
         - `logPromptWorkflowStateChange(...)`: append selected prompt workflow-transition debug entries [`src/index.ts`]
-        - `renderPiUsereqStatus(...)`: render the status/current-path/context/elapsed/sound footer with CLI-theme token overlays [`src/core/extension-status.ts`]
+        - `renderPiUsereqStatus(...)`: render the status/branch/context/elapsed/sound footer with CLI-theme token overlays [`src/core/extension-status.ts`]
           - `createStatusThemeAdapter(...)`: constrain status rendering to CLI-supported `accent`, `warning`, `dim`, and `error` theme tokens [`src/core/extension-status.ts`]
-          - `buildPiUsereqStatusText(...)`: compose the single-line footer payload with workflow state, current-path, elapsed semantics, and sound status fields [`src/core/extension-status.ts`]
+          - `resolveStatusBranchValue(...)`: resolve the active git branch from the current context cwd before footer rendering [`src/core/extension-status.ts`]
+            - `resolveRuntimeGitBranchName(...)`: resolve the active git branch for the current execution path [`src/core/runtime-project-paths.ts`]
+              - `resolveRuntimeGitPath(...)`: resolve the runtime git root for the active execution path [`src/core/runtime-project-paths.ts`]
+                - `isInsideGitRepo(...)`: test git work-tree membership [`src/core/runtime-project-paths.ts`]
+                - `resolveGitRoot(...)`: resolve repository root [`src/core/runtime-project-paths.ts`]
+          - `buildPiUsereqStatusText(...)`: compose the single-line footer payload with workflow state, branch, context gauge, elapsed semantics, and sound status fields [`src/core/extension-status.ts`]
             - `formatStatusField(...)`: render one colored text field [`src/core/extension-status.ts`]
             - `formatRenderedStatusField(...)`: render one pre-styled field [`src/core/extension-status.ts`]
             - `formatWorkflowStateValue(...)`: render the workflow-state value with error highlighting when required [`src/core/extension-status.ts`]
@@ -815,9 +830,14 @@
           - `persistPromptCommandState(...)`: mirror workflow state plus pending or active prompt execution plans into process-scoped persistence [`src/core/extension-status.ts`]
             - `writePersistedPromptCommandRuntimeState(...)`: store workflow state plus pending or active prompt execution plans on `globalThis` [`src/core/prompt-command-state.ts`]
           - `syncPiUsereqStatusTicker(...)`: start or stop the live elapsed ticker [`src/core/extension-status.ts`]
-          - `renderPiUsereqStatus(...)`: render the status/current-path/context/elapsed/sound footer with CLI-theme token overlays [`src/core/extension-status.ts`]
+          - `renderPiUsereqStatus(...)`: render the status/branch/context/elapsed/sound footer with CLI-theme token overlays [`src/core/extension-status.ts`]
             - `createStatusThemeAdapter(...)`: constrain status rendering to CLI-supported `accent`, `warning`, `dim`, and `error` theme tokens [`src/core/extension-status.ts`]
-            - `buildPiUsereqStatusText(...)`: compose the single-line footer payload with workflow state, current-path, elapsed semantics, and sound status fields [`src/core/extension-status.ts`]
+            - `resolveStatusBranchValue(...)`: resolve the active git branch from the current context cwd before footer rendering [`src/core/extension-status.ts`]
+              - `resolveRuntimeGitBranchName(...)`: resolve the active git branch for the current execution path [`src/core/runtime-project-paths.ts`]
+                - `resolveRuntimeGitPath(...)`: resolve the runtime git root for the active execution path [`src/core/runtime-project-paths.ts`]
+                  - `isInsideGitRepo(...)`: test git work-tree membership [`src/core/runtime-project-paths.ts`]
+                  - `resolveGitRoot(...)`: resolve repository root [`src/core/runtime-project-paths.ts`]
+            - `buildPiUsereqStatusText(...)`: compose the single-line footer payload with workflow state, branch, context gauge, elapsed semantics, and sound status fields [`src/core/extension-status.ts`]
               - `formatStatusField(...)`: render one colored text field [`src/core/extension-status.ts`]
               - `formatRenderedStatusField(...)`: render one pre-styled field [`src/core/extension-status.ts`]
               - `formatWorkflowStateValue(...)`: render the workflow-state value with error highlighting when required [`src/core/extension-status.ts`]
@@ -870,10 +890,14 @@
         - `logPromptWorkflowEvent(...)`: append selected workflow-closure and workflow-session-shutdown debug entries [`src/index.ts`]
         - `transitionPromptWorkflowState(...)`: transition workflow state for matched-success merge handling and final idle restoration, and append gated workflow-state debug entries immediately after each transition [`src/index.ts`]
           - `setPiUsereqWorkflowState(...)`: transition workflow state for matched-success merge handling and final idle restoration [`src/core/extension-status.ts`]
-            - `renderPiUsereqStatus(...)`: render the status/current-path/context/elapsed/sound footer with CLI-theme token overlays [`src/core/extension-status.ts`]
+            - `renderPiUsereqStatus(...)`: render the status/branch/context/elapsed/sound footer with CLI-theme token overlays [`src/core/extension-status.ts`]
           - `logPromptWorkflowStateChange(...)`: append selected prompt workflow-transition debug entries [`src/index.ts`]
-        - `finalizePromptCommandExecution(...)`: verify persisted execution-session header metadata plus live worktree artifacts, restore the original session-backed base path through the persisted replacement-session context when lifecycle hooks omit `switchSession()`, merge the matched successful worktree branch with `--ff-only` from `base-path`, delete the worktree and branch after merge success, and append selected merge plus workflow-restore debug entries [`src/core/prompt-command-runtime.ts`]
+        - `finalizePromptCommandExecution(...)`: verify persisted execution-session header metadata plus live worktree artifacts, synchronize the successful execution transcript into the restored base session, restore the original session-backed base path through the persisted replacement-session context when lifecycle hooks omit `switchSession()`, merge the matched successful worktree branch with `--ff-only` from `base-path`, delete the worktree and branch after merge success, and append selected merge plus workflow-restore debug entries [`src/core/prompt-command-runtime.ts`]
           - `verifyPromptCommandClosureArtifacts(...)`: verify execution-session header cwd, worktree registration, branch presence, and worktree-path existence without requiring worktree-session reactivation after prompt end [`src/core/prompt-command-runtime.ts`]
+          - `preservePromptCommandExecutionTranscript(...)`: append or materialize the restored base-session transcript from the execution-session JSONL before the base-path switch [`src/core/prompt-command-runtime.ts`]
+            - `readPromptSessionJsonLines(...)`: parse execution-session JSONL records and parse original-session JSONL records when a persisted base session already exists [`src/core/prompt-command-runtime.ts`]
+            - `readPromptSessionFileCwd(...)`: verify the restored session header cwd equals `base-path` after transcript synchronization [`src/core/prompt-command-runtime.ts`]
+            - `readPromptSessionJsonLines(...)`: re-read the restored base session and verify copied execution entry identifiers [`src/core/prompt-command-runtime.ts`]
           - `restorePromptCommandExecution(...)`: switch back to the original session-backed base path, reuse the persisted replacement-session context keyed by the execution-session file, append optional workflow-restore debug entries, clear active worktree path facts, and realign the live `ctx.cwd` mirror before merge or merge-abort return [`src/core/prompt-command-runtime.ts`]
           - `deletePromptWorktree(...)`: delete the merged worktree and branch after successful fast-forward merge [`src/core/prompt-command-runtime.ts`]
         - `restorePromptCommandExecution(...)`: switch back to the original session-backed base path when interrupted, failed, or unmatched prompt-end events skip merge and retain the worktree for manual recovery, reusing the persisted replacement-session context when lifecycle hooks omit `switchSession()` [`src/core/prompt-command-runtime.ts`]
@@ -943,9 +967,14 @@
       - `getProjectBase(...)`: resolve project base from command context cwd [`src/index.ts`]
       - `getProjectConfigPath(...)`: resolve the persisted config path [`src/core/config.ts`]
     - `setPiUsereqStatusConfig(...)`: cache the just-saved docs/tests/src and pi-notify values for status rendering [`src/core/extension-status.ts`]
-    - `renderPiUsereqStatus(...)`: render the status/current-path/context/elapsed/sound footer after save-and-close with CLI-theme token overlays [`src/core/extension-status.ts`]
+    - `renderPiUsereqStatus(...)`: render the status/branch/context/elapsed/sound footer after save-and-close with CLI-theme token overlays [`src/core/extension-status.ts`]
       - `createStatusThemeAdapter(...)`: constrain status rendering to CLI-supported `accent`, `warning`, `dim`, and `error` theme tokens [`src/core/extension-status.ts`]
-      - `buildPiUsereqStatusText(...)`: compose the single-line footer payload with workflow state, current-path, elapsed semantics, and sound status fields [`src/core/extension-status.ts`]
+      - `resolveStatusBranchValue(...)`: resolve the active git branch from the current context cwd before footer rendering [`src/core/extension-status.ts`]
+        - `resolveRuntimeGitBranchName(...)`: resolve the active git branch for the current execution path [`src/core/runtime-project-paths.ts`]
+          - `resolveRuntimeGitPath(...)`: resolve the runtime git root for the active execution path [`src/core/runtime-project-paths.ts`]
+            - `isInsideGitRepo(...)`: test git work-tree membership [`src/core/runtime-project-paths.ts`]
+            - `resolveGitRoot(...)`: resolve repository root [`src/core/runtime-project-paths.ts`]
+      - `buildPiUsereqStatusText(...)`: compose the single-line footer payload with workflow state, branch, context gauge, elapsed semantics, and sound status fields [`src/core/extension-status.ts`]
         - `formatStatusField(...)`: render one colored text field [`src/core/extension-status.ts`]
         - `formatRenderedStatusField(...)`: render one pre-styled field [`src/core/extension-status.ts`]
         - `formatWorkflowStateValue(...)`: render the workflow-state value with error highlighting when required [`src/core/extension-status.ts`]
@@ -962,15 +991,15 @@
       - `buildStaticCheckMenuChoices(...)`: serialize guided add/remove actions plus direct per-language toggle rows [`src/index.ts`]
         - `getSupportedStaticCheckLanguageSupport(...)`: enumerate supported languages and extensions [`src/core/static-check.ts`]
           - `getSupportedStaticCheckLanguages(...)`: enumerate canonical supported languages [`src/core/static-check.ts`]
-        - `buildTerminalSettingsMenuChoices(...)`: append canonical terminal rows to the selector menu [`src/index.ts`]
-      - `buildSupportedStaticCheckLanguageChoices(...)`: serialize supported languages with enablement, configured counts, and terminal rows [`src/index.ts`]
+        - `buildTerminalSettingsMenuChoices(...)`: append the canonical value-less `Reset defaults` row to the selector menu [`src/index.ts`]
+      - `buildSupportedStaticCheckLanguageChoices(...)`: serialize supported languages with enablement, configured counts, and the value-less terminal reset row [`src/index.ts`]
         - `getSupportedStaticCheckLanguageSupport(...)`: enumerate supported languages and extensions [`src/core/static-check.ts`]
           - `getSupportedStaticCheckLanguages(...)`: enumerate canonical supported languages [`src/core/static-check.ts`]
-        - `buildTerminalSettingsMenuChoices(...)`: append canonical terminal rows to the selector menu [`src/index.ts`]
-      - `buildConfiguredStaticCheckLanguageChoices(...)`: serialize configured languages plus terminal rows for removal flows [`src/index.ts`]
+        - `buildTerminalSettingsMenuChoices(...)`: append the canonical value-less `Reset defaults` row to the selector menu [`src/index.ts`]
+      - `buildConfiguredStaticCheckLanguageChoices(...)`: serialize configured languages plus the value-less terminal reset row for removal flows [`src/index.ts`]
         - `getSupportedStaticCheckLanguageSupport(...)`: enumerate supported languages and extensions [`src/core/static-check.ts`]
           - `getSupportedStaticCheckLanguages(...)`: enumerate canonical supported languages [`src/core/static-check.ts`]
-        - `buildTerminalSettingsMenuChoices(...)`: append canonical terminal rows to the selector menu [`src/index.ts`]
+        - `buildTerminalSettingsMenuChoices(...)`: append the canonical value-less `Reset defaults` row to the selector menu [`src/index.ts`]
       - `resetStaticCheckConfig(...)`: restore documented per-language static-check defaults [`src/index.ts`]
         - `getDefaultStaticCheckConfig(...)`: build documented per-language static-check defaults [`src/core/config.ts`]
           - `createStaticCheckLanguageConfig(...)`: clone checker entries and derive the enable flag [`src/core/config.ts`]
@@ -987,30 +1016,30 @@
           - `getConfiguredEnabledPiUsereqTools(...)`: canonicalize configured enabled tools [`src/index.ts`]
             - `normalizeEnabledPiUsereqTools(...)`: canonicalize configurable active tools [`src/core/pi-usereq-tools.ts`]
           - `getPiUsereqStartupTools(...)`: enumerate configurable tools from runtime inventory in documented menu order [`src/index.ts`]
-      - `buildPiUsereqToolToggleChoices(...)`: serialize per-tool startup-toggle rows plus terminal reset/save actions [`src/index.ts`]
-        - `buildTerminalSettingsMenuChoices(...)`: append canonical terminal rows to the selector menu [`src/index.ts`]
+      - `buildPiUsereqToolToggleChoices(...)`: serialize per-tool startup-toggle rows plus the value-less terminal reset action [`src/index.ts`]
+        - `buildTerminalSettingsMenuChoices(...)`: append the canonical value-less `Reset defaults` row to the selector menu [`src/index.ts`]
     - `configureDebugMenu(...)`: interactive debug editor for global enablement, log path, status-change logging, dedicated workflow-event logging, workflow filters, reset confirmation, and per-tool plus per-prompt toggles [`src/index.ts`]
-      - `buildDebugMenuChoices(...)`: serialize global debug controls, workflow-event toggles, canonical tool and prompt toggles, and terminal rows [`src/index.ts`]
+      - `buildDebugMenuChoices(...)`: serialize global debug controls, workflow-event toggles, canonical tool and prompt toggles, and the value-less terminal reset row [`src/index.ts`]
         - `buildDebugMenuChoice(...)`: dim and disable locked debug rows while global debug is off [`src/index.ts`]
         - `getDebugToolToggleNames(...)`: enumerate debuggable tool names in canonical grouped order [`src/index.ts`]
       - `selectDebugLogOnStatus(...)`: select one explicit workflow-state filter or `any` [`src/index.ts`]
       - `confirmResetChanges(...)`: require explicit approval before applying reset mutations [`src/index.ts`]
       - `resetDebugConfigToDefaults(...)`: restore the debug configuration subtree to documented defaults [`src/index.ts`]
     - `configurePiNotifyMenu(...)`: interactive notify, sound, and Pushover editor with credential-locked enablement, immediate-save mutations, reset confirmation, and dedicated event submenus [`src/index.ts`]
-      - `buildPiNotifyMenuChoices(...)`: serialize command-notify, sound, and Pushover blocks plus shared-event submenu launchers and terminal rows [`src/index.ts`]
+      - `buildPiNotifyMenuChoices(...)`: serialize command-notify, sound, and Pushover blocks plus shared-event submenu launchers and the value-less terminal reset row [`src/index.ts`]
         - `buildPiNotifyEventLauncherChoice(...)`: serialize one event-submenu launcher row with a compact enabled-toggle summary [`src/index.ts`]
         - `buildPiNotifyPushoverRows(...)`: serialize direct Pushover rows with locked enablement plus the shared event-submenu launcher [`src/index.ts`]
-        - `buildTerminalSettingsMenuChoices(...)`: append canonical terminal rows [`src/index.ts`]
+        - `buildTerminalSettingsMenuChoices(...)`: append the canonical value-less `Reset defaults` row [`src/index.ts`]
       - `configurePiNotifyEventMenu(...)`: interactive completed/interrupted/failed event editor for one notification transport [`src/index.ts`]
-        - `buildPiNotifyEventMenuChoices(...)`: serialize shared event rows plus submenu reset/save actions [`src/index.ts`]
+        - `buildPiNotifyEventMenuChoices(...)`: serialize shared event rows plus the submenu reset action [`src/index.ts`]
         - `resetPiNotifyEventMenuToDefaults(...)`: restore default event toggles for one notification transport [`src/index.ts`]
         - `resolvePiNotifyEventLabel(...)`: map one event-toggle key to the human-readable menu label [`src/index.ts`]
         - `togglePiNotifyFlag(...)`: toggle one persisted boolean notification setting [`src/index.ts`]
       - `togglePiNotifyFlag(...)`: toggle one persisted boolean notification setting [`src/index.ts`]
-      - `selectPiNotifySoundLevel(...)`: present the `Enable sound` selector with subtree-local reset/save actions [`src/index.ts`]
-        - `buildTerminalSettingsMenuChoices(...)`: append canonical terminal rows to the selector menu [`src/index.ts`]
-      - `selectPiNotifyPushoverPriority(...)`: present the `Normal|High` priority selector with subtree-local reset/save actions [`src/index.ts`]
-        - `buildTerminalSettingsMenuChoices(...)`: append canonical terminal rows to the selector menu [`src/index.ts`]
+      - `selectPiNotifySoundLevel(...)`: present the `Enable sound` selector with the subtree-local reset action [`src/index.ts`]
+        - `buildTerminalSettingsMenuChoices(...)`: append the canonical value-less `Reset defaults` row to the selector menu [`src/index.ts`]
+      - `selectPiNotifyPushoverPriority(...)`: present the `Normal|High` priority selector with the subtree-local reset action [`src/index.ts`]
+        - `buildTerminalSettingsMenuChoices(...)`: append the canonical value-less `Reset defaults` row to the selector menu [`src/index.ts`]
       - `resetPiNotifyConfigToDefaults(...)`: restore notification settings to documented defaults [`src/index.ts`]
     - `getDefaultConfig(...)`: restore default config on reset and subtree-local selector resets [`src/core/config.ts`]
       - `normalizeEnabledPiUsereqTools(...)`: canonicalize configurable active tools [`src/core/pi-usereq-tools.ts`]

package/src/core/debug-runtime.ts

@@ -26,10 +26,10 @@ export const DEFAULT_DEBUG_ENABLED = "disable" as const;
 
 /**
  * @brief Defines the default debug log file value.
- * @details Relative values resolve against the original project base when entries are written. Access complexity is O(1).
+ * @details New configurations write debug JSON entries to `/tmp/PI-useReq.json` unless the user overrides the path. Access complexity is O(1).
  * @satisfies CTN-013, REQ-237
  */
-export const DEFAULT_DEBUG_LOG_FILE = "debug.json";
+export const DEFAULT_DEBUG_LOG_FILE = "/tmp/PI-useReq.json";
 
 /**
  * @brief Defines the default workflow-transition logging mode.

package/src/core/extension-status.ts

@@ -1,10 +1,9 @@
 /**
  * @file
  * @brief Tracks pi-usereq extension status state and renders status-bar telemetry.
- * @details Centralizes hook interception, context-usage snapshots, run timing,
- * and deterministic status-bar formatting for the pi-usereq extension. Runtime
- * is O(1) per event plus O(s) in configured source-path count during status
- * rendering. Side effects are limited to in-memory state mutation and interval
+ * @details Centralizes hook interception, context-usage snapshots, active-branch lookup, run timing, and deterministic status-bar formatting for the pi-usereq extension. Runtime
+ * is O(1) per event plus interval-driven re-renders while a prompt remains
+ * active. Side effects are limited to in-memory state mutation and interval
  * scheduling through exported controller helpers.
  */
 
@@ -16,14 +15,11 @@ import type {
 } from "@mariozechner/pi-coding-agent";
 import type { UseReqConfig } from "./config.js";
 import type { PromptCommandExecutionPlan } from "./prompt-command-runtime.js";
-import {
-  formatRuntimePathForDisplay,
-  getRuntimeContextPath,
-} from "./path-context.js";
 import {
   restorePersistedPromptCommandRuntimeStateForSession,
   writePersistedPromptCommandRuntimeState,
 } from "./prompt-command-state.js";
+import { resolveRuntimeGitBranchName } from "./runtime-project-paths.js";
 
 /**
  * @brief Enumerates the CLI-supported theme tokens consumed by status rendering.
@@ -323,6 +319,17 @@ function createStatusThemeAdapter(theme: RawStatusTheme): StatusThemeAdapter {
   };
 }
 
+/**
+ * @brief Resolves the active git branch value rendered in the status bar.
+ * @details Reads the current branch from the active context working directory on every status render so worktree switches and restored base-session renders expose the latest branch immediately. Runtime is dominated by git execution when the working directory belongs to a repository. Side effects include subprocess creation.
+ * @param[in] ctx {ExtensionContext} Active extension context.
+ * @return {string} Active branch name or `unknown` when unavailable.
+ * @satisfies REQ-121, REQ-283
+ */
+function resolveStatusBranchValue(ctx: ExtensionContext): string {
+  return resolveRuntimeGitBranchName(ctx.cwd);
+}
+
 /**
  * @brief Normalizes one raw context-usage snapshot.
  * @details Preserves the runtime token and context-window counts, derives a
@@ -370,12 +377,10 @@ function refreshContextUsage(
 
 /**
  * @brief Resolves the icon text for one normalized context-usage snapshot.
- * @details Maps context usage to one fixed-width icon band so footer rendering
- * remains compact and deterministic. Unavailable usage degrades to the `0%`
- * icon. Runtime is O(1). No external state is mutated.
+ * @details Maps context usage to one fixed-width icon band so footer rendering remains compact and deterministic across the documented `0`, `>0-<25`, `>=25-<50`, `>=50-<75`, and `>=75` percent bands. Unavailable usage degrades to the `0%` icon. Runtime is O(1). No external state is mutated.
  * @param[in] contextUsage {ContextUsage | undefined} Normalized context snapshot.
  * @return {string} Fixed-width gauge icon text.
- * @satisfies REQ-121, REQ-122
+ * @satisfies REQ-122, REQ-284
  */
 function resolveContextUsageIconText(
   contextUsage: ContextUsage | undefined,
@@ -384,13 +389,13 @@ function resolveContextUsageIconText(
   if (percent === undefined || percent === null || percent <= 0) {
     return "▕_▏";
   }
-  if (percent <= 25) {
+  if (percent < 25) {
     return "▕▂▏";
   }
-  if (percent <= 50) {
+  if (percent < 50) {
     return "▕▄▏";
   }
-  if (percent <= 90) {
+  if (percent < 75) {
     return "▕▆▏";
   }
   return "▕█▏";
@@ -398,24 +403,24 @@ function resolveContextUsageIconText(
 
 /**
  * @brief Formats one icon-based context-usage gauge.
- * @details Renders the documented `warning`-colored icon bands for `0-90%`, applies terminal blink control to the `warning`-colored `>90-100%` icon, and applies terminal blink control to the `error`-colored overflow icon so unsupported terminals degrade to non-blinking colored text automatically. Runtime is O(1). No external state is mutated.
+ * @details Renders the documented gauge icon with theme `error` for `>=90%`, enables terminal blink only for `>=100%`, and otherwise leaves the gauge in the default terminal color. Runtime is O(1). No external state is mutated.
  * @param[in] theme {StatusThemeAdapter} Normalized status theme.
  * @param[in] contextUsage {ContextUsage | undefined} Normalized context snapshot.
  * @return {string} Rendered fixed-width gauge icon.
- * @satisfies REQ-121, REQ-122, REQ-126, REQ-127, REQ-128, REQ-233
+ * @satisfies REQ-122, REQ-126, REQ-127, REQ-128, REQ-233, REQ-284
  */
 function formatContextUsageBar(
   theme: StatusThemeAdapter,
   contextUsage: ContextUsage | undefined,
 ): string {
   const percent = contextUsage?.percent ?? 0;
-  if (percent > 100) {
+  if (percent >= 100) {
     return theme.colorize("error", "\u001b[5m▕█▏\u001b[25m");
   }
-  if (percent > 90) {
-    return theme.colorize("warning", "\u001b[5m▕█▏\u001b[25m");
+  if (percent >= 90) {
+    return theme.colorize("error", "▕█▏");
   }
-  return theme.value(resolveContextUsageIconText(contextUsage));
+  return resolveContextUsageIconText(contextUsage);
 }
 
 /**
@@ -545,23 +550,22 @@ function didAgentEndAbort(messages: AgentEndEvent["messages"]): boolean {
 
 /**
  * @brief Builds the full single-line pi-usereq status-bar payload.
- * @details Renders status, current-path, context, elapsed, and sound fields in the canonical order with dim bullet separators, workflow-state highlighting, and the documented icon-based context gauge. Runtime is O(1). No external state is mutated.
- * @param[in] cwd {string} Runtime working directory used for context-path derivation.
+ * @details Renders status, branch, context, elapsed, and sound fields in the canonical order with dim bullet separators, workflow-state highlighting, and the documented icon-based context gauge. Runtime is O(1). No external state is mutated.
  * @param[in] config {UseReqConfig} Effective project configuration.
  * @param[in] theme {StatusThemeAdapter} Normalized status theme.
  * @param[in] state {PiUsereqStatusState} Mutable status state snapshot.
+ * @param[in] branchName {string} Active git branch name shown in the footer.
  * @param[in] nowMs {number} Current wall-clock time in milliseconds.
  * @return {string} Single-line status-bar text.
- * @satisfies REQ-109, REQ-112, REQ-120, REQ-121, REQ-123, REQ-124, REQ-125, REQ-126, REQ-127, REQ-128, REQ-148, REQ-156, REQ-159, REQ-180, REQ-222, REQ-223
+ * @satisfies REQ-109, REQ-112, REQ-120, REQ-121, REQ-123, REQ-124, REQ-125, REQ-126, REQ-127, REQ-128, REQ-156, REQ-159, REQ-180, REQ-222, REQ-223, REQ-233, REQ-283, REQ-284
  */
 function buildPiUsereqStatusText(
-  cwd: string,
   config: UseReqConfig,
   theme: StatusThemeAdapter,
   state: PiUsereqStatusState,
+  branchName: string,
   nowMs: number,
 ): string {
-  const currentPathText = formatRuntimePathForDisplay(getRuntimeContextPath(cwd));
   const elapsedText = formatElapsedStatusValue(state, nowMs);
   const soundText = config["notify-sound"];
   return [
@@ -570,7 +574,7 @@ function buildPiUsereqStatusText(
       "status",
       formatWorkflowStateValue(theme, state.workflowState),
     ),
-    formatStatusField(theme, "current-path", currentPathText),
+    formatStatusField(theme, "branch", branchName),
     formatRenderedStatusField(
       theme,
       "context",
@@ -666,11 +670,11 @@ export function setPiUsereqStatusConfig(
 
 /**
  * @brief Renders the current pi-usereq status bar into the active UI context.
- * @details Updates the controller's latest context pointer and writes the single-line status text only when configuration is available, deriving `current-path` from the active runtime context path aligned to `ctx.cwd` and including the documented icon-based context gauge. When pi has already invalidated the supplied context after session replacement or reload, the helper clears the stale cached context and returns without surfacing the stale-instance exception. Runtime is O(s) in configured source-path count. Side effect: mutates `ctx.ui` status when the context is still active.
+ * @details Updates the controller's latest context pointer and writes the single-line status text only when configuration is available, including the active branch field and documented icon-based context gauge. When pi has already invalidated the supplied context after session replacement or reload, the helper clears the stale cached context and returns without surfacing the stale-instance exception. Runtime is O(1) plus git execution for branch refresh. Side effect: mutates `ctx.ui` status when the context is still active.
  * @param[in,out] controller {PiUsereqStatusController} Mutable status controller.
  * @param[in] ctx {ExtensionContext} Active extension context.
  * @return {void} No return value.
- * @satisfies REQ-120, REQ-121, REQ-123, REQ-124, REQ-125, REQ-126, REQ-127, REQ-128, REQ-148, REQ-159, REQ-180, REQ-280
+ * @satisfies REQ-120, REQ-121, REQ-123, REQ-124, REQ-125, REQ-126, REQ-127, REQ-128, REQ-159, REQ-180, REQ-233, REQ-280, REQ-283, REQ-284
  */
 export function renderPiUsereqStatus(
   controller: PiUsereqStatusController,
@@ -682,13 +686,14 @@ export function renderPiUsereqStatus(
   }
   try {
     const theme = createStatusThemeAdapter(ctx.ui.theme as RawStatusTheme);
+    const branchName = resolveStatusBranchValue(ctx);
     ctx.ui.setStatus(
       "pi-usereq",
       buildPiUsereqStatusText(
-        ctx.cwd,
         controller.config,
         theme,
         controller.state,
+        branchName,
         Date.now(),
       ),
     );