@timurproko/a1 0.2.7-dev.1276 → 0.2.7-dev.1286

package/dist/ui/components/index.d.ts

@@ -16,7 +16,7 @@ export type { ParsedMouseInput, RoutedMouseInput } from "./mouse.js";
 export { isInsidePane, toPaneLocalMouse } from "./pane.js";
 export type { Pane, PaneInputResult, PaneMouseEvent } from "./pane.js";
 export { sessionNameFrame } from "./session-name-frame.js";
-export { progressStatusFrame, progressStatusText } from "./progress-status.js";
+export { progressStatusFrame, progressStatusText, isProgressSpinnerStyle, progressSpinnerFrame, PROGRESS_SPINNER_INTERVAL_MS } from "./progress-status.js";
 export type { ProgressStatusFrameStyles, ProgressStatusMarker } from "./progress-status.js";
 export { FrameCache, RENDER_REVISION_KINDS, RenderRevisionTracker, ZERO_REVISIONS, normalizeRevisions, revisionsEqual } from "./revision.js";
 export type { RenderCacheContract, RenderRevisionKind, RenderRevisions } from "./revision.js";

package/dist/ui/components/index.js

@@ -8,7 +8,7 @@ export { STEPPER_RESERVE, placementFor, regionAt, renderGroupHeader, renderListR
 export { MOUSE_TRACKING_OFF, MOUSE_TRACKING_ON, parseMouseInput, routeMouseInput } from "./mouse.js";
 export { isInsidePane, toPaneLocalMouse } from "./pane.js";
 export { sessionNameFrame } from "./session-name-frame.js";
-export { progressStatusFrame, progressStatusText } from "./progress-status.js";
+export { progressStatusFrame, progressStatusText, isProgressSpinnerStyle, progressSpinnerFrame, PROGRESS_SPINNER_INTERVAL_MS } from "./progress-status.js";
 export { FrameCache, RENDER_REVISION_KINDS, RenderRevisionTracker, ZERO_REVISIONS, normalizeRevisions, revisionsEqual } from "./revision.js";
 export { COPY_ACKNOWLEDGEMENT_DURATION_MS, MAX_COPY_ROWS, MAX_COPY_SOURCE_UNITS, copyAcknowledgementText, selectionCopyLineContent, selectionCopyRowText } from "./selection-copy.js";
 export { ScrollbarRails, isThumbRow, scrollForThumbRow, scrollForTrackPage, scrollbarGeometry, scrollbarPresentation, scrollbarReservesSpace, scrollbarSelectionRows, scrollbarWheelRows, } from "./scrollbar.js";

package/dist/ui/components/progress-status.d.ts

@@ -1,4 +1,11 @@
+import type { ProgressSpinnerStyle } from "../../contracts/presentation/index.js";
 export type ProgressStatusMarker = "…" | "...";
+/** Pinned loader cadence, shared by the focused Settings preview. */
+export declare const PROGRESS_SPINNER_INTERVAL_MS = 80;
+/** Accepts only the declared owned spinner choices. */
+export declare function isProgressSpinnerStyle(value: unknown): value is ProgressSpinnerStyle;
+/** One fixed-cell glyph; actual Current indicators retain the loader's supplied frame. */
+export declare function progressSpinnerFrame(style: ProgressSpinnerStyle, phase: number, currentFrame?: string): string;
 export interface ProgressStatusFrameStyles {
     readonly muted: (text: string) => string;
     readonly highlight: (text: string) => string;

package/dist/ui/components/progress-status.js

@@ -1,3 +1,24 @@
+/** Pinned loader cadence, shared by the focused Settings preview. */
+export const PROGRESS_SPINNER_INTERVAL_MS = 80;
+const SPINNER_FRAMES = {
+    none: [],
+    current: ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"],
+    circle: ["◐", "◓", "◑", "◒"],
+    diamond: ["◇", "◈", "◆", "◈"],
+    square: ["◧", "◩", "◨", "◪"],
+};
+/** Accepts only the declared owned spinner choices. */
+export function isProgressSpinnerStyle(value) {
+    return typeof value === "string" && Object.hasOwn(SPINNER_FRAMES, value);
+}
+/** One fixed-cell glyph; actual Current indicators retain the loader's supplied frame. */
+export function progressSpinnerFrame(style, phase, currentFrame) {
+    if (style === "current" && currentFrame !== undefined)
+        return currentFrame;
+    const frames = SPINNER_FRAMES[style];
+    const index = Number.isFinite(phase) ? Math.max(0, Math.floor(phase)) : 0;
+    return frames.length === 0 ? "" : frames[index % frames.length];
+}
 const GRAPHEMES = new Intl.Segmenter(undefined, { granularity: "grapheme" });
 const HIGHLIGHT_WIDTH = 2;
 const UPDATES_PER_STEP = 3;

package/dist/ui/components/value-menu.d.ts

@@ -7,7 +7,7 @@ import type { UiTheme } from "./theme.js";
 export interface ValueMenuState {
     /** Values offered, as they should read. */
     readonly choices: readonly string[];
-    /** Optional already-painted square previews, aligned before each choice label. */
+    /** Optional already-painted glyph previews, aligned before each choice label. */
     readonly previews?: readonly string[];
     /** The value in effect, marked rather than highlighted. */
     readonly current: string | null;

package/dist/ui/components/value-menu.js

@@ -11,7 +11,7 @@ export function valueMenuFrame(state, anchor, layout) {
     const top = Math.max(bodyTop, Math.min(anchor.screenRow - currentIndex, bodyBottom - state.choices.length));
     const previewWidth = Math.max(0, ...(state.previews ?? []).map(displayWidth));
     const previewColumns = previewWidth === 0 ? 0 : previewWidth + 1;
-    const width = Math.max(...state.choices.map(choice => displayWidth(choice) + previewColumns + 4), 6);
+    const width = Math.min(Math.max(0, layout.surfaceWidth - layout.reservedRight), Math.max(...state.choices.map(choice => displayWidth(choice) + previewColumns + 4), 6));
     // Invariant: rows reserve two cells for the effective-value mark and, when present,
     // a preview plus one gap. Choice text remains aligned with the source value column.
     const column = Math.min(Math.max(0, anchor.valueColumn - 2 - previewColumns), Math.max(0, layout.surfaceWidth - width - layout.reservedRight));
@@ -20,6 +20,8 @@ export function valueMenuFrame(state, anchor, layout) {
 /** Draws the menu over the rows behind it, leaving them otherwise untouched. */
 export function renderValueMenu(lines, state, frame, theme) {
     const output = [...lines];
+    if (frame.width <= 0)
+        return output;
     state.choices.forEach((choice, index) => {
         const target = frame.top + index;
         if (target < 0 || target >= output.length)
@@ -31,7 +33,7 @@ export function renderValueMenu(lines, state, frame, theme) {
         const previewWidth = Math.max(0, ...previews.map(displayWidth));
         const preview = previewWidth === 0 ? "" : `${padToWidth(previews[index] ?? "", previewWidth)} `;
         // Invariant: the current-value check stays on ordinary text while the optional
-        // square carries the palette color; the row treatment supplies only its surface.
+        // preview carries its own color; the row treatment supplies only its surface.
         const tail = padToWidth(`${current ? " " : "  "}${preview}${choice} `, frame.width - (current ? 1 : 0));
         const painted = current
             ? `${paint(theme.fg("text", "✓"))}${paint(tail)}`

package/dist/ui/settings/declarations.d.ts

@@ -70,6 +70,18 @@ export declare const OWNED_SETTING_DECLARATIONS: Readonly<{
         defaultValue: true;
         allowedValues: readonly [true, false];
     }>;
+    readonly spinnerStyle: Readonly<{
+        id: "spinnerStyle";
+        label: "Spinner style";
+        section: Readonly<{
+            id: "appearance";
+            title: "Appearance";
+        }>;
+        description: "Indicator beside working and operation progress text. None keeps text only; Current keeps the dot spinner.";
+        application: "live";
+        defaultValue: "current";
+        allowedValues: readonly ["none", "current", "circle", "diamond", "square"];
+    }>;
     readonly scrollbarAppearance: Readonly<{
         id: "scrollbarAppearance";
         label: "Scrollbar mode";
@@ -149,7 +161,7 @@ export declare const OWNED_SETTING_DECLARATIONS: Readonly<{
             id: "agent";
             title: "Agent";
         }>;
-        description: "Name unnamed sessions from the first prompt; regenerate automatic names on the next prompt after a worktree context change. Manual names are preserved.";
+        description: "Name unnamed sessions from the current task and relevant discussion; regenerate on the next prompt after a worktree context change. Manual names are preserved.";
         application: "live";
         defaultValue: true;
         allowedValues: readonly [true, false];
@@ -161,10 +173,10 @@ export declare const OWNED_SETTING_DECLARATIONS: Readonly<{
             id: "agent";
             title: "Agent";
         }>;
-        description: "Format for future automatic names: fix-api-cache, Fix API cache, or Fix API Cache. Existing and manual names stay unchanged.";
+        description: "Format for future automatic names: Fix API cache (default), fix-api-cache, or Fix API Cache. Existing and manual names stay unchanged.";
         application: "live";
-        defaultValue: "kebab";
-        allowedValues: readonly ["kebab", "sentence", "title"];
+        defaultValue: "sentence";
+        allowedValues: readonly ["sentence", "kebab", "title"];
     }>;
     readonly promptSuggestions: Readonly<{
         id: "promptSuggestions";

package/dist/ui/settings/declarations.js

@@ -46,6 +46,15 @@ export const OWNED_SETTING_DECLARATIONS = Object.freeze({
         defaultValue: true,
         allowedValues: Object.freeze([true, false]),
     }),
+    spinnerStyle: Object.freeze({
+        id: "spinnerStyle",
+        label: "Spinner style",
+        section: APPEARANCE_SECTION,
+        description: "Indicator beside working and operation progress text. None keeps text only; Current keeps the dot spinner.",
+        application: "live",
+        defaultValue: "current",
+        allowedValues: Object.freeze(["none", "current", "circle", "diamond", "square"]),
+    }),
     scrollbarAppearance: Object.freeze({
         id: "scrollbarAppearance",
         label: "Scrollbar mode",
@@ -104,7 +113,7 @@ export const OWNED_SETTING_DECLARATIONS = Object.freeze({
         id: "sessionAutoName",
         label: "Automatic session name",
         section: AGENT_SECTION,
-        description: "Name unnamed sessions from the first prompt; regenerate automatic names on the next prompt after a worktree context change. Manual names are preserved.",
+        description: "Name unnamed sessions from the current task and relevant discussion; regenerate on the next prompt after a worktree context change. Manual names are preserved.",
         application: "live",
         defaultValue: true,
         allowedValues: Object.freeze([true, false]),
@@ -113,10 +122,10 @@ export const OWNED_SETTING_DECLARATIONS = Object.freeze({
         id: "sessionNameFormat",
         label: "Session name format",
         section: AGENT_SECTION,
-        description: "Format for future automatic names: fix-api-cache, Fix API cache, or Fix API Cache. Existing and manual names stay unchanged.",
+        description: "Format for future automatic names: Fix API cache (default), fix-api-cache, or Fix API Cache. Existing and manual names stay unchanged.",
         application: "live",
-        defaultValue: "kebab",
-        allowedValues: Object.freeze(["kebab", "sentence", "title"]),
+        defaultValue: "sentence",
+        allowedValues: Object.freeze(["sentence", "kebab", "title"]),
     }),
     promptSuggestions: Object.freeze({
         id: "promptSuggestions",

package/docs/architecture/internal-naming.md

@@ -66,7 +66,7 @@ The old environment registry included `fixture` and `inputAcknowledgement`, but
 
 `certificationTarball`, `internalPackaging`, `nativePi`, `piParityIntentionalMutation`, `protocolVersion`, `structuredFlowLimits`, `terminalArgumentsJson`, and `terminalExecutable` had no active runtime consumer in the reviewed tree. They are removed from the current environment authority, not renamed into new settings. Rejection patterns and immutable historical evidence remain factual.
 
-The release store (`src/foundation/release/release-state.ts`, persisted as `release-state.json`) keeps the schema id `a1-release-cohort-v1` and the identity key `releaseCohortSchema`. "Cohort" is a legacy name from the retired supervisor era; the id is unchanged because every installed release state carries it, and renaming it would make existing installations unreadable.
+The release store (`src/foundation/release/release-state.ts`, persisted as `release-state.json`) uses `a1-release-cohort-v2` and retains the identity key `releaseCohortSchema`. "Cohort" is a historical wire name, not a supervisor. New readers accept v1 and preserve its records; the next locked write upgrades control state to v2. This deliberately fences older cleanup/control writers that cannot protect live release-use claims. Existing sessions are not migrated or restarted, legacy approved roots remain protected, and a claim-aware launcher may still run a retained older UI. A pre-v2 launcher cannot independently control a v2 store.
 
 ## Negotiated handoff and protected state
 

package/docs/architecture/project-structure.md

@@ -93,11 +93,11 @@ Build output mirrors the production namespaces directly under ignored `dist/`, w
 
 ## Development worktrees
 
-Every task worktree must be created at `{working-dir}/.worktrees/<task-id>`, where `{working-dir}` is the agent session's initial working directory. The `.worktrees` directory is inside that working directory, not beside it. For working directory `D:/Git/a1`, `D:/Git/a1/.worktrees/<task-id>` is correct and `D:/Git/a1-<task-id>` is forbidden.
+Task checkouts live inside the primary repository's `.worktrees/<task-id>/`, not beside the repository. Follow the shared Worktrees guidance in `AGENTS.md`. The product command contract is documented in [Worktree commands](../features/worktrees.md).
 
 ### Common Git workflow
 
-External agents use ordinary Git without an A1 installation, runtime, or session link. Keep primary on `develop`, run the bounded cleanup sweep and relay its `lines`, then inspect `git worktree list --porcelain` from primary. Inventory is read-only and advisory; it is not atomic editing exclusion or permission to adopt a checkout.
+Keep primary on `develop` and run the delivery skill's bounded cleanup sweep. In A1, enter or attach once; success is authoritative and informational inventory is not a second approval gate. Outside A1, use ordinary Git without installing A1 or inventing runtime identities.
 
 For a new delivery, create a unique absent task path and a new topic branch from freshly fetched `origin/develop`, unless the maintainer selected another base. For example, with primary at `D:/Git/a1` and unused task/branch names:
 
@@ -105,25 +105,21 @@ For a new delivery, create a unique absent task path and a new topic branch from
 cd /d/Git/a1 && git fetch origin develop && git worktree add -b feature/example-task .worktrees/example-task origin/develop && git -C .worktrees/example-task rev-parse --show-toplevel --git-common-dir && git -C .worktrees/example-task status --short --branch
 ```
 
-Successful creation by this session establishes provenance for that fresh checkout. Before planning, implementation, test, or delivery-documentation edits, verify the exact canonical root, common Git repository, intended branch, and working-tree state. Relative Git directory results must resolve to the primary repository's common directory. A path/branch collision never permits force creation, overwriting, or adoption of the existing checkout. A context mismatch means stop edits and report the blocker; never fall back to task edits in primary.
+For external agents, successful creation establishes provenance for a fresh checkout; verify the canonical root, common repository, branch, and local work before using it. Never force a collision or fall back to task edits in primary. A1 performs its own exact-context and editing-claim checks internally.
 
 ### Resume and ownership
 
-Reuse an existing checkout only when its exact branch, OpenSpec change, and PR match the requested stream and continuing ownership or explicit handoff from the prior owner or maintainer is established without conflicting ownership evidence. Names, similar files, recency, cleanliness, and ancestry are not ownership evidence. Inspect Git worktree locks and the cleanup journal's `status`; claim any released cleanup registration through the [cleanup ownership protocol](../local-worktree-cleanup.md#resume-or-recover-ownership) before editing. An owned registration requires matching owner authority. Neither an unregistered path nor a successful cleanup claim proves that no other editor is using it.
+Continue the same task's branch, change, and PR. A1 owns cooperative editing claims and preserves existing edits when resuming; external agents establish continuing ownership or an explicit handoff themselves. Cleanup registration remains a separate repository concern: follow [cleanup ownership](../local-worktree-cleanup.md#resume-or-recover-ownership) when resuming a released cleanup candidate. Neither attachment nor cleanup registration authorizes merge or deletion.
 
-Known live editing claims, foreign cleanup ownership, Git locks, and unverifiable handoffs block reuse. Stop edits and report the blocker, or use a safe fresh worktree without overriding, recovering, unlocking, unlinking, or waiting out another owner. Preserve the existing delivery's branch/history/PR: do not force a branch checked out elsewhere or create a replacement PR to evade ownership. If the same stream cannot safely continue, report that concrete blocker.
-
-Repeat exact-context and ownership verification when resuming or switching streams. Handoffs name the absolute worktree, branch, change, PR, and whether editing ownership is being handed over. This is cooperative coordination, not enforcement against arbitrary external editors. Missing A1 integration alone never blocks external agents and is not evidence of a conflicting owner.
+Do not replace a delivery's history or PR to evade a real ownership conflict. Handoffs name the absolute worktree, branch, change, PR, and editing handoff. Runtime coordination is cooperative, not exclusion against arbitrary external editors.
 
 ### Environment-specific adapters
 
-Inside an active A1 shell-tool session only, run `a1 session worktrees` and `a1 session link-worktree <absolute-worktree>` before edits to acquire the runtime's editing claim and footer association. An `available` result still needs atomic linking; a `busy` or `unverifiable` owner, failed association, lost race, or different returned path blocks edits there. A failed stream switch preserves the prior association. External agents use the common Git workflow instead of fabricating runtime identities or starting A1 just to satisfy repository policy.
-
-A stale Git registration elsewhere whose directory is missing and whose row is `prunable` may be pruned before retrying inventory; this does not permit removing a live checkout. Mutation-gate corruption and transient A1 startup-registration failures have a separate [worktree-link recovery procedure](../worktree-link-recovery.md). Recovery never overrides a live or unverifiable editing claim.
+A1 owns creation/attachment, bounded retries, and ordinary recovery behind its worktree commands. Successful attachment returns the canonical path and branch; no follow-up inventory check is required. The old session link/unlink commands remain compatible aliases. Rare installation/legacy coordination failures have an operator [recovery reference](../worktree-link-recovery.md), not an agent preflight procedure.
 
 Claude Code uses its established `EnterWorktree` tool by task name. The tracked `.claude/settings.json` wires `scripts/governance/claude-worktree-create.mjs` to create `.worktrees/<task-id>` detached at fresh `origin/develop`, or return an already registered path. The agent must still establish ownership before reusing that path and create the topic branch in a new detached worktree before editing. Passing an absolute `path` to `EnterWorktree` is reserved for a worktree created by hand, from primary before any shell command in that session. The matching `WorktreeRemove` hook declines removal: leave with `ExitWorktree` `keep` and use only the guarded cleanup tool for removal. Other agents do not need these tools or hooks.
 
-A1 linking acquires a cooperative live-session editing claim and switches footer repository/PR discovery; an existing draft PR is not required when linking first succeeds. Clean unlink/disposal releases that runtime claim; a crashed A1 owner becomes reusable only after its recorded process is no longer running. Runtime association does not change process or tool cwd, create a Git lock, or register, release, or authorize cleanup. Context verification and editing handoff also grant no acceptance, finalization, merge, deletion, or cleanup authority. Repository commands therefore keep an explicit worktree path. The primary worktree stays on `develop` for integration and must not be used for task edits. Do not edit, adopt, move, or remove another session's worktree.
+A1 attachment updates footer repository/PR discovery and subsequent built-in tool working directories without changing process-global cwd. Detach/disposal releases the runtime's claim and preserves Git data. An existing PR is not required. Explicit absolute paths retain their meaning; custom extensions and independent terminals keep their own cwd. Attachment never creates a Git lock, changes cleanup registration, or grants acceptance, finalization, merge, or deletion authority.
 
 An agent that directly chooses a transient file path for a PR/comment body, command payload, captured output, temporary patch/diff, or ad hoc log must place it beneath the verified task worktree's exact `.artifacts/` root, never the primary checkout, another worktree, OS temp, home/desktop, or a sibling path. Such scratch remains ignored, unstaged, uncommitted, disposable, non-authoritative, and secret-free. This repository path rule does not relocate storage internally selected by tools, product runtime code, or hermetic tests.
 

package/docs/features/session-exports.md

@@ -12,4 +12,4 @@ Automatic export storage refuses linked storage-directory entries rather than fo
 
 Exports are user data and can contain private session content. They are not disposable build artifacts, do not belong in `.artifacts/`, and are never removed by ordinary worktree cleanup. The `a1 pi` comparison profile retains its pinned export behavior.
 
-For an old export already blocking an eligible merged worktree, see the explicit named-export preservation operation in [local worktree cleanup](../local-worktree-cleanup.md). It preserves and verifies the selected export before removing only its original pathname; it does not remove the worktree or bypass other local-content checks.
+For an old export blocking worktree cleanup, follow [export decisions](../local-worktree-cleanup.md#export-decisions): an explicit request to delete the identified file is sufficient, without mandatory preservation or another confirmation. If preservation is wanted instead, the optional named-export operation saves and verifies a copy before removing the source. Neither choice bypasses ordinary worktree cleanup checks.

package/docs/features/session-naming.md

@@ -1,6 +1,8 @@
 # Session names
 
-Bare A1 automatically names an unnamed session from its first prompt while the agent works. Names are short labels (up to 16 characters, including separators), generated by the active model in a separate tool-free request. The request does not add a conversation turn or delay the main response. It makes at most two attempts, with 30-second deadlines and respective 4,096/32,768 token ceilings; provider failures use a deterministic prompt-based fallback.
+Bare A1 automatically names an unnamed session from its current task while the agent works. Names prefer two or three descriptive words, with a maximum of three words and 32 characters including separators. The active model receives the current prompt, verified worktree/branch hints, and bounded relevant recent discussion in a separate tool-free request. Short approvals such as `ok do it` refer back to the concrete task, producing names such as `Spinner style settings` rather than `Implement task`. Images, tool output, thinking blocks, and pasted-image paths are not naming subjects.
+
+The request does not add a conversation turn or delay the main response. It makes at most two attempts, with 30-second deadlines and respective 4,096/32,768 token ceilings. Failed, empty, generic, or attachment-path results use a deterministic fallback from meaningful task words or current branch hints; when no usable task words exist, the fallback is `New task` in the default format.
 
 **Automatic session name** in the Agent settings group is enabled by default. Turning it off cancels pending naming without deleting the current name. The `a1 pi` comparison profile does not receive automatic naming or the A1 footer layout/reveal.
 
@@ -10,11 +12,11 @@ Choose **Session name format** in Agent settings:
 
 | Choice | Example |
 | --- | --- |
-| **Kebab case** (default) | `fix-api-cache` |
-| **Sentence case** | `Fix API cache` |
+| **Sentence case** (default, first choice) | `Fix API cache` |
+| **Kebab case** | `fix-api-cache` |
 | **Title Case** | `Fix API Cache` |
 
-Sentence case capitalizes the first word; Title Case capitalizes every ordinary word. Both preserve acronyms and technical spellings supplied by the model, such as `API` and `GitHub`. The same format applies to prompt-based fallback, and all formats keep the 16-character limit, trimming at a word boundary where possible.
+Sentence case capitalizes the first word; Title Case capitalizes every ordinary word. Both preserve acronyms and technical spellings supplied by the model, such as `API` and `GitHub`. The same format applies to contextual fallback, and all formats enforce the three-word/32-character limits, trimming at a word boundary where possible. Valid saved format choices are preserved; only missing or invalid values use Sentence case.
 
 The choice is saved to your A1 profile and applies live to future automatic naming, including context regeneration and pending results. Changing it does not rewrite an existing name or start another naming request. Manual `/name` values remain untouched.
 
@@ -22,7 +24,7 @@ The choice is saved to your A1 profile and applies live to future automatic nami
 
 Linking a different worktree, clearing and re-entering the same worktree, or changing its confirmed branch makes an automatic name eligible for regeneration. A durable association revision detects exit/re-entry even between footer refreshes. Repeating a link without leaving, runtime heartbeats, commits, dirty files, and PR-check updates do not trigger regeneration.
 
-The old name stays visible until the **next user prompt** starts a run in the new context. That prompt and bounded worktree/branch hints determine the replacement; the original session prompt and old conversation are not reused. Worktree changes during a running turn wait for another prompt. Naming provenance and the completed context survive restart/resume, so resuming unchanged work does not rename it.
+The old name stays visible until the **next user prompt** starts a run in the new context. That prompt, bounded worktree/branch hints, and relevant recent task discussion determine the replacement. A short approval can use discussion matching the new task, but unrelated original prompts and old tasks are excluded. Worktree changes during a running turn wait for another prompt. Naming provenance and the completed context survive restart/resume, so resuming unchanged work does not rename it.
 
 Manual `/name` renames always win, including a manual rename to the same text as an automatic name. Existing named sessions without A1 automatic-name provenance are preserved. Automatic generation cannot overwrite a manual rename or apply to a different session/context after a late provider response.
 
@@ -30,7 +32,7 @@ Manual `/name` renames always win, including a manual rename to the same text as
 
 - The first footer row shows the path, branch, and optional linked PR number.
 - The second row shows stats/context, then ` • session-name`, with the model/thinking text still aligned right.
-- If space is tight, the name is clipped or omitted before existing stats/model content is displaced. Unnamed sessions have no dangling separator.
+- If space is tight, detailed stats are trimmed first to preserve the full name beside the model/thinking segment. Optional provider/route text can be omitted; the name is clipped only if it still cannot fit after stats are reduced. Unnamed sessions and rows without stats have no dangling separator.
 
 A changed automatic name reveals in the configured accent's **secondary color**: 600 ms tonal shimmer over the old name, 45 ms per grapheme to reveal the replacement, then 300 ms fade to ordinary dim text. Palette terminals use a plain typewriter reveal. Live accent changes recolor active frames without restarting them. Repeated redraws, resume, and an unchanged regenerated name do not replay the animation; manual names change immediately.
 

package/docs/features/worktrees.md

@@ -0,0 +1,38 @@
+# Worktree commands
+
+A1 owns worktree creation, attachment, cooperative editing claims, and ordinary recovery. Repository instructions only guide agents to these commands; they do not implement a second verification or lock-management procedure.
+
+## Command contract
+
+Run these commands through an active A1 session's shell tool:
+
+| Command | Result |
+| --- | --- |
+| `a1 worktree enter <type/short-description> [--base <branch>]` | Create or resume the matching task checkout and attach it. |
+| `a1 worktree attach <absolute-path>` | Attach an existing registered task checkout in this session's repository. |
+| `a1 worktree detach` | Release this session's attachment without deleting files or branches. |
+| `a1 worktree list` | Informational same-repository inventory; never required after success. |
+
+Successful enter/attach returns the canonical root and branch after acquiring the editing claim. It is the complete attachment result: agents do not run a second inventory approval gate or implement their own retry loop. Temporary registration/coordination contention is retried within an operation budget. Actual ownership conflicts and uncertain records produce actionable failures rather than unsafe takeovers. A failed switch preserves the prior attachment. No command removes worktrees, branches, user files, or private workspace data.
+
+Enter creates `.worktrees/<short-description>` under the primary checkout. It fetches the selected origin base before creating a new topic branch. Base selection is explicit `--base`, local Git configuration `a1.worktreeBase`, then the origin default branch; local-only repositories fall back to the primary branch. Existing matching worktrees keep their local edits and history. Path/branch collisions, primary checkouts, foreign repositories, and Git-locked worktrees are retained, not forced or adopted. Setup commands, dependency installation, private-clone provisioning, and repository hooks are not executed by A1.
+
+`a1 session link-worktree`, `unlink-worktree`, and `worktrees` remain compatible aliases for attach, detach, and list. They use the same authoritative results and internal retries.
+
+## Working directories
+
+After successful attachment, subsequent built-in read, bash, edit, write, grep, find, and ls calls resolve relative paths from the verified attached root. Detach returns those tools to the session's startup directory. The already-running shell that issued the attachment finishes in its original cwd; A1 does not rewrite shell commands or call process-global chdir. Explicit absolute paths retain their ordinary meaning. Project resources, settings, custom extensions, and independent terminals keep their own discovery/cwd behavior; use the returned explicit root for those integrations.
+
+Background footer polling activates persisted claims once per session binding, then observes without rewriting healthy runtime registrations or claims. Informational listing waits for a consistent coordination snapshot rather than marking all owners unverifiable because an unrelated mutation happens to be running. Runtime shutdown releases its own claims. Crash recovery preserves durable attachment state and checks recorded process liveness before another runtime can acquire a claim.
+
+Implementation completion and review handoff do not end the task attachment. Keep it active for review and follow-up fixes so built-in tools and footer PR discovery continue using the task checkout. Detach only when explicitly requested or switching tasks; runtime shutdown releases editing claims automatically. Repository cleanup handoff is independent and does not require runtime detach.
+
+Claims coordinate participating A1 sessions. They are not a sandbox against arbitrary external editors, an editing lock in Git, repository cleanup ownership, or permission to merge/delete anything. Delivery and protected cleanup remain independent.
+
+## Shared repository guidance
+
+Use this identical block in repositories, without adding another inventory approval gate:
+
+> In an active A1 session, use `a1 worktree enter <branch>` or `a1 worktree attach <absolute-path>`. Work in the returned directory; successful completion is the attachment confirmation. Keep the task attached after implementation completion and review handoff so follow-up fixes retain its checkout and PR. Use `a1 worktree detach` only when explicitly requested or switching tasks; it preserves files and branches. Runtime shutdown releases claims automatically. A1 owns coordination, retries, and recovery; `a1 worktree list` is informational. Outside A1, use ordinary Git worktrees.
+
+Install an A1 release exposing this interface before integrating a repository's instruction migration. Older installations only expose the session-context aliases; unknown commands in those older releases may return quietly without performing an operation. A migration PR is not evidence that a compatible installed release is active.

package/docs/local-worktree-cleanup.md

@@ -6,6 +6,21 @@ The implementation is repository tooling, not part of the installed A1 product.
 
 If the whole repository moves to another canonical path or Windows drive, a carried cleanup journal still names the old absolute paths. Read-only `status` and `preview` report `state-relocation-required` and never rewrite it. The next mutation-locked operation safely rebases the journal only when every recorded entry is completed terminal history, the repository and remote identities still match, and every historical path is beneath the old recorded worktree root. The migration is atomic and changes only repository/path fields; the requested current worktree is then captured afresh and must pass every ordinary cleanup gate. Any owned, released, partially deleting, malformed, escaped, or identity-mismatched entry blocks relocation without changing the journal or local resources.
 
+## Cleanup decisions
+
+Use one clear request for one identified scope; do not ask the maintainer to repeat a decision already supplied. Tool confirmation flags encode that authority and are not a reason for another conversational confirmation.
+
+| Request | Action |
+| --- | --- |
+| Ordinary cleanup of completed work | Use `sweep` for released candidates or exact `complete`; retain every reported blocker. |
+| Delete one identified export | Follow [export decisions](#export-decisions); preservation is not mandatory. |
+| Preserve one identified export | Use optional [named-export preservation](#explicit-named-export-preservation). |
+| Discard a rejected change and its remote branch | Use exact confirmed `discard` only when both rejection and remote deletion are authorized. One explicit request can supply both. |
+| Stop development processes, remove a disposable link, retire a redundant checkout, or enable background cleanup | Use the corresponding exact authorized operation below; generic cleanup does not imply these extra permissions. |
+| Ambiguous file, conflicting owner, dirty work, unavailable evidence, or a lock | Retain the affected scope and report the actionable blocker. Ask only for a missing decision; do not repeat an unchanged attempt without a reason. |
+
+Automatic cleanup remains conservative. Explicit file decisions do not weaken worktree/branch eligibility, ownership, content, link, process, or compare-and-delete safeguards. Use integrated tooling from primary, not unmerged task tooling against live worktrees. Detailed journals, races, and recovery belong in tooling and the sections below; user-facing reports should state the result or blocker concisely.
+
 ## Hand-off and sweep: the ordinary agent path
 
 The delivering agent's session usually ends before the maintainer merges, so cleanup is split into two commands that never need the same session. When the validated PR is handed to the maintainer, and again after any repair push, the owning agent parks the worktree from the primary checkout:
@@ -92,7 +107,7 @@ Agents do not manually remove generated content, call `git worktree remove`, or
 
 ## Explicit closed-unmerged discard
 
-Closing a PR does not itself authorize deletion. After the maintainer explicitly rejects one exact PR and separately confirms remote deletion, run the candidate-scoped command from the primary checkout:
+Closing a PR does not itself authorize deletion. Require explicit rejection of the exact PR and authority to delete its remote branch; one clear request may supply both. Then run the candidate-scoped command from the primary checkout:
 
 ```bash
 node scripts/governance/local-worktree-cleanup.mjs discard \
@@ -119,11 +134,19 @@ Branch mode verifies the named same-repository PR is still closed-unmerged into
 
 A branch-scoped `branch-discard-<ref-digest>.json` journal beside the ordinary cleanup state pins the repository, exact ref, change, PR, expected head, and deletion step without changing existing worktree records. After local preflight, the command journals intent, revalidates live evidence, expected-head deletes only the remote ref, verifies remote absence, and compare-and-deletes the unchanged local ref. Absent refs support resumption. Repeated completed requests report `already-discarded` only while both refs remain absent; a recreated ref is retained as `discard-ref-recreated`. Command reports, not the worktree-only registration list, describe this branch-scoped state. Sweep and queue never invoke branch-only discard.
 
-## Explicit named-export preservation
+## Export decisions
 
-Default bare-A1 exports now live in the persistent user directory `~/.a1/exports/`; see [session exports](features/session-exports.md). Existing exports in a worktree remain user data, not cleanup disposables. Adding a filename pattern to `.gitignore` or the disposable policy is not a preservation operation.
+Default bare-A1 exports live in `~/.a1/exports/`; see [session exports](features/session-exports.md). An existing worktree export is user data, not an automatic cleanup disposable.
+
+- **Delete:** an explicit request to delete one identified export is sufficient. Its exact path or an unambiguous previously reported blocker in the same interaction identifies the file; do not demand a copy or another preservation confirmation. Verify the candidate and ownership, regular-file identity, untracked HTML/JSONL status, and real non-link ancestors within that worktree. Recheck identity immediately before non-recursively unlinking only that file. Do not follow links, delete directories, remove tracked content, or resolve another owner's blocker by deleting their files.
+- **Preserve:** when chosen, use the optional confirmed operation below. Its verified-copy and journal safeguards remain unchanged.
+- **Unspecified:** a generic cleanup request does not authorize deleting unknown exports. Report the file and ask only whether to retain, preserve, or delete it. Do not add a blanket filename pattern to ignored/disposable content.
+
+Either file decision leaves subsequent worktree and branch removal to integrated cleanup tooling with every ordinary safeguard intact. A deletion request does not authorize overriding another blocker.
+
+## Explicit named-export preservation
 
-After the maintainer explicitly chooses one named legacy export to preserve, run the integrated repository operation from primary:
+This optional operation is for a maintainer who wants to keep a named legacy export. It is not a prerequisite when deletion was explicitly requested. Run it from primary:
 
 ```bash
 cd /d/Git/a1 && node scripts/governance/local-worktree-cleanup.mjs preserve-export --repo D:/Git/a1 --path D:/Git/a1/.worktrees/example-task --change example-change --pr 123 --file session.html --confirm-preserve-export

package/docs/openspec-archive-automation.md

@@ -6,13 +6,39 @@ Unrelated standalone documentation remains separate: a non-draft unassociated PR
 
 Version-1 and version-2 deliveries and their existing comments, acceptance PRs, archive PRs, receipts, retries, and bounded catch-up remain supported under [Legacy delivery](#legacy-delivery). Do not silently convert an in-flight legacy delivery.
 
-## Worktree context across agent environments
+## Agent operating guide
+
+This runbook owns the delivery lifecycle. The [worktree protocol](architecture/project-structure.md#development-worktrees) owns checkout creation, identity, ownership, and runtime adapters; [local cleanup](local-worktree-cleanup.md) owns removal decisions, commands, blockers, and recovery. `AGENTS.md`, the delivery skill, and OpenSpec context are concise entry points, not separate copies of these procedures. Detailed checks stay in their owning runbook and tooling.
+
+### Authorization without repeated confirmation
+
+A planning-only request authorizes planning only. Once a concrete plan has been presented, one explicit instruction approving it and requesting implementation satisfies both requirements; no separate messages or special approval phrase are required. Ask only about a genuinely missing scope or authorization decision, not an approval already given. Reconcile approved refinements in the same PR before corresponding implementation edits.
+
+Implementation approval never grants merge permission, foreign-worktree ownership, unrelated user-file deletion, or background cleanup authority. Use the separate [exact-candidate merge procedure](#maintainer-requested-agent-merge) and [cleanup decisions](local-worktree-cleanup.md#cleanup-decisions). A named-export deletion request does not require preservation approval instead.
+
+### Branches and validation
+
+Keep unrelated changes out. Use `type/short-description` branches with `feature`, `fix`, `refactor`, `docs`, `test`, `chore`, or `style`, and `type(scope): subject` commits; mark incompatible changes with `BREAKING CHANGE:`.
+
+Before pushing, run only quick targeted checks of what changed: typecheck, the test files covering the changed code, and strict OpenSpec validation. Do not run preflight, `test:fast`, `test:full`, `test:release`, or directory-wide suites unless reproducing a reported CI failure or explicitly requested by the maintainer. Preflight is diagnostic, not CI authority. Draft PRs run no Development test suites; ready finalized candidates receive the selected exact-head validation. Use [complete-regression ordering](#complete-regression-evidence-ordering) for trusted failed-Full repairs, not broader local test runs.
 
-External agents use ordinary Git worktrees without an A1 installation, runtime, or session link. Follow the [development worktree protocol](architecture/project-structure.md#development-worktrees): keep primary on `develop`, run the cleanup sweep, inspect Git inventory, and verify the exact task root, common repository, branch, and state before edits. A fresh worktree created by the session establishes its provenance. An existing delivery needs continuing ownership or explicit handoff plus the exact branch, change, and PR; inventory and a clean checkout alone grant nothing.
+After a push, do not watch CI in the foreground. Read and report its current result before unrelated work; do not poll for completion. Repair routine failed checks in the same branch/PR without weakening behavior, assertions, coverage, or required checks. Ask for approval only when a repair adds substantive scope. A changed candidate or target requires renewed applicable validation.
 
-Use A1 inventory/linking only inside an active A1 shell-tool session, and Claude Code's established worktree hooks in that environment. Missing A1 integration alone does not block an external agent. A known live owner, Git lock, conflicting cleanup owner, or unverifiable handoff still blocks reuse. Claim any released cleanup registration through the [cleanup ownership protocol](local-worktree-cleanup.md#resume-or-recover-ownership) before editing. Neither a runtime link nor a cleanup claim proves the absence of arbitrary external editors; coordination remains cooperative.
+### Generated proposals
+
+Nightly regression repairs and Pi upgrades are ordinary implementation-bound changes. Continue the generated branch and PR. Check each generated Implementation outcome when its work is complete, including an outcome needing no code change; do not rewrite the generated items. Keep detailed report evidence in its existing comments/design; do not add commits solely to insert a final CI run ID or body edits solely to record lifecycle phase. Draft implementation runs no Development suites.
+
+Failed-Full repair selection follows the immutable provenance checks in [complete-regression ordering](#complete-regression-evidence-ordering); labels or naming never select it. Regression repair templates retain two implementation outcomes, one acceptance outcome, and triage metadata under Automation. Pi-upgrade proposals retain four implementation outcomes and one acceptance outcome; their version delta, changelog excerpt, gate verdicts, and review items remain in sync report comments/design. Publishing recovery remains independent of PR validation. The existing post-publication `chore/release-X.Y.Z-dev` reopening exception is limited to `openspec-ci[bot]`, version-only manifests, and a note matching the published Release; it grants no implementation integration authority.
+
+### Handoff and reporting
+
+Provide the absolute worktree, branch/commit, change, PR, behavior, known gaps, applicable run or inspection command, and whether editing ownership is handed over. For interactive checkout tests, build first and use `./scripts/dev` or `./scripts/dev pi`, never a direct Node launcher such as `node scripts/development/dev-launch.mjs`. Follow `AGENTS.md` for pasteable user-command formatting. End runnable implementation reports with `🧪 Manual test:` and the applicable command; a documentation-only change needs inspection, not a product build. Say when nothing is runnable instead of inventing a test.
+
+After exact-head required validation succeeds, park the exact candidate with the primary-checkout `handoff` command, and repeat after a validated repair. It registers/releases cleanup ownership without removing anything. Do not add a lifecycle body edit, rerun successful validation, wait for merge, or start a watcher. Leave integration to a current authorized maintainer decision. CI counts are not progress, and manual validation never blocks truthful task completion or readiness.
+
+## Worktree context across agent environments
 
-Repeat context and ownership verification on resume or stream changes, preserve the delivery's branch/history/PR, and keep every command explicitly scoped to its worktree. Handoffs name the absolute worktree path, branch, change, PR, and whether editing ownership is being handed over. An editing handoff does not register, release, or authorize cleanup and grants no integration authority. The lifecycle below applies equally to all agent environments.
+Follow the [development worktree protocol](architecture/project-structure.md#development-worktrees) before creating, resuming, or switching checkouts. It defines the common Git path and conditional A1/Claude Code adapters; external agents need no A1 installation or runtime link. Editing handoff, runtime association, cleanup ownership, and integration authority remain distinct.
 
 ## Version-3 lifecycle
 

package/docs/worktree-link-recovery.md

@@ -8,9 +8,9 @@ Updated A1 holds a `proper-lockfile` gate, the `mutation.authority.gate` lock di
 
 The next mutation safely recovers abandoned owner/pending metadata after taking the gate. Empty, truncated, NUL-filled, or otherwise malformed metadata does not prevent this recovery. One bounded `recovery.json` records the recovery reason/time, not the original bytes or session contents. A live gate holder remains protected. Acquisition waits at most two seconds by default and honors cancellation.
 
-If startup registration fails temporarily, the running session retries on its 30-second refresh interval. Slow attempts are coalesced rather than queued indefinitely. Once registration succeeds, retry the explicit worktree link in the same session. Switching an agent's session replaces its publication identity, and disposal drains publication before releasing claims.
+Worktree commands own bounded retries; agents do not implement a recovery preflight or confirm success through a second inventory command. If startup registration fails temporarily, the running session retries on its one-second recovery interval. Healthy registrations and claims are not rewritten by background polls. Slow recovery attempts are coalesced rather than queued indefinitely. Switching an agent's session replaces its publication identity, and disposal drains publication before releasing claims.
 
-Inventory remains read-only. It can conservatively show unverifiable status until a mutation has recovered abandoned state; inventory does not perform repair.
+Inventory reads editing claims under a bounded consistent snapshot and does not repair or acquire them. Ordinary global coordination contention produces internal waiting or an operation-level contention diagnostic, never a blanket unverifiable-ownership result for every worktree.
 
 ## Older lock files and mixed versions
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timurproko/a1",
-  "version": "0.2.7-dev.1276",
+  "version": "0.2.7-dev.1286",
   "description": "Standalone single-agent terminal UI on pinned Pi",
   "type": "module",
   "privateLaunchContract": "neutral-launch-v1",
@@ -69,8 +69,8 @@
     "typecheck:bin": "tsgo -p tsconfig.bin.json"
   },
   "dependencies": {
-    "@earendil-works/pi-coding-agent": "1.5.1",
-    "@earendil-works/pi-tui": "1.5.1",
+    "@earendil-works/pi-coding-agent": "1.5.2",
+    "@earendil-works/pi-tui": "1.5.2",
     "@silvia-odwyer/photon-node": "0.3.4",
     "chalk": "5.6.2",
     "cross-spawn": "7.0.6",
@@ -113,7 +113,7 @@
     "@mariozechner/clipboard": "^0.3.9"
   },
   "publication": {
-    "source": "3d3c76792f41343dee7f72854c2b60c3edd4a155",
-    "pullRequest": 903
+    "source": "81969ce6924469b3081347067fd0d0190359b132",
+    "pullRequest": 913
   }
 }