@boxes-dev/dvb-runtime 1.0.1091 → 1.0.1093

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/dist/bin/dvbd.mjs CHANGED
@@ -1,6 +1,6 @@
1
1
  #!/usr/bin/env node
2
2
 
3
- !function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="47398613-b9bd-5f2b-9588-152eaf724fc6")}catch(e){}}();
3
+ !function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="57feb75d-01ce-5c1b-85e0-5a03f16ca546")}catch(e){}}();
4
4
  import { createRequire as __dvbCreateRequire } from "node:module";
5
5
  import { dirname as __dvbDirname } from "node:path";
6
6
  import { fileURLToPath as __dvbFileURLToPath } from "node:url";
@@ -64675,9 +64675,9 @@ var init_sentry = __esm({
64675
64675
  uncaughtExceptionMonitorInstalled = false;
64676
64676
  currentDevboxSentryUser = null;
64677
64677
  readBuildMetadata = () => {
64678
- const rawPackageVersion = "1.0.1091";
64679
- const rawGitSha = "e27d9d3c12d578e97515be216373f3634d2b454e";
64680
- const rawSentryRelease = "boxes-dev-dvb@1.0.1091+e27d9d3c12d578e97515be216373f3634d2b454e";
64678
+ const rawPackageVersion = "1.0.1093";
64679
+ const rawGitSha = "a3bbdd5feeb2fd4fdf13c3bcd5f52874812c58aa";
64680
+ const rawSentryRelease = "boxes-dev-dvb@1.0.1093+a3bbdd5feeb2fd4fdf13c3bcd5f52874812c58aa";
64681
64681
  const packageVersion = typeof rawPackageVersion === "string" ? rawPackageVersion : void 0;
64682
64682
  const gitSha = typeof rawGitSha === "string" ? rawGitSha : void 0;
64683
64683
  const sentryRelease = typeof rawSentryRelease === "string" ? rawSentryRelease : void 0;
@@ -66894,7 +66894,7 @@ var init_packageVersion = __esm({
66894
66894
  return path8.join(process.cwd(), "dvb");
66895
66895
  };
66896
66896
  readEmbeddedPackageVersion = () => {
66897
- const raw = "1.0.1091";
66897
+ const raw = "1.0.1093";
66898
66898
  return trimVersion(raw);
66899
66899
  };
66900
66900
  readNearestPackageMetadata = (basePath) => {
@@ -80047,4 +80047,4 @@ smol-toml/dist/index.js:
80047
80047
  *)
80048
80048
  */
80049
80049
 
80050
- //# debugId=47398613-b9bd-5f2b-9588-152eaf724fc6
80050
+ //# debugId=57feb75d-01ce-5c1b-85e0-5a03f16ca546
@@ -91,7 +91,12 @@ checkout, choose a paid plan, or add a payment method from billing.
91
91
  ## Paid Plans And Seats
92
92
 
93
93
  Paid plans apply to assigned paid seats. Team admins can assign and remove paid
94
- seats from the billing page.
94
+ seats from Billing on the website. A paid plan keeps at least one paid seat, so
95
+ the last paid seat offers Cancel plan instead of Remove seat. To stop paying, a
96
+ team admin needs to select Cancel plan there or at the bottom of Billing on the
97
+ website. Cancellation takes effect at the end of the billing period, and the
98
+ plan and its seats stay active until then. Keep plan undoes a scheduled
99
+ cancellation.
95
100
 
96
101
  Paid seats receive the plan's included box-hours each billing period. If usage
97
102
  goes beyond the included amount, boxes.dev uses prepaid overage credits when
@@ -115,9 +115,12 @@ the user connects Codex or Claude Code before launch.
115
115
  The agent prepares a manifest with you, checks it, and asks for explicit
116
116
  approval before `dvb agent-init run` uploads files or creates a Template box.
117
117
  The current version-3 manifest also lets the agent design startup and teardown
118
- behavior and, when useful, one Template maintenance script with matching GitHub
119
- watches. Maintenance starts with its repeating schedule off and fresh watch
120
- baselines; setup does not run the script.
118
+ behavior and one Template maintenance script with matching GitHub watches. The
119
+ agent recommends maintenance when dependencies or tooling change over time and
120
+ watches files such as lockfiles rather than application source. Maintenance
121
+ starts with its repeating schedule off and fresh watch baselines. The setup
122
+ agent on the Template box tests the script twice and saves any fixes; setup
123
+ does not start a maintenance run.
121
124
 
122
125
  ## List And Select Machines
123
126
 
@@ -10,13 +10,15 @@ runtime.
10
10
  The workbench has a few persistent areas:
11
11
 
12
12
  - The top bar is split at the left pane's edge. The left pane's own top area
13
- shows the project selector, a back button, and a crosshair button.
14
- The back button retraces earlier workbench
13
+ shows the project selector, paired Back and Forward buttons, and a crosshair
14
+ button. Back and Forward retrace workbench
15
15
  selections, so an integration or automation detour can return to the thread
16
- you were viewing. It is disabled until there is somewhere to return. The
17
- crosshair button scrolls the thread list to the selected thread, first
18
- expanding Devboxes or Project and the Template box row, folder, or devbox that hides
19
- it. It is disabled when no thread is selected and hidden when the left pane
16
+ you were viewing at the reply you were reading. If you were following the
17
+ latest output, you return to the bottom. Each arrow is disabled when there
18
+ is nowhere to go in that direction. The crosshair button scrolls the thread
19
+ list to the selected thread, first expanding Devboxes or Project and the
20
+ Template box row, folder, or devbox that hides it. It is disabled when no
21
+ thread is selected and hidden when the left pane
20
22
  is too narrow to fit it. A thread inside a collapsed automation stays hidden
21
23
  until you expand that automation. The
22
24
  content pane's title bar starts with runtime status, metrics, and ports when
@@ -135,7 +137,14 @@ explanation rather than disappearing.
135
137
  ## Keyboard Shortcuts
136
138
 
137
139
  The workbench has keyboard shortcuts for the most common actions. macOS uses
138
- Cmd; Windows and Linux use the Ctrl-based equivalents shown in parentheses.
140
+ Cmd; Windows and Linux equivalents are shown in parentheses.
141
+
142
+ History:
143
+
144
+ - Back / forward: **Cmd+[** / **Cmd+]** (Alt+Left / Alt+Right)
145
+
146
+ These browser-style history bindings are fixed. While Terminal or Browser has
147
+ focus, Cmd+[ and Cmd+] keep switching that pane's tabs instead.
139
148
 
140
149
  Threads:
141
150
 
@@ -153,6 +162,10 @@ Threads:
153
162
 
154
163
  Panes:
155
164
 
165
+ - Show or hide the left sidebar: **Cmd+B** (Ctrl+Shift+B). Press it again
166
+ to reopen the sidebar, or use the sidebar button beside the project selector.
167
+ The open conversation stays in place, and the project remembers the sidebar's
168
+ visibility and width on this computer.
156
169
  - Toggle the Terminal / Files / Git-Review pane: **Cmd+L** / **Cmd+K** /
157
170
  **Cmd+J** (Ctrl+Shift+L / Ctrl+Shift+K / Ctrl+Shift+J). Pressing the same
158
171
  shortcut again closes the pane and returns focus to the chat. Opening the
@@ -186,16 +199,17 @@ Help:
186
199
 
187
200
  - Show keyboard shortcuts: **Cmd+Shift+/** (Ctrl+Shift+/)
188
201
 
189
- This opens the keyboard shortcuts dialog, which lists every customizable
190
- shortcut with its current binding. **Account menu > Keyboard shortcuts** at
191
- the bottom of the sidebar opens the same dialog. Controls that have a shortcut,
192
- such as the pane toggles in the titlebar, also show their binding in the hover
202
+ This opens the keyboard shortcuts dialog, which lists the fixed history keys
203
+ and every customizable shortcut with its current binding. **Account menu >
204
+ Keyboard shortcuts** at the bottom of the sidebar opens the same dialog.
205
+ Controls that have a shortcut, such as the pane toggles in the titlebar, also
206
+ show their binding in the hover
193
207
  tooltip. The dynamic thread-number shortcuts always follow sidebar order and
194
208
  are not customizable.
195
209
 
196
210
  ### Customizing Shortcuts
197
211
 
198
- Every shortcut listed in the keyboard shortcuts dialog can be rebound. Open it
212
+ Workbench shortcuts with a Rebind control can be changed. Open the dialog
199
213
  (**Cmd+Shift+/**, **Account menu > Keyboard shortcuts**, or **Customize** in
200
214
  the search modal footer), then click Rebind on a shortcut and press the new
201
215
  combo.
@@ -23,6 +23,18 @@ command without repeating an unrecorded workaround.
23
23
  For remote Team Template editing, perform these checks on the target editing
24
24
  box. Success on the source project's Template box does not verify the target.
25
25
 
26
+ For normal setup, configure new devboxes to fetch the latest remote default
27
+ branch, usually `main`, regardless of the Template box's current branch or
28
+ files. Use another saved starting branch when the user requests it. Inheriting
29
+ the Template box's saved checkout should be a deliberate user choice.
30
+
31
+ Read back the project's branch defaults; checking out `main` on the Template
32
+ box alone does not configure them. Follow
33
+ [Project setup](project-setup.md) for the setup
34
+ flow's supported controls and generated Git declaration. Keep dependency,
35
+ environment, and service commands after branch preparation, and remove custom
36
+ commands that switch branches or reset away the selected code.
37
+
26
38
  ## Verify Required Service Startup
27
39
 
28
40
  Check how the required services start through the documented development
@@ -607,28 +607,39 @@ that thread's machine and asks the agent to follow up. The events are:
607
607
  - **Merge conflicts**: the pull request branch conflicts with its base branch.
608
608
 
609
609
  To turn follow-ups on for one pull request, open its actions menu in
610
- Git/Review, choose **Automate follow-ups**, and select the events. The selected
610
+ Git/Review, choose **Automate follow-ups**, and select the events. The project's
611
+ default follow-up events are selected to start. The selected
611
612
  devbox or Template box needs **GitHub CLI access**, and the boxes.dev GitHub
612
613
  App needs access to the repository so GitHub can send the events; personal
613
614
  GitHub CLI access alone cannot provide them. Follow-ups work only for pull
614
615
  requests into the repository's default branch. An agent can also turn them on
615
- itself with `dvb-onbox pr followups enable`; see
616
+ with `dvb-onbox pr followups enable` when you ask, and may offer to after it
617
+ opens a pull request; see
616
618
  [Pull Request Follow-ups](onbox-agent-tools.md#pull-request-follow-ups).
617
619
 
618
620
  To turn them on for new pull requests automatically, open **Project settings**,
619
621
  expand **Git**, and turn on **Automate follow-ups on new pull requests**. It is
620
- off by default. While it is on, boxes.dev turns on all four events when one of
621
- the project's threads opens a pull request, either with **Create PR** in
622
- Git/Review or by an agent running `gh pr create` on one of the project's
623
- devboxes. The thread that opened the pull request handles its follow-ups, and
624
- an agent's `gh pr create` output ends with a line saying they are on. The
625
- setting does not cover pull requests opened any other way, such as on
626
- github.com or with `gh pr create` in your own terminal, or a branch that
627
- already had an open pull request. It acts only when the pull request is
628
- created, so turning a pull request's follow-ups off later stays in effect.
622
+ off by default. While it is on, boxes.dev turns on the project's default
623
+ follow-up events when one of the project's threads opens a pull request, either
624
+ with **Create PR** in Git/Review or by an agent running `gh pr create` on one
625
+ of the project's devboxes. The thread that opened the pull request handles its
626
+ follow-ups, and an agent's `gh pr create` output ends with a line saying they
627
+ are on and naming the events. The setting does not cover pull requests opened
628
+ any other way, such as on github.com or with `gh pr create` in your own
629
+ terminal, or a branch that already had an open pull request. It acts only when
630
+ the pull request is created, so turning a pull request's follow-ups off later
631
+ stays in effect.
632
+
633
+ The project's default follow-up events are all four events unless you change
634
+ them under **Default follow-up events** in the same **Git** settings. They
635
+ apply when follow-ups start for a pull request without anyone choosing events:
636
+ the automatic setting above, and an agent's `dvb-onbox pr followups enable`
637
+ without `--triggers`. Changing them does not change the events of pull requests
638
+ that already have follow-ups.
629
639
 
630
640
  Before acting, the agent fetches the pull request's current state with `gh`. It
631
- may edit the worktree, run tests, commit, and push to the pull request branch.
641
+ may edit the worktree, run tests, commit, and push to the pull request branch
642
+ when your instructions and the repository's rules allow pushing.
632
643
  If a safe fix is not clear, it stops and explains why. When a failing check is
633
644
  something it can't fix, it also turns follow-ups off. When feedback needs no
634
645
  changes, such as an approval, it says so in the thread and leaves follow-ups
@@ -643,12 +654,20 @@ conversation. Approvals without a comment, edits, and deletions do not start a
643
654
  follow-up. Your own reviews and comments never start one, because agents act on
644
655
  GitHub as you; message the agent in its thread instead. The owner, member, and
645
656
  collaborator filter uses the relationship GitHub reports for each author; it
646
- does not check whether the author can write to the repository. boxes.dev waits
647
- until two minutes pass without a new comment, or ten minutes after the first
648
- one, then sends the comments together. If another selected event is ready in
649
- the meantime, its follow-up starts right away and includes the waiting
650
- comments. The agent replies to or resolves review conversations only
651
- when your instructions or the project's agent guidance tell it to.
657
+ does not check whether the author can write to the repository.
658
+
659
+ Bot review feedback includes a bot's reviews, inline review comments, and
660
+ comments in the pull request's conversation, along with edits to them. A bot's
661
+ approval does not start a follow-up, even when it has a comment.
662
+
663
+ Review bots often post a status comment, a review, and inline comments over a
664
+ minute or two, and people often leave several comments in a row. boxes.dev
665
+ waits until three minutes pass without new review feedback from either, or ten
666
+ minutes after the first, then sends it all in one follow-up. If failed checks
667
+ or a merge conflict need a follow-up in the meantime, it starts right away and
668
+ includes the waiting feedback. The agent replies to or resolves review
669
+ conversations only when your instructions or the project's agent guidance tell
670
+ it to.
652
671
 
653
672
  While a Codex agent is working, its follow-up waits for the current turn to
654
673
  finish. Later events join a waiting follow-up that already covers those kinds,
@@ -51,15 +51,18 @@ the prepared devbox; it does not query the remote as the user types. Unlisted
51
51
  names can still be entered and are verified when fetched.
52
52
 
53
53
  boxes.dev fetches the selected remote branches and checks them out before
54
- running startup scripts. It remembers choices on this computer for the signed-in
55
- account after the first message is accepted. Discarding a draft does not change
56
- that preference. Clients without this picker use the project's configured
57
- defaults.
54
+ running startup scripts. For projects with configured branch defaults, an
55
+ accepted first message saves the chosen branches as that owner's project
56
+ defaults. New drafts, other devices, automations, and clients without this
57
+ picker use the same saved defaults. Discarding a draft, reopening an old draft,
58
+ or a failed start does not change them. Existing devboxes keep their checkout.
58
59
 
59
60
  Setup and import show default branches and startup commands as separate settings
60
- under **New devboxes**. Project settings show configured defaults above the
61
- startup script. Existing projects without managed defaults can keep the branch
62
- saved in the Template box snapshot by choosing **From Template box**.
61
+ under **New devboxes**. Edit configured defaults in **Project settings → Devbox
62
+ lifecycle → New devbox defaults**, above the startup script, then choose
63
+ **Save**. Clearing or restoring startup commands keeps the branch defaults.
64
+ Existing projects without configured defaults can keep the branch saved in
65
+ the Template box snapshot by choosing **From Template box**.
63
66
 
64
67
  Projects using the generated Git startup commands retain their existing reset
65
68
  and clean behavior on the new devbox: tracked files match the fetched branch,
@@ -67,6 +70,7 @@ untracked files are removed, and ignored files such as dependencies remain.
67
70
  Existing projects without those generated commands keep their saved checkout
68
71
  until a branch is explicitly selected. An explicit choice in such a project
69
72
  preserves local work and stops for conflicting changes or unpublished commits.
73
+ That choice applies to the current draft without saving a project default.
70
74
  The Template box is unaffected.
71
75
 
72
76
  Changing a choice while composing prepares the latest selection. Before setup
@@ -88,9 +92,10 @@ can be set from 1 to 120 seconds.
88
92
  Startup scripts can install dependencies, configure the environment, or start
89
93
  services after branch preparation. The standard generated fetch/checkout
90
94
  commands are handled by boxes.dev; any extra commands remain startup work.
91
- Remove branch-switching commands from custom scripts when choosing starting branches.
92
- If setup leaves a repository on another branch, boxes.dev reports the conflict
93
- before starting the agent. A successful checkout alone does not mean an app
95
+ Remove commands that switch branches or reset Git history from custom scripts
96
+ when choosing starting branches. If setup leaves a repository on another
97
+ branch, boxes.dev reports the conflict before starting the agent. A successful
98
+ checkout alone does not mean an app
94
99
  is listening or has rebuilt for that branch.
95
100
 
96
101
  When a project has a devbox startup script, boxes.dev may reserve a
@@ -101,6 +101,14 @@ for the project owner to resolve, but does not discard local content.
101
101
 
102
102
  ## Team Template Values
103
103
 
104
+ Project settings and Team Template settings have one environment-variable
105
+ search across all managed files. It matches names, file paths, comments,
106
+ descriptions, and member instructions, never saved values. Required Member
107
+ values appear first, and optional Member values start collapsed under **Show
108
+ optional**. Searching reveals matching optional values automatically. Team
109
+ values and a project's own variables remain visible. Filtering and collapsing
110
+ rows preserve unsaved entries and do not change which variables will be saved.
111
+
104
112
  A team admin can add environment-file defaults to a Team Template. Each row is
105
113
  either:
106
114
 
@@ -115,8 +123,16 @@ Claude session. In a Team Template-managed project, the desktop app warns the
115
123
  member about each missing required value, such as one the team added later,
116
124
  and links to **Project settings**.
117
125
 
126
+ For a Team row, an admin can check **Allow personal override**. In a Team
127
+ Template-managed project, each member can then save a private replacement in
128
+ **Project settings → Environment files**. Without a replacement, the Team value
129
+ is used. **Use team value** removes the member's replacement. Turning the
130
+ checkbox off uses the Team value without deleting saved private replacements;
131
+ turning it back on permits those replacements again. Renaming the variable or
132
+ moving its file still requires the member to approve the new destination.
133
+
118
134
  Project creation groups required values and member files under **Needed to
119
- create the project**. **Optional values** starts collapsed, groups rows by destination
135
+ create the project**. **Show optional** starts collapsed, groups rows by destination
120
136
  file and shows search when there are more than eight optional rows. Search
121
137
  and disclosure changes preserve entered values. Identical names in different
122
138
  files remain separate inputs. Optional values never block creation, but the
@@ -174,8 +174,8 @@ kept in the draft for review. If microphone access was denied, allow it for
174
174
  boxes.dev in your phone's settings and try again. Dictate requires an updated
175
175
  mobile app; an older installed app needs an app-store update.
176
176
 
177
- To find text within the open conversation, choose **… → Find in thread** in the
178
- thread header. **Find in thread** matches literal text, ignoring capitalization
177
+ To find text within the open conversation, choose **… → Find** in the
178
+ thread header. Find matches literal text, ignoring capitalization
179
179
  and Markdown formatting, in your messages and the agent's final replies. Use the
180
180
  arrows to move through occurrences in conversation order, including older
181
181
  messages. For a match in older messages, Find opens that part of the thread
@@ -257,7 +257,7 @@ you type or attach files. Stopping preserves text and attachments that are
257
257
  still drafts in the composer so you can send them as soon as the turn finishes
258
258
  stopping.
259
259
 
260
- Choose **… → Open Terminal** in a session when you need a shell for the
260
+ Choose **… → Terminal** in a thread when you need a shell for the
261
261
  thread's current runtime.
262
262
 
263
263
  Choose **… → Agent permissions** in an open thread to view or change what
@@ -277,9 +277,9 @@ project's shared settings. **Message teammates' agents** is not on the mobile
277
277
  screens yet; change it in the desktop app.
278
278
 
279
279
  Long-press a message to open its bottom menu and choose **Copy** to copy its
280
- text. On an eligible completed Codex or Claude reply, choose **Continue in
281
- current box** or **Continue in new devbox** to fork the conversation through
282
- that reply. The header menu also offers **Continue in new chat** for the
280
+ text. On an eligible completed Codex or Claude reply, choose **Fork in
281
+ current box** or **Fork into new devbox** to fork the conversation through
282
+ that reply. The header menu also offers **Fork thread** for the
283
283
  latest reply. Wait for the agent to finish before forking; until then, the
284
284
  menu shows these choices dimmed and explains why. Unsent text and attachments
285
285
  will stay with the original chat. Choosing a new
@@ -369,7 +369,7 @@ and keyboard visibility.
369
369
 
370
370
  ## Browser
371
371
 
372
- Choose **… → Open Browser** in a thread's header to open Browser on that
372
+ Choose **… → Browser** in a thread's header to open Browser on that
373
373
  thread's devbox or Template box, waking it if it's asleep. It is the same
374
374
  Chromium session as the desktop Browser pane, with the same tabs, signed-in
375
375
  sites, and profile, and agents on the box use it too. If the box's browser
@@ -450,8 +450,9 @@ What these commands change depends on the project:
450
450
  On the Template box they need no extra permission. On a devbox, the current
451
451
  thread needs `edit-project-settings` or `edit-template-box`.
452
452
  - In a Team Template project, they edit the user's own variables: values for
453
- Member rows the team defined, and variables the user added to any file.
454
- Team values belong to the team and cannot be changed here. The current
453
+ Member rows the team defined, personal overrides on Team rows where the admin
454
+ enabled **Allow personal override**, and variables the user added to any file.
455
+ Removing a personal override returns to the Team value. The current
455
456
  thread needs `edit-project-settings`, `edit-personal-environment`, or
456
457
  `edit-team-template` for a team admin.
457
458
 
@@ -682,6 +683,7 @@ Template maintenance uses one script and one complete GitHub watch set:
682
683
  dvb-onbox project maintenance get --json
683
684
  dvb-onbox project maintenance runs --json
684
685
  dvb-onbox project maintenance logs --run <run-id> --json
686
+ dvb-onbox project maintenance run --json
685
687
  dvb-onbox project maintenance apply \
686
688
  --script-file /home/boxes/<file> \
687
689
  --timeout-seconds <1-480> \
@@ -715,6 +717,19 @@ unavailable run IDs return `maintenance_run_not_found`. The existing maintenance
715
717
  permission and Template box or Team Template editing-session requirements also
716
718
  apply to history and logs.
717
719
 
720
+ `run` starts the saved script on the current ordinary Template box, the same
721
+ way as **Run now** in Project settings, and requires **Edit template
722
+ maintenance**. It returns the run's `publicRunId` and a disposition: `create`
723
+ for a new run, `merge` when the request joined a run already waiting to start,
724
+ or `followup` when the run will start after one in progress. A project without
725
+ a saved script returns `maintenance_not_configured`. After the script succeeds,
726
+ boxes.dev saves a snapshot, and agents on the Template box pause briefly while
727
+ it is saved. Follow the run with `runs` until its status is `succeeded`,
728
+ `failed`, or `canceled`, then read `logs`; only `succeeded` means both the
729
+ script and the snapshot finished. Finish a maintenance repair with a successful
730
+ run. In a Team Template editing session, `run` returns `source_box_unavailable`;
731
+ run Team Template maintenance from the desktop app.
732
+
718
733
  The same maintenance commands work in a Team Template's current editing
719
734
  session. They update that Team Template's shared maintenance script and watches
720
735
  and require the editing session's owner to remain a team admin. Use repository
@@ -903,8 +918,9 @@ requests into the repository's default branch. One thread per boxes.dev
903
918
  account handles a pull request's follow-ups at a time.
904
919
 
905
920
  When the project's **Automate follow-ups on new pull requests** Git setting is
906
- on, `gh pr create` turns on all four triggers for the new pull request in the
907
- thread that ran it, and its output ends with a line saying so. A line saying
921
+ on, `gh pr create` turns on the project's default follow-up events for the new
922
+ pull request in the thread that ran it, and its output ends with a line saying
923
+ so and naming the events. A line saying
908
924
  follow-ups only work for pull requests into the default branch means none were
909
925
  turned on, and a line saying boxes.dev couldn't turn them on gives the reason.
910
926
  When gh prints nothing about follow-ups and you need to know whether they are
@@ -925,8 +941,11 @@ repositories and the project has more than one. They always act for the thread
925
941
  that runs them.
926
942
 
927
943
  `--triggers` takes a comma-separated list of `failed-checks`, `bot-reviews`,
928
- `human-reviews`, and `conflicts`. Without it, `enable` turns on all four for a
929
- pull request that has no follow-ups and keeps the current triggers otherwise.
944
+ `human-reviews`, and `conflicts`. Without it, `enable` turns on the project's
945
+ default follow-up events for a pull request that has no follow-ups and keeps
946
+ the current triggers otherwise. The defaults are all four unless the user
947
+ changed them in the project's Git settings; `enable` reports which triggers it
948
+ turned on.
930
949
  `enable` also resumes paused follow-ups that this thread handles.
931
950
 
932
951
  When another thread handles the pull request's follow-ups, `enable` returns
@@ -940,11 +959,11 @@ previous thread still run there.
940
959
  `disable` turns off follow-ups that this thread handles. It can't turn off
941
960
  another thread's follow-ups.
942
961
 
943
- Turn follow-ups on after opening a pull request meant for review, or when you
944
- want to hear about its CI results, unless `gh pr create` reported that they are
945
- already on. Leave them off for throwaway or draft-only experiments unless the
946
- user asks. If you keep getting follow-ups you can't resolve or that aren't
947
- worth acting on, turn them off and tell the user why.
962
+ Run `enable` only when the user has asked for follow-ups. If `gh pr create`
963
+ reported that it turned them on, nothing more is needed. Otherwise, you may
964
+ offer to turn them on after opening a pull request for review. When an
965
+ "Automated PR follow-up" message arrives, handle it as the
966
+ `boxes-pr-followups` skill describes.
948
967
 
949
968
  Errors use these codes: `repo_required`, `no_pull_request`, `pr_closed`,
950
969
  `github_app_required`, `github_cli_unavailable`, `held_by_other_thread`,
@@ -1386,7 +1405,9 @@ Prompt files are limited to 32 KiB.
1386
1405
 
1387
1406
  Delegation does not grant destruction permission or access to unrelated
1388
1407
  threads. To clean up a devbox created this way, see
1389
- [Destroy And Archive Created Devboxes](#destroy-and-archive-created-devboxes). Read-only thread and project discovery has its own permission below.
1408
+ [Destroy And Archive Created Devboxes](#destroy-and-archive-created-devboxes).
1409
+ To archive finished threads started on the current devbox, see
1410
+ [Archive Created Threads On This Devbox](#archive-created-threads-on-this-devbox). Read-only thread and project discovery has its own permission below.
1390
1411
  `dvb-onbox` does not expose arbitrary direct exec, services, or generic machine
1391
1412
  management. The current-box public link commands above are its only port-control
1392
1413
  surface.
@@ -1874,6 +1895,33 @@ request the devbox made for itself. It returns `cancelled`, or `not_pending`
1874
1895
  with a null `requestId` if there is nothing to cancel. Once archival has
1875
1896
  started, it returns `destruction_started`.
1876
1897
 
1898
+ ### Archive Created Threads On This Devbox
1899
+
1900
+ **Destroy and archive created devboxes** also lets any agent on an ordinary
1901
+ devbox archive worker threads created there by agents on that same devbox,
1902
+ such as a worker started with `threads start --target current-devbox`:
1903
+
1904
+ ```bash
1905
+ dvb-onbox threads archive --thread <thread-id> --json
1906
+ ```
1907
+
1908
+ Use the thread ID returned by `threads start` or shown by `threads list`.
1909
+ Archive a thread only after its work is finished and you have collected its
1910
+ result. Any agent on the creating devbox can archive the worker; it doesn't
1911
+ have to be the agent that started it. Archiving keeps the thread's history,
1912
+ and the user can unarchive it in the desktop or mobile app. Repeating the
1913
+ command is safe; `changed` is `false` when the thread was already archived.
1914
+ A Codex thread's saved session on the devbox is updated first; if that fails,
1915
+ the command returns `archive_failed` and the thread stays in the active list.
1916
+
1917
+ The devbox's anchor thread, which is its first thread, returns `anchor_thread`
1918
+ and is archived only when the whole devbox is destroyed and archived.
1919
+ Manually started threads, threads created from another box, and threads on
1920
+ other boxes return `thread_not_found`. Threads that haven't started return
1921
+ `thread_not_ready`, and agents on a Template box get `not_devbox`. After an
1922
+ `archive_disabled` error, request `destroy-created-devboxes`. Permission to
1923
+ destroy this devbox does not grant permission to archive individual workers.
1924
+
1877
1925
  ## Devbox Folders
1878
1926
 
1879
1927
  Project folders group whole ordinary devboxes in the desktop thread list. They
@@ -322,11 +322,20 @@ desktop setup.
322
322
  While reviewing the manifest, the coding agent presents the available instance
323
323
  types and asks the user which one to use. The choice applies to the project's
324
324
  Template box and all of its devboxes and cannot be changed after initialization.
325
- When the repository's `origin` default branch is known, the manifest also
326
- starts with recommended inline shell commands that refresh each new devbox from
327
- that remote branch. Version 3 includes full startup and teardown sections with
328
- independent timeouts. The commands are editable and optional, and a missing
329
- default branch never blocks setup.
325
+ When every selected repository's `origin` default branch is known, the manifest starts
326
+ with generated Git commands that declare the branch to use for new devboxes.
327
+ This also covers repositories in subfolders. If you narrow the repository
328
+ selection, update the generated block's paths to match it.
329
+ boxes.dev recognizes that generated block, saves its branch defaults separately,
330
+ and prepares the checkout before running any remaining startup commands. Normally
331
+ configure the project's starting branch, usually `main`, so new devboxes fetch
332
+ fresh remote code regardless of the Template box's current checkout. Keep the
333
+ generated block intact when adding application setup commands after it. Omit
334
+ it only when the user deliberately wants the Template box's saved checkout;
335
+ without it, an explicit thread branch choice is needed to prepare remote code.
336
+ Version 3 includes full startup and teardown sections with independent timeouts.
337
+ A missing default branch never blocks setup. After setup, clearing the startup
338
+ script does not remove saved branch defaults.
330
339
 
331
340
  Template maintenance starts unconfigured. When the repository needs ongoing
332
341
  environment updates, the coding agent should author the maintenance script and
@@ -475,8 +484,10 @@ stopped at a usage limit before the switch still needs a follow-up. When Claude
475
484
  account, boxes.dev resumes the same conversation and continues the unfinished
476
485
  request before queued follow-ups. Switching accounts restarts Claude, stopping
477
486
  its background commands and agents. Claude checks completed work before
478
- recovering unfinished work. Stop cancels this recovery. With no available account,
479
- or pending steering that cannot be safely resumed, the turn stays stopped.
487
+ recovering unfinished work. Messages already sent with Steer stay in the
488
+ conversation and are not sent again during recovery. Stop cancels recovery.
489
+ With no available account, or if the replacement API key also hits a limit,
490
+ the turn stops with an error; continue it when usage is available.
480
491
 
481
492
  Configure agents manages the Codex and Claude accounts that run coding-agent
482
493
  threads. Remote MCP connections are managed separately from **Integrations →
@@ -625,15 +636,15 @@ or links. The user can instead choose **Use an SSH key for GitHub pull/push
625
636
  access instead**. An explicit SSH or automatic-access choice remains selected
626
637
  when GitHub access refreshes.
627
638
 
628
- Review also shows an editable **Devbox startup script**. For one repository,
629
- boxes.dev recommends commands that refresh the project root from the selected
630
- repository's default branch. For multiple repositories, the recommendation
631
- refreshes every reviewed child folder. The script will run while each future
632
- devbox is prepared for its first thread, before the first prompt is sent. This
633
- keeps the checkout current when the Template-box snapshot contains an older
634
- version. It is optional: the user can edit it or leave it blank, and an unknown
635
- default branch leaves the recommendation blank without blocking project
636
- creation.
639
+ Review's **New devboxes** section shows the **Default branch** separately from
640
+ the optional **Startup script**. boxes.dev fetches and prepares each repository's
641
+ selected branch before running the startup script and sending the first prompt.
642
+ The branch shown here supplies the project default; a thread can choose another
643
+ branch. Use the script for application setup, such as installing dependencies
644
+ or starting services. Leaving it blank skips those extra commands and keeps the
645
+ branch default. If a default branch is unknown, confirm the intended starting
646
+ branch and choose **Use default branch**. Setup can continue without one, but
647
+ then new devboxes inherit the saved checkout unless a thread selects a branch.
637
648
 
638
649
  GitHub creation clones committed Git contents and Git LFS objects. It does not
639
650
  copy uncommitted local work, scan local configuration, install dependencies, or
@@ -846,12 +857,23 @@ loopback address unchecked by default because they depend on software running
846
857
  on the local computer. Remote HTTP MCP definitions stay selected, but their
847
858
  OAuth or token credentials may need to be authorized again on the Template box.
848
859
 
860
+ Claude hooks appear in a separate **Hooks** row. If any hook runs a command,
861
+ the row shows a **Check first** badge and starts unchecked, because a command
862
+ hook whose script or tool is missing on the Template box can stop Claude from
863
+ responding to any prompt. When no hook runs a command, **Hooks** stays
864
+ selected. The rest of the Claude settings stay selected either way and are
865
+ copied without the hooks unless **Hooks** is also selected. Users can select
866
+ **Hooks** when the Template box will have what the commands need.
867
+
849
868
  When desktop local-folder setup detects a Git remote, **Finalize Bundle** shows
850
- an editable **Devbox startup script** field. The field saves shell commands as
851
- the project's startup setting; it does not create a script file on the Template
852
- box. If the default branch cannot be detected, the user can enter it and
853
- populate the recommended commands. Leaving the field blank disables startup
854
- automation and does not block setup.
869
+ **New devboxes**, with the **Default branch** separate from the optional
870
+ **Startup script**. boxes.dev prepares the selected branch before running the
871
+ script. If the default branch cannot be detected, confirm the intended starting
872
+ branch and choose **Use default branch**. Continuing without one preserves the
873
+ saved checkout unless a thread selects a branch. The script field saves shell commands
874
+ in the project settings; it does not create a script file on the Template box.
875
+ Leaving it blank skips extra startup commands and does not remove a branch
876
+ default already shown in the review.
855
877
 
856
878
  ## Git Access
857
879
 
@@ -1027,11 +1049,15 @@ Common recovery paths:
1027
1049
  - Interrupted local setup: resume the setup scan, review, bundle, or upload
1028
1050
  step.
1029
1051
  - Upload failure: retry the upload.
1030
- - Remote Git access failure: choose **Fix Git access**. boxes.dev removes the
1031
- incomplete Template box, keeps the approved setup review and other bundle
1032
- choices, and returns to Finalize Bundle with Git access marked unverified.
1033
- Reconnect GitHub or grant the App access named there, switch to and verify
1034
- SSH, or skip Git access before continuing.
1052
+ - Remote Git SSH verification failure: the message names the Git host and what
1053
+ setup observed: the repository couldn't be read after SSH sign-in, a
1054
+ follow-up SSH connection failed, or sign-in didn't complete although the SSH
1055
+ server answered. Fix what it points to, then choose **Retry setup** to check
1056
+ the same key again. To change or skip Git access, choose **Fix Git access**.
1057
+ boxes.dev removes the incomplete Template box, keeps the approved setup review
1058
+ and other bundle choices, and returns to Finalize Bundle with Git access
1059
+ marked unverified. Reconnect GitHub or grant the App access named there,
1060
+ switch to and verify SSH, or skip Git access before continuing.
1035
1061
  - User-stopped remote setup: choose **Open setup thread** and continue the same
1036
1062
  conversation. boxes.dev keeps the setup thread state and does not
1037
1063
  automatically continue after Stop. When the user and agent agree the setup
@@ -500,7 +500,7 @@ Start the ordinary new-project flow and choose **Start from a Team Template**.
500
500
  The picker shows only templates with a current saved version and does not
501
501
  preselect one. Select the exact template, name the project and complete
502
502
  **Needed to create the project**, which brings required environment values
503
- and all member files together. **Optional values** starts collapsed; these
503
+ and all member files together. **Show optional** starts collapsed; these
504
504
  can be added now or later in Project settings. Independent projects also
505
505
  offer coding-agent choices; at least one must be selected when the template
506
506
  includes setup instructions. Team defaults remain available for review.