@hcflabs/pi-herdr-tools 0.0.0-stage → 1.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,22 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Henry Wang
4
+ Copyright (c) 2026 hcflabs
5
+
6
+ Permission is hereby granted, free of charge, to any person obtaining a copy
7
+ of this software and associated documentation files (the "Software"), to deal
8
+ in the Software without restriction, including without limitation the rights
9
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
10
+ copies of the Software, and to permit persons to whom the Software is
11
+ furnished to do so, subject to the following conditions:
12
+
13
+ The above copyright notice and this permission notice shall be included in all
14
+ copies or substantial portions of the Software.
15
+
16
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
22
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,168 @@
1
- # Temporary Holding Version
1
+ # `@hcflabs/pi-herdr-tools`
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Clone conversations, hand off tasks, and ask side questions in Herdr. Name conversations, see where idle conversations stopped, and finish worktrees with explicit safety checks.
4
+
5
+ ## Install
6
+
7
+ ```sh
8
+ pi install npm:@hcflabs/pi-task-models
9
+ pi install npm:@hcflabs/pi-herdr-tools
10
+ ```
11
+
12
+ Use Herdr 0.9.3 or later in a Herdr-managed Pi pane. Outside Herdr, rename still sets the Pi session title.
13
+
14
+ Configure `fast` in `/task-models`.
15
+
16
+ ## Works with
17
+
18
+ | Package | Relationship | Purpose |
19
+ | --- | --- | --- |
20
+ | [`@hcflabs/pi-herdr`](https://github.com/hcflabs/pi-harness/tree/main/packages/pi-herdr) | Required | Herdr CLI access. |
21
+ | [`@hcflabs/pi-memory`](https://github.com/hcflabs/pi-harness/tree/main/extensions/pi-memory) | Improves | Keeps Main-only memory and dream advice out of side threads. |
22
+ | [`@hcflabs/pi-task-models`](https://github.com/hcflabs/pi-harness/tree/main/extensions/pi-task-models) | Required | Model profiles for titles, idle recaps, and side threads. |
23
+
24
+ ## Use
25
+
26
+ Run `/clone-tab`; the original session stays active. Commands and prompts are for humans; tools are for agents.
27
+
28
+ | Surface | Type | Purpose |
29
+ | --- | --- | --- |
30
+ | `/clone-tab` | command | Clone into a new tab in the current workspace. |
31
+ | `/clone-worktree` | command | Clone into a new Git worktree workspace. |
32
+ | `/handoff-worktree <issue>` | prompt | Prepare a task for `herdr_handoff`. |
33
+ | `herdr_handoff` | tool | Start a separate task from local `main`, without changing focus. |
34
+ | `/done [-f]` | command | Remove the worktree and close its workspace tabs. `--force` aliases `-f`. |
35
+ | `/btw [<question...>]` | command | Open a side pane with an optional editable draft. |
36
+ | `/btw ask <question...>` | command | Ask a question starting with a subcommand name. |
37
+ | `/btw config [option value]` | command | Show values or `reset` defaults. Set `auto-submit` to `on`/`off`, `tools` to `inherit`/`all`/`read-only`/`none`, or `split` to `right`/`down`. |
38
+ | `/btw merge [<prompt...>]` | command | Queue a merge request. Without a prompt, open the editor. In Main, check pending deliveries. |
39
+ | `/btw help` | command | Show command grammar. |
40
+ | BTW capability widget | ui | Show `tool-free`, `read-only`, `tool-enabled`, or context-load errors with recovery steps. |
41
+ | `/rename` | command | Generate a title from up to five recent user messages. |
42
+ | Rename progress and result widgets | ui | Show `renaming...`, then `renamed to <title>` for two seconds on success. |
43
+ | First real user prompt | ui | Start titles in new, untitled conversations. |
44
+ | `pi-herdr-rename/rename` | model task | Title model profile. |
45
+ | Idle recap widget | ui | Show the goal, current state, and next action after four idle minutes. |
46
+ | `pi-herdr-tools/recap` | model task | Idle recap model profile. |
47
+ | `pi-herdr-btw/btw` | model task | Side-thread model profile. |
48
+ | Dialog blocked status | ui | Show `Input required` in Herdr during interactive TUI dialogs. |
49
+
50
+ ### Clones
51
+
52
+ Both commands require `HERDR_ENV=1` and `HERDR_PANE_ID`. Pane, session-path, and leaf validation precedes target creation. Clones contain the root-to-current-leaf path, excluding sibling branches and still-streaming assistant output. Unsaved sessions use live state.
53
+
54
+ ![Clone launch and recovery boundaries.](./docs/clone-flow.svg)
55
+
56
+ Clone tabs keep the current working directory. Worktree clones use the new checkout. Pi starts with `--session <absolute-clone-file>`; only successful launches change focus.
57
+
58
+ Worktree creation uses `herdr worktree create --workspace <current-workspace> --no-focus`, or the repository's parent workspace when already in a linked worktree. Herdr creates missing branches from `HEAD`, with checkouts under `worktrees.directory` in grouped workspaces. Clones and handoffs use an extra unfocused tab if a layout plugin such as `herdr-plus` occupies the root pane.
59
+
60
+ ### Worktree handoff
61
+
62
+ Run `/handoff-worktree Fix the flaky login test`. The agent collects missing facts, asking one question only for an unclear repository, outcome, or critical constraint. It sends a self-contained prompt, not the conversation, and reports without waiting for completion.
63
+
64
+ The tool registers only with `HERDR_ENV=1`. It also requires `HERDR_PANE_ID` and local `main`. A handoff has no checked integration: the new agent works without supervision. Delegated subagents cannot use the tool.
65
+
66
+ The tool selects the repository in one of two ways:
67
+
68
+ - Without `repo`, the current directory and the pane workspace must be in the same Git repository.
69
+ - With `repo`, the tool uses that child repository of the Pi working directory. Use it when Pi runs in a parent directory that holds many repositories. The current workspace does not need a Git checkout.
70
+
71
+ The tool never selects a child repository automatically. All parameters must be non-empty strings:
72
+
73
+ | Parameter | Requirement |
74
+ | --- | --- |
75
+ | `branch` | New branch; must not exist. |
76
+ | `label` | Workspace label. |
77
+ | `agentName` | Unique agent name matching `^[a-z][a-z0-9_-]{0,31}$`. |
78
+ | `prompt` | Self-contained task prompt. |
79
+ | `repo` | Optional. A Git top-level directory, relative to the Pi working directory. It must not contain `..` or resolve outside that directory. A subdirectory of a repository fails. |
80
+
81
+ After validation, the tool runs `herdr worktree create --workspace <parent> --branch <branch> --base main --label <label> --no-focus`. With `repo`, it uses `--cwd <repository>` instead of `--workspace <parent>`. Herdr then opens the primary workspace of the repository, or creates it, and does not close it later. It starts Pi without session arguments. It submits `herdr agent prompt <agentName> <prompt> --wait --until working --timeout 30000`, with the prompt as one argument, not a shell command or file. The result includes workspace ID, tab, pane, branch, checkout path, agent name, and `repo` when set.
82
+
83
+ ### Side questions
84
+
85
+ With a conversation open, run `/btw Why is this test failing?`, then submit the draft. Exact first words `ask`, `config`, `merge`, and `help` select subcommands; other input is a question.
86
+
87
+ The side-thread model receives Main's fixed, compaction-aware context snapshot. Enabled tools can change shared files. Select `read-only` or `none` to prevent changes. Shorten Main's context if it exceeds the side-thread context limit.
88
+
89
+ ![Side-thread merge delivery.](./docs/btw-merge-sequence.svg)
90
+
91
+ Run `/btw merge Apply the smallest safe fix` after the answer. The merge request contains user and assistant text, without tool payloads. Pending delivery survives shutdown until consumption or 24-hour stale cleanup. Once idle and authenticated, Main appends the transcript without starting a turn, then submits the prompt.
92
+
93
+ ### Titles
94
+
95
+ Automatic titles ignore extension-injected, empty, and image-only prompts. Expanded skill and prompt-template text starts background generation without delaying the reply. English, sentence-case display titles usually have two or three words; limits are four words and 20 characters.
96
+
97
+ Herdr updates the pane and sole-pane tab. Linked worktrees get semantic branches only for detached checkouts or generated `worktree/...` branches; other branches remain unchanged. For example, `Update task logic` gives `refactor/update-task-logic`. Generated worktree labels change automatically; manual `/rename` can replace custom workspace names.
98
+
99
+ ### Idle recaps
100
+
101
+ When an agent run settles, a four-minute idle timer starts. Then the recap model reads the user and assistant text and the newest compaction or branch summary of the current branch, without tool payloads. The recap request has a limit of 48 KiB, so Pi keeps the start of the summary and the newest turns. It writes an idle recap of at most 40 words. The widget above the editor shows `↺ Recap: <text>`. The recap does not go into the model context.
102
+
103
+ Idle recaps require an interactive UI. Pi does not start the timer when the editor has text. In the TUI, a key press stops the timer and cancels a recap request. Submitted input, `!` shell commands, a new agent run, tree navigation, `/reload`, session switch, and exit also remove the widget. Without new entries on the branch since the last recap, Pi does not make a new recap.
104
+
105
+ ### Dialog status
106
+
107
+ Status requires Herdr's installed Pi integration, `~/.pi/agent/extensions/herdr-agent-state.ts`. Select, confirm, input, editor, and custom dialogs from any package count; RPC, JSON, and print modes do not. No dialog title or content goes to Herdr.
108
+
109
+ Status clears on answer, cancellation, failure, `/reload`, session switch, or exit. Reload can hide dialogs; late events cannot restore status. Nested dialogs count as one block. Other status owners, including `@hcflabs/pi-ask-question`, remain independent.
110
+
111
+ ## Flow
112
+
113
+ ### Worktree completion
114
+
115
+ ![Worktree removal and primary-checkout update.](./docs/done-flow.svg)
116
+
117
+ `/done` requires `HERDR_ENV=1`, `HERDR_WORKSPACE_ID`, and `HERDR_TAB_ID`. Commit or discard changes, then confirm removal; declining changes nothing. Normal and forced completion wait for idle Pi.
118
+
119
+ Normal removal rejects dirty worktrees and checkout use by other workspaces. Close listed tabs and retry; labels identify them, or IDs without labels. Primary-checkout tabs do not block removal or updates.
120
+
121
+ **`/done -f` skips confirmation and cross-workspace checks. It passes `--force` to Git, can permanently delete uncommitted work, and can leave other workspaces' tabs pointing at a removed checkout.**
122
+
123
+ Cleanup runs `git worktree remove <checkout>`, closes other tabs in the current workspace, then updates a non-bare primary checkout with `git pull --ff-only`. The current tab closes last, even if the update fails. Tabs in other workspaces do not close.
124
+
125
+ ## Config
126
+
127
+ Package-owned: `~/.pi/agent/config/pi-herdr-btw/config.json`
128
+
129
+ | Name | Description | Values | Default |
130
+ | --- | --- | --- | --- |
131
+ | `autoSubmit` | Submit the draft automatically; otherwise, keep it editable. | Boolean. | `false` |
132
+ | `tools` | Tools available in the side pane. | `inherit` (Main's active tools), `all`, `read-only` (built-in read-only tools), or `none`. | `inherit` |
133
+ | `split` | Side-pane placement. | `right` or `down`. | `right` |
134
+
135
+ File and fields are optional. Launch reports unknown keys and invalid values, using field defaults; malformed files use all defaults. `/btw` continues without changing the file. `/btw config show` prints effective values. Updates fail until you correct issues or run `/btw config reset`. Reset reports issues, then replaces the file with defaults.
136
+
137
+ ### Model profiles
138
+
139
+ See [`@hcflabs/pi-task-models`](https://github.com/hcflabs/pi-harness/tree/main/extensions/pi-task-models) for profile defaults, assignments, and config errors.
140
+
141
+ Side threads select the first authenticated viable route before launch. Titles use the primary route, then fallback, with configured thinking; they never substitute the current session model. An invalid title gets one repair request before fallback. Without a viable route, titles remain unchanged. Idle recaps use the same route order and never substitute the current session model.
142
+
143
+ ## State and storage
144
+
145
+ Clones are separate session files in the Pi-selected session directory. Each contains only the active path. Pi names the clone file for a saved source session; otherwise, the extension creates and names it. Saved `pi-herdr-rename/title` entries restore display titles and semantic branches without another model request. Older titles get no migration.
146
+
147
+ ## Limits and recovery
148
+
149
+ | Failure | Recovery |
150
+ | --- | --- |
151
+ | Definite clone-tab creation failure | The clone file is removed. Cleanup errors name any remaining file. |
152
+ | Worktree creation or pre-launch extra-tab failure | No clone session exists yet. |
153
+ | Killed or incomplete worktree creation | Partial workspace state can remain. Inspect returned IDs with `herdr workspace list`. |
154
+ | Incomplete tab response | Inspect known IDs before cleanup. Clone tabs retain the session path; worktree clones retain the worktree without a clone session. |
155
+ | Agent start requested | An ambiguous launch retains targets and session files. Inspect reported IDs. |
156
+ | Clone focus failure | Pi already started. Focus its tab manually. |
157
+ | Handoff validation failure | No worktree exists. Correct the reported requirement. |
158
+ | Handoff cancellation | Before creation, nothing remains. After creation, reported resources remain; later launch or delivery steps stop. |
159
+ | Handoff start or prompt failure | Resources remain. Errors identify worktree, branch, workspace, tab, pane, and agent. No automatic cleanup occurs. |
160
+ | `agent_blocked` or `agent_prompt_stalled` | Prompt delivery failed. Inspect the agent before retrying. |
161
+
162
+ Timed-out prompts can still arrive. Check `herdr agent get` and `herdr agent read`; resend with `herdr agent prompt` only if absent. Alternatively, run `/done` in the new worktree. Remove personal `handoff-worktree.md` copies to resolve package-prompt name collisions.
163
+
164
+ After a failed primary update, the removed worktree stays removed. Correct primary-checkout changes or divergence, then run `git -C <primary-checkout> pull --ff-only`.
165
+
166
+ `/rename` warns without user text. For Herdr or Git synchronization warnings, correct the problem and retry `/rename`. Newer renames silently cancel older requests.
167
+
168
+ When an idle recap request fails, Pi shows a warning and does not retry. Pi shows each different warning only one time. The next settled run starts a new idle timer.
@@ -0,0 +1,156 @@
1
+ <!DOCTYPE html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="UTF-8">
5
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
6
+ <title>From /btw side question to Main</title>
7
+ <link href="https://fonts.googleapis.com/css2?family=Instrument+Serif:ital@0;1&amp;family=Geist:wght@400;500;600&amp;family=Geist+Mono:wght@400;500;600&amp;display=swap" rel="stylesheet">
8
+ <style>
9
+ *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
10
+ body { min-height: 100vh; display: grid; place-items: center; background: #f0eee9; }
11
+ figure { width: min(1280px, 100%); }
12
+ svg { display: block; width: 100%; height: auto; }
13
+ </style>
14
+ </head>
15
+ <body>
16
+ <figure>
17
+ <svg width="1280" height="720" viewBox="0 0 1280 720" xmlns="http://www.w3.org/2000/svg" role="img" aria-labelledby="btw-merge-sequence-title btw-merge-sequence-desc">
18
+ <title id="btw-merge-sequence-title">From /btw side question to Main</title>
19
+ <desc id="btw-merge-sequence-desc">Sequence diagram showing Main launching an editable Herdr side thread from a static context snapshot while shared working-directory effects remain live. The side pane runs /btw merge with its text transcript and next prompt, which immediately establishes pending delivery. Herdr then refocuses Main and closes the side pane. The pending delivery survives side-pane shutdown and waits for Main to become idle with current model authentication before appending the transcript without starting a turn and submitting the next prompt.</desc>
20
+ <defs>
21
+ <style>
22
+ @import url('https://fonts.googleapis.com/css2?family=Instrument+Serif:ital@0;1&amp;family=Geist:wght@400;500;600&amp;family=Geist+Mono:wght@400;500;600&amp;display=swap');
23
+ .eyebrow { fill: #4c5665; font: 500 10px 'Geist Mono', monospace; letter-spacing: .18em; }
24
+ .diagram-title { fill: #101828; font: 400 28px 'Instrument Serif', serif; }
25
+ .diagram-subtitle { fill: #4c5665; font: 400 14px 'Geist', sans-serif; }
26
+ .lifeline { stroke: rgba(16,24,40,.22); stroke-width: 1; stroke-dasharray: 4 4; }
27
+ .activation { fill: rgba(16,24,40,.06); stroke: #4c5665; stroke-width: .8; }
28
+ .message { fill: none; stroke: #4c5665; stroke-width: 1.2; marker-end: url(#btw-arrow); }
29
+ .message-live { fill: none; stroke: #4c5665; stroke-width: 1.2; stroke-dasharray: 4 4; marker-end: url(#btw-arrow-open); }
30
+ .message-focal { fill: none; stroke: #1d4ed8; stroke-width: 1.4; marker-end: url(#btw-arrow-accent); }
31
+ .label-mask { fill: #f0eee9; }
32
+ .label { fill: #4c5665; font: 500 10px 'Geist Mono', monospace; letter-spacing: .06em; text-anchor: middle; }
33
+ .label-focal { fill: #1d4ed8; font: 500 10px 'Geist Mono', monospace; letter-spacing: .06em; text-anchor: middle; }
34
+ .note { fill: #4c5665; font: 400 14px 'Geist', sans-serif; }
35
+ .actor { fill: #fff; stroke: #101828; stroke-width: 1; }
36
+ .actor-tag { fill: none; stroke: rgba(16,24,40,.32); stroke-width: .8; }
37
+ .tag { fill: #4c5665; font: 500 10px 'Geist Mono', monospace; letter-spacing: .08em; text-anchor: middle; }
38
+ .name { fill: #101828; font: 600 14px 'Geist', sans-serif; text-anchor: middle; }
39
+ .sub { fill: #4c5665; font: 400 10px 'Geist Mono', monospace; text-anchor: middle; }
40
+ .pending { fill: #e5e3df; stroke: #4c5665; stroke-width: 1; }
41
+ .legend { fill: #4c5665; font: 400 10px 'Geist', sans-serif; }
42
+ </style>
43
+ <marker id="btw-arrow" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto">
44
+ <polygon points="0 0,8 3,0 6" fill="#4c5665"/>
45
+ </marker>
46
+ <marker id="btw-arrow-accent" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto">
47
+ <polygon points="0 0,8 3,0 6" fill="#1d4ed8"/>
48
+ </marker>
49
+ <marker id="btw-arrow-link" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto">
50
+ <polygon points="0 0,8 3,0 6" fill="#1d4ed8"/>
51
+ </marker>
52
+ <marker id="btw-arrow-open" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto">
53
+ <polyline points="0 0,8 3,0 6" fill="none" stroke="#4c5665" stroke-width="1.2"/>
54
+ </marker>
55
+ </defs>
56
+
57
+ <rect width="1280" height="720" fill="#f0eee9"/>
58
+
59
+ <text class="eyebrow" x="48" y="24">SEQUENCE · BTW MERGE DELIVERY</text>
60
+ <text class="diagram-title" x="48" y="56">From /btw side question to Main</text>
61
+ <text class="diagram-subtitle" x="48" y="80">The conversation snapshot stays fixed. File changes in the shared working directory do not.</text>
62
+
63
+ <!-- Lifelines -->
64
+ <line class="lifeline" x1="184" y1="164" x2="184" y2="684"/>
65
+ <line class="lifeline" x1="640" y1="164" x2="640" y2="684"/>
66
+ <line class="lifeline" x1="1096" y1="164" x2="1096" y2="684"/>
67
+
68
+ <!-- Activations -->
69
+ <rect class="activation" x="180" y="176" width="8" height="108"/>
70
+ <rect class="activation" x="636" y="264" width="8" height="396"/>
71
+ <rect class="activation" x="1092" y="312" width="8" height="272"/>
72
+ <rect class="activation" x="180" y="652" width="8" height="32"/>
73
+
74
+ <!-- Messages -->
75
+ <path class="message" d="M188 184 H240 Q248 184 248 192 V212 Q248 220 240 220 H188"/>
76
+ <line class="message" x1="188" y1="276" x2="636" y2="276"/>
77
+ <line class="message" x1="644" y1="320" x2="1092" y2="320"/>
78
+ <path class="message" d="M1100 348 H1152 Q1160 348 1160 356 V372 Q1160 380 1152 380 H1100"/>
79
+ <line class="message-live" x1="1092" y1="400" x2="188" y2="400"/>
80
+ <line class="message" x1="1092" y1="456" x2="644" y2="456"/>
81
+ <line class="message" x1="636" y1="540" x2="188" y2="540"/>
82
+ <line class="message" x1="644" y1="576" x2="1092" y2="576"/>
83
+ <line class="message-focal" x1="636" y1="660" x2="188" y2="660"/>
84
+ <path class="message" d="M188 676 H240 Q248 676 248 680 Q248 684 240 684 H188"/>
85
+
86
+ <!-- Message labels -->
87
+ <rect class="label-mask" x="264" y="172" width="264" height="84" rx="4"/>
88
+ <text class="label" x="280" y="188" style="text-anchor:start">PREPARE</text>
89
+ <text class="note" x="272" y="208">Snapshot compaction-aware context</text>
90
+ <text class="note" x="272" y="228">Capture cwd and active tools</text>
91
+ <text class="note" x="272" y="248">Resolve an authenticated route</text>
92
+
93
+ <rect class="label-mask" x="344" y="260" width="136" height="20" rx="2"/>
94
+ <text class="label" x="412" y="274">STATIC CONTEXT</text>
95
+ <rect class="label-mask" x="800" y="304" width="136" height="20" rx="2"/>
96
+ <text class="label" x="868" y="318">OPEN SIDE PANE</text>
97
+ <rect class="label-mask" x="1156" y="332" width="104" height="20" rx="2"/>
98
+ <text class="label" x="1208" y="346">SIDE ANSWER</text>
99
+ <rect class="label-mask" x="808" y="384" width="120" height="20" rx="2"/>
100
+ <text class="label" x="868" y="398">SHARED CWD</text>
101
+ <text class="note" x="868" y="428" text-anchor="middle">Tool writes are immediately visible to Main</text>
102
+ <rect class="label-mask" x="816" y="440" width="104" height="20" rx="2"/>
103
+ <text class="label" x="868" y="454">/BTW MERGE</text>
104
+ <text class="note" x="904" y="480" text-anchor="middle">Text transcript + next prompt</text>
105
+ <rect class="label-mask" x="352" y="524" width="120" height="20" rx="2"/>
106
+ <text class="label" x="412" y="538">REFOCUS MAIN</text>
107
+ <rect class="label-mask" x="816" y="560" width="104" height="20" rx="2"/>
108
+ <text class="label" x="868" y="574">CLOSE PANE</text>
109
+ <rect class="label-mask" x="336" y="648" width="152" height="20" rx="2"/>
110
+ <text class="label-focal" x="412" y="662">APPEND WITHOUT TURN</text>
111
+ <rect class="label-mask" x="264" y="668" width="128" height="20" rx="2"/>
112
+ <text class="label" x="328" y="682">SUBMIT PROMPT</text>
113
+
114
+ <!-- Durable state and actors -->
115
+ <rect class="pending" x="496" y="468" width="288" height="56" rx="6"/>
116
+ <text class="name" x="640" y="488">Pending delivery established</text>
117
+ <text class="sub" x="640" y="508">DURABLE BEFORE REFOCUS / CLOSE</text>
118
+
119
+ <rect class="pending" x="496" y="584" width="288" height="60" rx="6"/>
120
+ <text class="name" x="640" y="608">Pending delivery waits</text>
121
+ <text class="sub" x="640" y="624">MAIN IDLE + AUTH</text>
122
+ <text class="sub" x="640" y="640">SURVIVES SIDE-PANE SHUTDOWN</text>
123
+
124
+ <rect class="actor" x="64" y="96" width="240" height="68" rx="6"/>
125
+ <rect class="actor-tag" x="72" y="104" width="40" height="16" rx="2"/>
126
+ <text class="tag" x="92" y="116">MAIN</text>
127
+ <text class="name" x="184" y="140">Main</text>
128
+ <text class="sub" x="184" y="156">USER RUNS /BTW</text>
129
+
130
+ <rect class="actor" x="520" y="96" width="240" height="68" rx="6"/>
131
+ <rect class="actor-tag" x="528" y="104" width="56" height="16" rx="2"/>
132
+ <text class="tag" x="556" y="116">HERDR</text>
133
+ <text class="name" x="640" y="140">Herdr / BTW transport</text>
134
+ <text class="sub" x="640" y="156">DURABLE HANDOFF</text>
135
+
136
+ <rect class="actor" x="976" y="96" width="240" height="68" rx="6"/>
137
+ <rect class="actor-tag" x="984" y="104" width="40" height="16" rx="2"/>
138
+ <text class="tag" x="1004" y="116">SIDE</text>
139
+ <text class="name" x="1096" y="140">Side Pane</text>
140
+ <text class="sub" x="1096" y="156">EDITABLE DRAFT</text>
141
+
142
+ <!-- Legend -->
143
+ <line x1="48" y1="692" x2="1232" y2="692" stroke="rgba(16,24,40,.141)" stroke-width=".8"/>
144
+ <text class="eyebrow" x="48" y="712">LEGEND</text>
145
+ <rect class="activation" x="132" y="700" width="8" height="16"/>
146
+ <text class="legend" x="152" y="712">Active</text>
147
+ <line class="message-live" x1="248" y1="708" x2="288" y2="708"/>
148
+ <text class="legend" x="300" y="712">Live cwd effect</text>
149
+ <rect class="pending" x="444" y="700" width="24" height="16" rx="4"/>
150
+ <text class="legend" x="480" y="712">Durable pending</text>
151
+ <line class="message-focal" x1="640" y1="708" x2="680" y2="708"/>
152
+ <text class="legend" x="692" y="712">Merge delivery</text>
153
+ </svg>
154
+ </figure>
155
+ </body>
156
+ </html>
@@ -0,0 +1,138 @@
1
+ <?xml version="1.0" encoding="UTF-8"?>
2
+ <svg width="1280" height="720" viewBox="0 0 1280 720" xmlns="http://www.w3.org/2000/svg" role="img" aria-labelledby="btw-merge-sequence-title btw-merge-sequence-desc">
3
+ <title id="btw-merge-sequence-title">From /btw side question to Main</title>
4
+ <desc id="btw-merge-sequence-desc">Sequence diagram showing Main launching an editable Herdr side thread from a static context snapshot while shared working-directory effects remain live. The side pane runs /btw merge with its text transcript and next prompt, which immediately establishes pending delivery. Herdr then refocuses Main and closes the side pane. The pending delivery survives side-pane shutdown and waits for Main to become idle with current model authentication before appending the transcript without starting a turn and submitting the next prompt.</desc>
5
+ <defs>
6
+ <style>
7
+ @import url('https://fonts.googleapis.com/css2?family=Instrument+Serif:ital@0;1&amp;family=Geist:wght@400;500;600&amp;family=Geist+Mono:wght@400;500;600&amp;display=swap');
8
+ .eyebrow { fill: #4c5665; font: 500 10px 'Geist Mono', monospace; letter-spacing: .18em; }
9
+ .diagram-title { fill: #101828; font: 400 28px 'Instrument Serif', serif; }
10
+ .diagram-subtitle { fill: #4c5665; font: 400 14px 'Geist', sans-serif; }
11
+ .lifeline { stroke: rgba(16,24,40,.22); stroke-width: 1; stroke-dasharray: 4 4; }
12
+ .activation { fill: rgba(16,24,40,.06); stroke: #4c5665; stroke-width: .8; }
13
+ .message { fill: none; stroke: #4c5665; stroke-width: 1.2; marker-end: url(#btw-arrow); }
14
+ .message-live { fill: none; stroke: #4c5665; stroke-width: 1.2; stroke-dasharray: 4 4; marker-end: url(#btw-arrow-open); }
15
+ .message-focal { fill: none; stroke: #1d4ed8; stroke-width: 1.4; marker-end: url(#btw-arrow-accent); }
16
+ .label-mask { fill: #f0eee9; }
17
+ .label { fill: #4c5665; font: 500 10px 'Geist Mono', monospace; letter-spacing: .06em; text-anchor: middle; }
18
+ .label-focal { fill: #1d4ed8; font: 500 10px 'Geist Mono', monospace; letter-spacing: .06em; text-anchor: middle; }
19
+ .note { fill: #4c5665; font: 400 14px 'Geist', sans-serif; }
20
+ .actor { fill: #fff; stroke: #101828; stroke-width: 1; }
21
+ .actor-tag { fill: none; stroke: rgba(16,24,40,.32); stroke-width: .8; }
22
+ .tag { fill: #4c5665; font: 500 10px 'Geist Mono', monospace; letter-spacing: .08em; text-anchor: middle; }
23
+ .name { fill: #101828; font: 600 14px 'Geist', sans-serif; text-anchor: middle; }
24
+ .sub { fill: #4c5665; font: 400 10px 'Geist Mono', monospace; text-anchor: middle; }
25
+ .pending { fill: #e5e3df; stroke: #4c5665; stroke-width: 1; }
26
+ .legend { fill: #4c5665; font: 400 10px 'Geist', sans-serif; }
27
+ </style>
28
+ <marker id="btw-arrow" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto">
29
+ <polygon points="0 0,8 3,0 6" fill="#4c5665"/>
30
+ </marker>
31
+ <marker id="btw-arrow-accent" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto">
32
+ <polygon points="0 0,8 3,0 6" fill="#1d4ed8"/>
33
+ </marker>
34
+ <marker id="btw-arrow-link" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto">
35
+ <polygon points="0 0,8 3,0 6" fill="#1d4ed8"/>
36
+ </marker>
37
+ <marker id="btw-arrow-open" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto">
38
+ <polyline points="0 0,8 3,0 6" fill="none" stroke="#4c5665" stroke-width="1.2"/>
39
+ </marker>
40
+ </defs>
41
+
42
+ <rect width="1280" height="720" fill="#f0eee9"/>
43
+
44
+ <text class="eyebrow" x="48" y="24">SEQUENCE · BTW MERGE DELIVERY</text>
45
+ <text class="diagram-title" x="48" y="56">From /btw side question to Main</text>
46
+ <text class="diagram-subtitle" x="48" y="80">The conversation snapshot stays fixed. File changes in the shared working directory do not.</text>
47
+
48
+ <!-- Lifelines -->
49
+ <line class="lifeline" x1="184" y1="164" x2="184" y2="684"/>
50
+ <line class="lifeline" x1="640" y1="164" x2="640" y2="684"/>
51
+ <line class="lifeline" x1="1096" y1="164" x2="1096" y2="684"/>
52
+
53
+ <!-- Activations -->
54
+ <rect class="activation" x="180" y="176" width="8" height="108"/>
55
+ <rect class="activation" x="636" y="264" width="8" height="396"/>
56
+ <rect class="activation" x="1092" y="312" width="8" height="272"/>
57
+ <rect class="activation" x="180" y="652" width="8" height="32"/>
58
+
59
+ <!-- Messages -->
60
+ <path class="message" d="M188 184 H240 Q248 184 248 192 V212 Q248 220 240 220 H188"/>
61
+ <line class="message" x1="188" y1="276" x2="636" y2="276"/>
62
+ <line class="message" x1="644" y1="320" x2="1092" y2="320"/>
63
+ <path class="message" d="M1100 348 H1152 Q1160 348 1160 356 V372 Q1160 380 1152 380 H1100"/>
64
+ <line class="message-live" x1="1092" y1="400" x2="188" y2="400"/>
65
+ <line class="message" x1="1092" y1="456" x2="644" y2="456"/>
66
+ <line class="message" x1="636" y1="540" x2="188" y2="540"/>
67
+ <line class="message" x1="644" y1="576" x2="1092" y2="576"/>
68
+ <line class="message-focal" x1="636" y1="660" x2="188" y2="660"/>
69
+ <path class="message" d="M188 676 H240 Q248 676 248 680 Q248 684 240 684 H188"/>
70
+
71
+ <!-- Message labels -->
72
+ <rect class="label-mask" x="264" y="172" width="264" height="84" rx="4"/>
73
+ <text class="label" x="280" y="188" style="text-anchor:start">PREPARE</text>
74
+ <text class="note" x="272" y="208">Snapshot compaction-aware context</text>
75
+ <text class="note" x="272" y="228">Capture cwd and active tools</text>
76
+ <text class="note" x="272" y="248">Resolve an authenticated route</text>
77
+
78
+ <rect class="label-mask" x="344" y="260" width="136" height="20" rx="2"/>
79
+ <text class="label" x="412" y="274">STATIC CONTEXT</text>
80
+ <rect class="label-mask" x="800" y="304" width="136" height="20" rx="2"/>
81
+ <text class="label" x="868" y="318">OPEN SIDE PANE</text>
82
+ <rect class="label-mask" x="1156" y="332" width="104" height="20" rx="2"/>
83
+ <text class="label" x="1208" y="346">SIDE ANSWER</text>
84
+ <rect class="label-mask" x="808" y="384" width="120" height="20" rx="2"/>
85
+ <text class="label" x="868" y="398">SHARED CWD</text>
86
+ <text class="note" x="868" y="428" text-anchor="middle">Tool writes are immediately visible to Main</text>
87
+ <rect class="label-mask" x="816" y="440" width="104" height="20" rx="2"/>
88
+ <text class="label" x="868" y="454">/BTW MERGE</text>
89
+ <text class="note" x="904" y="480" text-anchor="middle">Text transcript + next prompt</text>
90
+ <rect class="label-mask" x="352" y="524" width="120" height="20" rx="2"/>
91
+ <text class="label" x="412" y="538">REFOCUS MAIN</text>
92
+ <rect class="label-mask" x="816" y="560" width="104" height="20" rx="2"/>
93
+ <text class="label" x="868" y="574">CLOSE PANE</text>
94
+ <rect class="label-mask" x="336" y="648" width="152" height="20" rx="2"/>
95
+ <text class="label-focal" x="412" y="662">APPEND WITHOUT TURN</text>
96
+ <rect class="label-mask" x="264" y="668" width="128" height="20" rx="2"/>
97
+ <text class="label" x="328" y="682">SUBMIT PROMPT</text>
98
+
99
+ <!-- Durable state and actors -->
100
+ <rect class="pending" x="496" y="468" width="288" height="56" rx="6"/>
101
+ <text class="name" x="640" y="488">Pending delivery established</text>
102
+ <text class="sub" x="640" y="508">DURABLE BEFORE REFOCUS / CLOSE</text>
103
+
104
+ <rect class="pending" x="496" y="584" width="288" height="60" rx="6"/>
105
+ <text class="name" x="640" y="608">Pending delivery waits</text>
106
+ <text class="sub" x="640" y="624">MAIN IDLE + AUTH</text>
107
+ <text class="sub" x="640" y="640">SURVIVES SIDE-PANE SHUTDOWN</text>
108
+
109
+ <rect class="actor" x="64" y="96" width="240" height="68" rx="6"/>
110
+ <rect class="actor-tag" x="72" y="104" width="40" height="16" rx="2"/>
111
+ <text class="tag" x="92" y="116">MAIN</text>
112
+ <text class="name" x="184" y="140">Main</text>
113
+ <text class="sub" x="184" y="156">USER RUNS /BTW</text>
114
+
115
+ <rect class="actor" x="520" y="96" width="240" height="68" rx="6"/>
116
+ <rect class="actor-tag" x="528" y="104" width="56" height="16" rx="2"/>
117
+ <text class="tag" x="556" y="116">HERDR</text>
118
+ <text class="name" x="640" y="140">Herdr / BTW transport</text>
119
+ <text class="sub" x="640" y="156">DURABLE HANDOFF</text>
120
+
121
+ <rect class="actor" x="976" y="96" width="240" height="68" rx="6"/>
122
+ <rect class="actor-tag" x="984" y="104" width="40" height="16" rx="2"/>
123
+ <text class="tag" x="1004" y="116">SIDE</text>
124
+ <text class="name" x="1096" y="140">Side Pane</text>
125
+ <text class="sub" x="1096" y="156">EDITABLE DRAFT</text>
126
+
127
+ <!-- Legend -->
128
+ <line x1="48" y1="692" x2="1232" y2="692" stroke="rgba(16,24,40,.141)" stroke-width=".8"/>
129
+ <text class="eyebrow" x="48" y="712">LEGEND</text>
130
+ <rect class="activation" x="132" y="700" width="8" height="16"/>
131
+ <text class="legend" x="152" y="712">Active</text>
132
+ <line class="message-live" x1="248" y1="708" x2="288" y2="708"/>
133
+ <text class="legend" x="300" y="712">Live cwd effect</text>
134
+ <rect class="pending" x="444" y="700" width="24" height="16" rx="4"/>
135
+ <text class="legend" x="480" y="712">Durable pending</text>
136
+ <line class="message-focal" x1="640" y1="708" x2="680" y2="708"/>
137
+ <text class="legend" x="692" y="712">Merge delivery</text>
138
+ </svg>