dsh-artel 0.0.0-stage → 0.2.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/CHANGELOG.md ADDED
@@ -0,0 +1,92 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project are documented here. The format follows
4
+ [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project uses
5
+ [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
6
+
7
+ ## [0.2.0] — 2026-11-19
8
+
9
+ ### Added
10
+
11
+ - In-chat launcher: an **Artel** button in the chat composer tool row (next to **+**) opens a panel over
12
+ the current conversation. The chat stays mounted underneath, and a dot on the button marks a run in
13
+ progress.
14
+ - Panel with a **Sessions** rail: every Artel run of the chat session, grouped by project, with a status
15
+ dot, the mode/counts/phase meta line, the active run highlighted, **+ New Artel** and session
16
+ counters.
17
+ - New-run form in the panel: project and mode in the heading, a task field, the Solo/Swarm selector with
18
+ hints, the **Go →** primary button (Ctrl+Enter) and a note that the run works in an isolated copy.
19
+ - Run page in the panel: task, mode tag, status pill and phase line, a two-step **Stop** confirmation,
20
+ and a feed of full agent replies (avatar, name, role, time, markdown), grouped tool calls, and
21
+ status, plan, user, peer, collision and error rows.
22
+ - Message composer on the run page: "Write to the agents…", a recipient picker (**Everyone** or a
23
+ specific agent) and Ctrl+Enter; a message also wakes a waiting or stopped run.
24
+ - **Changes** card on the run page: the run's file list with added/removed line counts, lazy diffs,
25
+ all-files **Apply** and **Discard** with inline confirmations, and applied/discarded/skipped states.
26
+ - The panel works on a blank chat session too: the profile's default working directory is used, so a
27
+ run can be started before the first message.
28
+
29
+ ### Changed
30
+
31
+ - Agents run unattended: Artel sets their approval policy to `never` and inherits the sandbox mode of
32
+ the parent chat session, so a run no longer stalls on an approval prompt.
33
+ - **Apply** writes every changed file; the per-file tick list and the "Apply N files" button are gone.
34
+ A conflict with a file changed in the project still rejects the whole apply.
35
+ - The run's diff count and status are visible in its header and in the rail while and after the agents
36
+ work.
37
+ - After **Apply** the isolated copy is deleted right away, like **Discard** already did; a run whose
38
+ copy is gone reports no changed files.
39
+ - The user guide and README now describe the in-chat launcher and the panel instead of the sidebar tab,
40
+ and ship screenshots of the new UI.
41
+
42
+ ### Removed
43
+
44
+ - The right-sidebar Artel tab and its standalone page. The client half now registers a single launcher
45
+ in the chat composer tool row and renders the panel as an overlay over the conversation.
46
+ - Per-file selection in the changes review, the "Open conversation" action and the session-header
47
+ status list.
48
+
49
+ ### Fixed
50
+
51
+ - `changeCount` is recalculated when a run is interrupted or fails, so the review card and the rail show
52
+ the real number of changed files instead of zero.
53
+ - The review card loads the run's changes when the run enters review, so the card no longer depends on
54
+ the Host-reported count to become visible.
55
+ - A Swarm planning turn no longer stalls when an agent calls `wait_agent`; the planning prompt tells
56
+ agents to announce their files and end the turn instead.
57
+
58
+ ## [0.1.0] — 2026-11-17
59
+
60
+ First public release.
61
+
62
+ ### Added
63
+
64
+ - **Solo** mode: one coding agent runs the task in its own copy of the project, end to end.
65
+ - **Swarm** mode: three agents share one copy and one agent tree. They open with a planning turn
66
+ that divides the files, then work in parallel, read each other's edits, and message each other
67
+ with the standard `send_message` / `list_agents` tools. Peer messages appear in the shared feed.
68
+ - Live run feed: agent messages, tool calls, status changes, ownership plans and collision notices.
69
+ You can write to a running agent without stopping it, and interrupt the run at any time.
70
+ - Per-file diff review with added/removed line counts and a line-by-line unified diff.
71
+ - Manual **Apply**: only the files you tick are copied into your project. A file you edited during
72
+ the run is reported and never overwritten.
73
+ - **Discard** removes the copy; nothing reaches the project.
74
+ - The run copy lives outside the project under `<DSH home>/artel/<profile>/copies` and is swept
75
+ after `keepCopiesHours` (72 by default).
76
+ - Locales: English, Russian, Chinese.
77
+ - Loopback-only HTTP API under `/api/dsh-artel/*`, fenced by local socket, local `Host` header and
78
+ a same-origin `Origin` check.
79
+ - First start moves the data root of the pre-rename `dsh-forge` build to the new `artel` directory,
80
+ so existing run records, feeds and copies keep working.
81
+
82
+ ### Notes
83
+
84
+ - The plugin was renamed from `dsh-forge` (the npm name `dsh-forge` belongs to an unrelated
85
+ placeholder package). The tab id changed as well, so an already open Forge tab does not restore —
86
+ open the **Artel** tab once after the restart.
87
+ - Requires DSH `^0.2.2-rc.1` and Node `^22.19.0 || >=24`.
88
+ - No build step: the host half is plain ESM and the client half is hand-written
89
+ `React.createElement`.
90
+
91
+ [0.2.0]: https://github.com/ksolodev/dsh-artel/compare/v0.1.0...v0.2.0
92
+ [0.1.0]: https://github.com/ksolodev/dsh-artel/releases/tag/v0.1.0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 dsh-artel contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,204 @@
1
- # Temporary Holding Version
1
+ # dsh-artel
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
+ [![npm version](https://img.shields.io/npm/v/dsh-artel.svg)](https://www.npmjs.com/package/dsh-artel)
4
+ [![CI](https://github.com/ksolodev/dsh-artel/actions/workflows/ci.yml/badge.svg)](https://github.com/ksolodev/dsh-artel/actions/workflows/ci.yml)
5
+ [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
6
+
7
+ ![Artel — review the diff, apply it yourself](docs/preview.svg)
8
+
9
+ Run a development task in an isolated copy of your project, watch the work as it happens, review the
10
+ diff line by line, then apply it yourself.
11
+
12
+ Artel is a DeepSeek Harness plugin. It adds an **Artel** icon button to the chat composer tool row, next
13
+ to **+**. The button covers the current chat with a panel: the session rail of Artel runs on the left,
14
+ and either the new-run form or the live run on the right. The chat session's working directory is the
15
+ project; Artel never touches it until you apply.
16
+
17
+ ![Artel opens over the chat](docs/artel-in-chat/screens/hero.png)
18
+
19
+ ## Install
20
+
21
+ Artel is a DSH bundle: it installs with the standard plugin CLI and needs no build step.
22
+
23
+ **From npm**
24
+
25
+ ```sh
26
+ dsh plugin --profile <profile> add dsh-artel
27
+ ```
28
+
29
+ **From the release tarball** — download `dsh-artel.tgz` from the
30
+ [latest release](https://github.com/ksolodev/dsh-artel/releases/latest), then:
31
+
32
+ ```sh
33
+ dsh plugin --profile <profile> add C:/path/to/dsh-artel.tgz
34
+ ```
35
+
36
+ **From a checkout** — point the plugin CLI at the directory:
37
+
38
+ ```sh
39
+ dsh plugin --profile <profile> add C:/path/to/dsh-artel
40
+ ```
41
+
42
+ A directory install is recorded as a `link:` dependency, so edits in the checkout are live after a
43
+ host reload. In the desktop app you can also use **Settings → Plugins → Install from file** and pick
44
+ the `.tgz` or the checkout folder.
45
+
46
+ After installing, restart DeepSeek Harness (or reload the page, which recomposes the client boot
47
+ graph), open a chat session that has a project directory, and click **Artel** in the composer tool row.
48
+ The plugin's host half talks to the client over a loopback-only HTTP API, so the plugin and the host
49
+ must run on the same machine.
50
+
51
+ ## How it works
52
+
53
+ 1. **Copy** — Artel copies the project into a fresh directory under your DSH home. `node_modules` is
54
+ linked, not copied, so the agents can still run the project's checks. The real project is not
55
+ touched.
56
+ 2. **Agents** — one agent works in the copy in **Solo**; three agents share one copy and one agent
57
+ tree in **Swarm**, so they can message each other with `send_message`/`list_agents`. The first
58
+ Swarm turn is planning only: the agents divide the files and announce who owns what. The agents run
59
+ unattended: Artel gives them the approval policy `never` and inherits the sandbox mode of the chat
60
+ session, so a run never stalls on an approval prompt.
61
+ 3. **Diff** — when every agent goes idle, Artel stops the run and fills the **Changes** card on the run
62
+ page: every changed file with added and removed line counts and a line-by-line diff.
63
+ 4. **Apply** — you press **Apply** and confirm. It writes every changed file into the project. Before
64
+ writing, Artel checks each file against the state it had when the run started; a file you edited
65
+ during the run is reported and the whole apply is refused, so nothing is half-written. **Discard**
66
+ deletes the copy and changes nothing.
67
+
68
+ ## Two ways to run a task
69
+
70
+ **Solo** — one agent does the whole task in its own copy of the project. It reads the code, edits the
71
+ copy, and runs whatever checks it needs. Use it when the task is small and well understood: fix a
72
+ bug, add a screen, change some text.
73
+
74
+ Write the task the way you would write it to a colleague: what should come out, and where in the
75
+ project it lives. The agent finds and reads the files itself.
76
+
77
+ **Swarm** — three agents share one copy and one conversation tree. Their first turn is a planning
78
+ turn: they make no edits, they divide the files among themselves and say out loud who owns what, so
79
+ that nobody edits the same file. They can also message each other directly: the team has
80
+ `send_message`/`list_agents`, so a question, a heads-up or a promise to take an area reaches the
81
+ other agents as a real turn, and every such message appears in the shared feed. After the planning
82
+ turn they work in parallel, read each other's edits on disk, and Artel flags any file that two agents
83
+ touch. Checks run once, against the whole copy.
84
+
85
+ Use Swarm when the work splits into pieces that do not meet in the same files.
86
+
87
+ ## Review and apply
88
+
89
+ While a run is active, the run page shows the live feed of every agent: full replies with the avatar,
90
+ name, role and time, grouped tool calls, and separate rows for status, plans, your messages,
91
+ agent-to-agent messages, edit collisions and errors. You can write to the agents at any time without
92
+ waiting for them to finish (Ctrl+Enter sends); address everyone or one specific agent.
93
+
94
+ ![The run page](docs/artel-in-chat/screens/run.png)
95
+
96
+ When every agent is idle, Artel stops and waits for you:
97
+
98
+ - **Changes** lists every changed file with added and removed line counts. Open a file to see the diff.
99
+ - **Apply** asks for confirmation and writes every changed file into your project. A file that you
100
+ edited during the run is never overwritten: Artel reports it and refuses the whole apply, so you can
101
+ discard and run again.
102
+ - **Discard** asks for confirmation, deletes the copy and changes nothing.
103
+
104
+ ![The Changes card](docs/artel-in-chat/screens/changes.png)
105
+
106
+ The copy lives outside the project, under your DSH home directory. It is deleted as soon as you apply
107
+ or discard the run, so reviewed copies do not pile up on disk.
108
+
109
+ ## Open it
110
+
111
+ 1. Open a chat session that has a project directory.
112
+ 2. Click the **Artel** button in the chat composer tool row (next to **+**). While a run in the session
113
+ is active, the button shows a dot.
114
+ 3. Pick Solo or Swarm, write the task, press **Go →** (or Ctrl+Enter). **← Chat** or Esc returns to the
115
+ chat; the chat itself is not replaced.
116
+
117
+ The panel belongs to the chat session: the **Sessions** rail lists every run of the session, grouped by
118
+ project, with the active one highlighted, and **+ New Artel** returns to the form. Each agent works in
119
+ the copy as its working directory. The first agent of a Swarm run is an ordinary DSH session, the other
120
+ two are that session's subagents, live in the same agent tree, and are not listed in the sidebar as
121
+ separate chats. Solo agents are ordinary sessions as well, titled `Artel · <agent> — <task>`; archive
122
+ or delete those sessions when you no longer need them.
123
+
124
+ ## Upgrading from `dsh-forge`
125
+
126
+ The plugin was renamed to Artel (the npm name `dsh-forge` belongs to an unrelated placeholder package).
127
+ On its first start the Host moves the previous data root from `<DSH home>/forge/<profile>` to
128
+ `<DSH home>/artel/<profile>`, so existing run records, feeds and copies stay available. The plugin id
129
+ changed with the name: an open Forge page does not restore Artel, so restart DeepSeek Harness and open
130
+ Artel once from the chat composer.
131
+
132
+ ## Requirements
133
+
134
+ - DSH `^0.2.2-rc.1` with a Host that provides the session controller (the desktop app or `dsh web`).
135
+ - Node `^22.19.0 || >=24` — the same runtime the Host uses.
136
+ - No Git, no extra binaries and no global install: copies, diffs and applying are done by the plugin.
137
+
138
+ ## Configuration
139
+
140
+ All values are optional; set them in the bundle's plugin configuration.
141
+
142
+ | Key | Default | Meaning |
143
+ | --- | --- | --- |
144
+ | `swarmAgentCount` | `3` | Agents per Swarm run (2–8). |
145
+ | `maxRunsPerSession` | `10` | Finished runs kept per session; the oldest are dropped with their copies. Runs waiting for you stay. |
146
+ | `keepCopiesHours` | `72` | Retention window for run copies, in hours (0 disables). The current startup sweep removes copies of applied and discarded runs regardless of age. |
147
+ | `diffContext` | `3` | Context lines around each diff hunk (0–12). |
148
+ | `idleGraceMs` | `1200` | How long Artel waits for a possible agent-to-agent message before it calls the run idle (0–10000). |
149
+ | `excludeGlobs` | `[]` | Extra paths never copied, diffed, or applied. |
150
+ | `copyRoot` | `<DSH home>/artel/<profile>/copies` | Where run copies are created. |
151
+ | `stateDir` | `<DSH home>/artel/<profile>/state` | Run index and feeds. |
152
+
153
+ ## Limitations
154
+
155
+ - The project is copied as files, not through Git. Git metadata is not copied, and Artel does not
156
+ require Git to be installed.
157
+ - A copy is limited to 512 MB in total and 32 MB per file. A project above the total limit is
158
+ refused with an error instead of a partial copy; files above the per-file limit are left out of
159
+ the copy.
160
+ - `node_modules` is linked into the copy instead of copied, so agents can run project checks.
161
+ - Artel watches the copy, not your project: it cannot know about edits you make during the run until
162
+ you apply, and then it refuses to overwrite those files.
163
+ - Only files are applied. Deleted files are deleted on Apply; renames arrive as one deletion and one
164
+ addition.
165
+ - Apply is all-or-nothing for the run: either every changed file is written or, if a file conflicts,
166
+ none is. The changes card has no per-file selection.
167
+ - Swarm agents live in one agent tree: the first agent is the session at the root of that tree and the
168
+ other two are its subagents. That is what lets them message each other, and it means the root session
169
+ must exist for their messages to be delivered. Closing that session (or restarting the Host) ends the
170
+ transport, exactly like the "runs stop on restart" rule below. A profile that does not provide the
171
+ subagent stack falls back to three independent sessions: the run still works, but the agents cannot
172
+ message each other and coordinate only through the ownership line and the files on disk.
173
+ - If no one claims a file, Artel hands the unclaimed files that sit next to claimed work to the agents
174
+ that claimed nothing, and marks them in the plan as "nobody claimed it" — so nobody idles through a
175
+ run. If the task is small enough for one agent, the other two end up verifying the copy and say so
176
+ in their summaries instead of inventing work.
177
+ - Restarting the plugin or the Host interrupts active runs. Their work stays reviewable and can still
178
+ be applied or discarded, but the agents stop and no longer accept messages.
179
+
180
+ ## Data and privacy
181
+
182
+ Run records and feeds are plain JSON and JSONL files under `stateDir`. Agent conversations are
183
+ ordinary DSH sessions and stay in your session store. The plugin's host half talks to the client over
184
+ a loopback-only HTTP API; every request is checked for a local socket, a local Host header and a
185
+ same-origin origin.
186
+
187
+ ## Development
188
+
189
+ ```sh
190
+ node --test test/*.test.js
191
+ ```
192
+
193
+ No build step: the host half is plain ESM (`lib/*.js`) and the client half is hand-written
194
+ `React.createElement` (`lib/client.js`). CI runs the suite on Ubuntu and Windows with Node 22 and 24.
195
+
196
+ - [ARCHITECTURE.md](ARCHITECTURE.md) — host/client design, the run and data model, the route surface.
197
+ - [docs/publishing.md](docs/publishing.md) — how a release is packed, published and listed.
198
+ - [docs/guide.md](docs/guide.md), [docs/guide.ru.md](docs/guide.ru.md),
199
+ [docs/guide.zh.md](docs/guide.zh.md) — the user guide (en / ru / zh).
200
+ - [CHANGELOG.md](CHANGELOG.md) — release notes.
201
+
202
+ ## License
203
+
204
+ MIT © dsh-artel contributors — see [LICENSE](LICENSE).
@@ -0,0 +1,12 @@
1
+ # Artel bundle.
2
+ #
3
+ # This file is the bundle patch: `dsh.bundle.patch` in package.json points here,
4
+ # and the plugin CLI appends this package to the profile's `dsh.profile.bundles`
5
+ # when it is installed.
6
+ #
7
+ # The row id must match the Host plugin's `export const name` (`dsh-artel` in
8
+ # lib/index.js). Keep the config block empty here: settings live in the plugin
9
+ # details page, and the client reads them through the plugin's own routes.
10
+ - insert:
11
+ - id: dsh-artel
12
+ name: dsh-artel
package/docs/guide.md ADDED
@@ -0,0 +1,218 @@
1
+ # Artel
2
+
3
+ Artel runs a development task in an isolated copy of the project that the current chat session works
4
+ in: it shows the work as it happens and moves the result into your project only when you ask.
5
+
6
+ Artel opens from the chat itself. The **Artel** icon button sits in the composer tool row, next to
7
+ "+". It lays a panel (overlay) over the current chat; the chat stays underneath and is not changed.
8
+ The panel belongs to this session, and the session's working directory is the project.
9
+
10
+ ![The Artel panel: the session rail and the new-run form](artel-in-chat/screens/hero.png)
11
+
12
+ ## Open Artel
13
+
14
+ 1. Open a chat whose working directory contains the project.
15
+ 2. Click **Artel** in the tool row under the chat composer (next to **+**). While a run in this
16
+ session is active, the button shows a dot.
17
+ 3. The panel covers the chat area. To get back to the chat, use **← Chat** in the panel header or
18
+ press Esc. Closing the panel does not stop the run: the agents keep working, and the next time
19
+ you open the panel it returns to the last selected run.
20
+
21
+ The header holds **← Chat**, the title **Artel**, the status of the selected run, and **Refresh** (it
22
+ re-reads the run list and the open run; the feed itself updates while the panel is open).
23
+
24
+ The left side is the **Sessions** rail: every Artel run of the current session, grouped by project.
25
+ A row shows a state dot, the task and a short `Solo · 1/3 · phase` line — the mode, how many agents
26
+ have finished a turn out of the total, and the current phase (the last status or plan message). The
27
+ active run is highlighted; clicking a row opens its page. **+ New Artel** returns to the new-run
28
+ form, and the rail footer shows `{n} runs` and `{n} files`. While there are no runs the rail says
29
+ "No Artel runs yet." and "Describe a task on the right — the agents work in an isolated copy.".
30
+
31
+ ## New Artel
32
+
33
+ The form takes the right side of the panel. Its heading names the project and the mode: "New Artel
34
+ in <project> · via <mode>". If the project is not known yet the heading is shorter: "New Artel ·
35
+ via <mode>".
36
+
37
+ 1. Describe the task in "What should the agents do? Describe the task…": what should come out and
38
+ where it lives in the project. You do not need to prepare any files — the agents find and read
39
+ them.
40
+ 2. Pick a mode: **Solo** ("One agent, one copy") or **Swarm** ("Three agents divide the files").
41
+ 3. Press **Go →** (or Ctrl+Enter). While the request is in flight the button reads "Starting…".
42
+
43
+ Below the form: "Artel works in an isolated copy of the project. Your files stay untouched until you
44
+ apply the changes." If a run does not start, a banner titled "Could not start Artel" with the error
45
+ text appears under the button.
46
+
47
+ ## Starting a run
48
+
49
+ Artel then:
50
+
51
+ 1. copies the project into a separate directory outside it;
52
+ 2. starts one agent (Solo) or three (Swarm) with the copy as their working directory;
53
+ 3. hands them the task and a few rules: edit only the copy, never touch the real project, run the
54
+ appropriate checks and finish by explaining what was done.
55
+
56
+ The copy is made once per run and all agents work in it. The project itself never changes.
57
+
58
+ The agents run unattended: Artel gives them the approval policy `never` and inherits the sandbox
59
+ mode of the parent chat session. Tools that are unavailable in that sandbox return a refusal to the
60
+ agent instead of leaving the run waiting for an approval.
61
+
62
+ ## Solo
63
+
64
+ One agent carries the task from start to finish. Its messages, tool calls and edits appear in the
65
+ feed right away. You can write to it at any time — the message joins the conversation without
66
+ stopping the work.
67
+
68
+ ## Swarm
69
+
70
+ Three agents work in the same copy and see each other's edits: each one reads the files the others
71
+ have already changed and adapts to them. They also talk to each other: the whole team lives in one
72
+ conversation tree, so `send_message({ agent: "<name>", message: "..." })` reaches a neighbour as a
73
+ real turn, and `list_agents()` lists the whole team. Their exchanges appear in the feed as separate
74
+ rows: the sender's name, an arrow and the message text.
75
+
76
+ **The first turn is planning.** The agents may not edit anything. They read the project, agree who
77
+ owns which files (if a boundary is unclear, they message the neighbour) and end the turn with a
78
+ single line:
79
+
80
+ ```
81
+ OWNERSHIP: src/app/settings/**
82
+ ```
83
+
84
+ Artel collects the claims, leaves a contested area to the first claimant and shows the split as a
85
+ **Plan** card in the feed. If two agents claim the same files, the feed names both and the winner.
86
+
87
+ **Then parallel work.** Artel sends each agent its area and starts them all at once. Each one reads
88
+ the files the others have already changed and adapts to them; if a change outside the area is
89
+ needed, the agent messages the owner instead of editing someone else's file and mentions it in the
90
+ final report. A message that arrives while an agent is idle wakes it for a new turn; Artel waits
91
+ briefly before declaring the run waiting so a short exchange between two agents does not look like
92
+ finished work.
93
+
94
+ While the run is active Artel watches the edits. When a second agent touches a file another agent
95
+ has already touched, an **Edit collision** row appears in the feed with both names and the path.
96
+ Ownership is declared, not enforced: the overlap is visible, the edit is not blocked.
97
+
98
+ An agent that claimed nothing receives the unclaimed files with a "nobody claimed it" note in the
99
+ plan, so it does not sit idle; if there are no unclaimed files, it becomes a reviewer of the shared
100
+ copy and says so in its report.
101
+
102
+ If nobody claims an area during the planning turn, Artel asks again. If the second attempt is empty
103
+ too, Artel splits the top level of the project between the agents so the run does not stall, and
104
+ says so in the feed.
105
+
106
+ ## The run page
107
+
108
+ The selected run's page opens on the right: the task at the top, the mode tag (**Solo** or
109
+ **Swarm**), the status, a tag with the number of changed files (once there are any) and a phase line
110
+ — the same short stage description as in the rail.
111
+
112
+ Run statuses: **Preparing**, **Planning**, **Working**, **Waiting for you**, **Finished**,
113
+ **Stopped**, **Failed**, **Applied**, **Discarded**.
114
+
115
+ ![The run page: agent replies and grouped tool calls](artel-in-chat/screens/run.png)
116
+
117
+ While a run is active the header has a **Stop** button. It asks for confirmation: "Stop this Artel
118
+ run?" with **Stop run** and **Keep working** (and "Stopping…" while the request is in flight). A
119
+ stopped run becomes **Stopped**; the copy and the diff stay available, and messaging the agents puts
120
+ it back to work.
121
+
122
+ ### The feed
123
+
124
+ - Full agent replies: an avatar with the initial, the name, the role and the time; the text is
125
+ rendered as markdown.
126
+ - Tool calls are grouped into compact rows: the tool name and the file path or command.
127
+ - Status rows with a timestamp and a **Plan** card with the split of work.
128
+ - Your messages: a bubble labelled "You → Everyone" or "You → <agent>".
129
+ - Agents talking to each other: the sender's name, an arrow and the message text.
130
+ - **Edit collision** when two agents touched one path; **Error** when an agent's turn failed. Both
131
+ name the path underneath when it is known.
132
+
133
+ While the feed is empty it says "The agents are getting ready — their messages will appear here.";
134
+ while it loads, "Loading the feed…".
135
+
136
+ ### Messaging the agents
137
+
138
+ The field at the bottom is "Write to the agents…", with a **Send** button. The footer has **To**:
139
+ **Everyone** by default, and a specific agent can also be chosen. Next to it: "Ctrl+Enter — send".
140
+ The message appears in the feed as "You → …" and puts a waiting or stopped run back to work while the
141
+ copy is still neither applied nor discarded.
142
+
143
+ ## Changes: apply or discard
144
+
145
+ When the agents go idle, Artel stops, computes the difference against your project and moves the run
146
+ to **Waiting for you**. The **Changes** card at the bottom of the page lists the files that differ
147
+ from your project: the heading "Changes · N files" and total `+N/−M` counts. Each row has a status —
148
+ **added**, **modified**, **deleted** or **binary** — and its own `+N/−M`. Click a file to open its
149
+ diff (**Show the diff**); click again to close it (**Hide the diff**). Binary files cannot be
150
+ expanded. The card header has **Refresh changes** and a collapse toggle (**Show changes** / **Hide
151
+ changes**).
152
+
153
+ ![The Changes card with a file diff open](artel-in-chat/screens/changes.png)
154
+
155
+ - **Apply** first asks for confirmation: "Apply these changes?" and "The changes will be written to
156
+ <project>. The isolated copy will be deleted.", with **Apply** and **Cancel**. It writes every
157
+ file in the card; there is no per-file selection.
158
+ - **Discard** asks "Discard these changes?" and "The isolated copy will be deleted; <project> will
159
+ stay untouched.", with **Discard** and **Cancel**.
160
+
161
+ After the decision a plate replaces the buttons: **Applied** with "The changes are written to
162
+ <project>." or **Discarded** with "The copy was deleted; the project is unchanged." If some files
163
+ could not be written, the card adds "Skipped: N".
164
+
165
+ Before writing, Artel re-reads your project. For each file it checks whether the file still matches
166
+ the state it had when the run started:
167
+
168
+ - If it does, the file is applied.
169
+ - If you edited it during the run, Artel refuses: "Nothing was applied. <file>: changed in your
170
+ project during the run" — and writes nothing, so you can decide again.
171
+ - A file that appeared in the project during the run is rejected the same way.
172
+
173
+ An apply is final: the run becomes **Applied**, its changes are in the project, and the isolated copy is
174
+ deleted right away. The diff stays in the run feed, so you can still read what changed.
175
+
176
+ ## Where the data lives
177
+
178
+ - Copies: `<DSH home>/artel/<profile>/copies/<run id>` — deleted when the run is applied or discarded; a
179
+ copy left behind by a crash is removed at the next start.
180
+ - Run index and feeds: `<DSH home>/artel/<profile>/state/runs` — a JSON index and one JSONL file per
181
+ run, with a size limit.
182
+ - Agent conversations: ordinary DSH sessions in your session store.
183
+
184
+ Artel keeps at most `maxRunsPerSession` runs per session: the oldest finished runs (applied,
185
+ discarded, stopped, failed) are dropped from the list together with their copies. Runs still waiting
186
+ for your decision are never dropped.
187
+
188
+ ## Troubleshooting
189
+
190
+ **"The Artel host half is unavailable. Check that the plugin is enabled."** — the client half loaded
191
+ but the host half does not answer: the plugin is disabled or the host half failed to load. Enable
192
+ the plugin and reload the page.
193
+
194
+ **"The Artel host is restarting — retry in a moment."** — the host is updating or restarting. Wait
195
+ and press **Retry** in the banner.
196
+
197
+ **"This chat session has no project directory yet, so there is nothing to copy"** — the session has
198
+ no working directory, so there is nothing to copy. Open a workspace or start the session in a
199
+ directory. If the project directory exists but was deleted or moved, the host answers
200
+ "The project directory does not exist".
201
+
202
+ **"Could not copy the project: project is larger than 536870912 bytes; excluded folders or a smaller
203
+ project are required"** — the project exceeds the 512 MB copy limit. Artel does not make a partial
204
+ copy: the run is refused. Exclude heavy directories with `excludeGlobs` or use a smaller project.
205
+ Files larger than 32 MB are left out of the copy.
206
+
207
+ **"Another run is already in progress in this session"** — one active run per session. Finish it or
208
+ stop it.
209
+
210
+ **No changes** — the agents may have finished without edits; the card says "No file changes in this
211
+ run.". Read the feed; if the task needs a nudge, write to the agents.
212
+
213
+ **The apply was rejected** — the card's banner lists the files that changed in the project during
214
+ the run. Discard the run, wait until the file is free and start again: applying only the remaining
215
+ files is not possible, because the card has no per-file selection.
216
+
217
+ **The run was interrupted by a restart** — if the plugin or the host restarted, active runs become
218
+ **Stopped**. The copy and the diff stay: you can apply or discard them.