@marver-design/marver 0.27.2 → 0.28.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.
Files changed (64) hide show
  1. package/CHANGELOG.md +101 -0
  2. package/README.md +4 -2
  3. package/dist/{anchor-check-gkxkPAIv.mjs → anchor-check-PHUOFj1N.mjs} +1 -1
  4. package/dist/{audio-Dw1lfMdb.mjs → audio-DX4POHAj.mjs} +39 -4
  5. package/dist/{boards-BqUqKNW8.mjs → boards-BeWtjGUM.mjs} +49 -4
  6. package/dist/boards-EH2onUXM.mjs +995 -0
  7. package/dist/{build-VgNg4rr8.mjs → build-BsAyLMT1.mjs} +7 -5
  8. package/dist/{capture-vadKjuCo.mjs → capture-DdZ6xgoz.mjs} +92 -30
  9. package/dist/cli.mjs +37 -16
  10. package/dist/{comments-YEU1Zhv9.mjs → comments-CrBHPEQl.mjs} +2 -2
  11. package/dist/config-BezZTiov.mjs +182 -0
  12. package/dist/conn-BMiHS42T.mjs +222 -0
  13. package/dist/connectors-MR9d-EBP.mjs +290 -0
  14. package/dist/{context-Ccjrhr1J.mjs → context-BUnFiyA3.mjs} +2 -2
  15. package/dist/{daemon-Dc9AH0M3.mjs → daemon-C5dg2R-V.mjs} +2187 -182
  16. package/dist/{dev-ri6nAlRp.mjs → dev-D7YS7iT2.mjs} +22 -11
  17. package/dist/{init-W0nxR1OY.mjs → init-WE5lQkQL.mjs} +7 -2
  18. package/dist/jam-Cj5gBvwD.mjs +373 -0
  19. package/dist/{link-CdTgn94Y.mjs → link-BFFRgrMt.mjs} +3 -3
  20. package/dist/listener-DdLEM79A.mjs +80 -0
  21. package/dist/{manifest-aFyDmL8C.mjs → manifest-DPZ3WNg_.mjs} +1 -1
  22. package/dist/{marks-BF9pNEgH.mjs → marks-Dyn6tmjp.mjs} +3 -3
  23. package/dist/{marks-CnCCfAbD.mjs → marks-Kmdab_5w.mjs} +2 -2
  24. package/dist/{perf-DkAUFT6W.mjs → perf-Cn5LiRaY.mjs} +3 -3
  25. package/dist/{perf-jam-BaH3Lg0m.mjs → perf-jam-QxD_UnzN.mjs} +1 -1
  26. package/dist/permit-DDa6wqOs.mjs +187 -0
  27. package/dist/{plugin-B8UghYuF.mjs → plugin-C_0yb-Fq.mjs} +365 -518
  28. package/dist/{poster-BNgafWMK.mjs → poster-DHi6I1fO.mjs} +1 -1
  29. package/dist/{publish-bakes-38Nja78p.mjs → publish-bakes-r4PEZuPl.mjs} +2 -2
  30. package/dist/{queue-CAM_vNmX.mjs → queue-c-6aTHEz.mjs} +164 -25
  31. package/dist/{recover-B8AiI29B.mjs → recover-nrLEVLyJ.mjs} +1 -1
  32. package/dist/{session-BAaJsK5c.mjs → session-DyVE7cCk.mjs} +1 -1
  33. package/dist/{shot-Ch24tiMO.mjs → shot-BrRtqaiS.mjs} +7 -6
  34. package/dist/{shot-CMQgMVZm.mjs → shot-DBWN8hPP.mjs} +1 -1
  35. package/dist/sizes-wjXDev3b.mjs +139 -0
  36. package/dist/speech-worker.mjs +23 -3
  37. package/dist/transport-C5FnY9ni.mjs +203 -0
  38. package/dist/{work-Bxz-ObF3.mjs → work-BYWD_1Zf.mjs} +3 -3
  39. package/dist/{work-CNhFF9pU.mjs → work-DJxH7cCX.mjs} +1 -1
  40. package/docs/jam-session.md +39 -14
  41. package/docs/live-jam.md +92 -10
  42. package/package.json +1 -1
  43. package/src/client/shell/JamSurface.tsx +56 -21
  44. package/src/client/shell/icons.tsx +1 -0
  45. package/src/client/shell/jam-capture.ts +97 -22
  46. package/src/client/shell/jam-keys.ts +32 -6
  47. package/src/client/shell/jam-lane.tsx +14 -5
  48. package/src/client/shell/jam-lines.ts +66 -9
  49. package/src/client/shell/jam-panel.tsx +55 -3
  50. package/src/client/shell/jam-queue.ts +50 -8
  51. package/src/client/shell/jam-session.tsx +53 -4
  52. package/src/client/shell/jam-surface-parts.tsx +6 -3
  53. package/src/client/shell/jam-ui.tsx +6 -1
  54. package/src/client/shell/jam-voice-wait.ts +21 -0
  55. package/src/client/shell/jam-voice.ts +14 -5
  56. package/src/client/shell/styles.css +27 -11
  57. package/src/client/shell/tidy.ts +3 -2
  58. package/src/shared/approval.ts +20 -0
  59. package/src/shared/events.ts +1 -1
  60. package/templates/AGENTS-embedded.md +28 -1
  61. package/templates/AGENTS-studio.md +28 -1
  62. package/templates/instructions/boards.md +7 -1
  63. package/templates/instructions/jam.md +90 -0
  64. package/dist/boards-BHKP5yhI.mjs +0 -342
@@ -0,0 +1,203 @@
1
+ import { b as validConnId, c as jamDir, h as readConn, x as writeAtomic } from "./conn-BMiHS42T.mjs";
2
+ import { mkdirSync, readFileSync, readdirSync, rmSync, statSync, watch } from "node:fs";
3
+ import { join } from "node:path";
4
+ import { createHmac, randomUUID, timingSafeEqual } from "node:crypto";
5
+ //#region src/server/jam/transport.ts
6
+ /**
7
+ * The session's commands travel through files, not a port (spec 29b, Part 6): Codex's and Cursor's
8
+ * sandboxes can block localhost, and a file in the repo reaches the daemon from any of them.
9
+ *
10
+ * The CLI writes design/.local/jam/req/<id>.json - the connection, the operation, its arguments, the
11
+ * time, and an HMAC-SHA256 over all of it made with the connection's key. The daemon checks the MAC,
12
+ * the age and that the id is new, does the operation, and answers design/.local/jam/res/<id>.json.
13
+ */
14
+ const reqDir = (root) => join(jamDir(root), "req");
15
+ const resDir = (root) => join(jamDir(root), "res");
16
+ /** Requests and answers older than this are swept. */
17
+ const KEEP_MS = 6e5;
18
+ const REQ_ID = /^[0-9a-f-]{36}$/;
19
+ const OPS = [
20
+ "next",
21
+ "say",
22
+ "progress",
23
+ "done",
24
+ "release",
25
+ "status",
26
+ "mute",
27
+ "own"
28
+ ];
29
+ /** JSON with its keys in order, at every depth: the bytes a MAC is made over. */
30
+ function canonical(v) {
31
+ if (Array.isArray(v)) return `[${v.map(canonical).join(",")}]`;
32
+ if (v && typeof v === "object") return `{${Object.keys(v).sort().filter((k) => v[k] !== void 0).map((k) => `${JSON.stringify(k)}:${canonical(v[k])}`).join(",")}}`;
33
+ return JSON.stringify(v);
34
+ }
35
+ const macOf = (key, body) => createHmac("sha256", Buffer.from(key, "hex")).update(canonical(body)).digest("hex");
36
+ /** Write a request and wait for its answer. Throws with a sentence a person can act on. */
37
+ async function request(root, conn, op, args, timeoutMs = 3e4) {
38
+ mkdirSync(reqDir(root), {
39
+ recursive: true,
40
+ mode: 448
41
+ });
42
+ mkdirSync(resDir(root), {
43
+ recursive: true,
44
+ mode: 448
45
+ });
46
+ const body = {
47
+ v: 1,
48
+ id: randomUUID(),
49
+ conn: conn.id,
50
+ op,
51
+ args,
52
+ ts: Date.now()
53
+ };
54
+ const req = {
55
+ ...body,
56
+ mac: macOf(conn.key, body)
57
+ };
58
+ const res = join(resDir(root), `${req.id}.json`);
59
+ writeAtomic(join(reqDir(root), `${req.id}.json`), JSON.stringify(req));
60
+ return await new Promise((resolve, reject) => {
61
+ let done = false;
62
+ const finish = (fn) => {
63
+ if (done) return;
64
+ done = true;
65
+ clearInterval(poll);
66
+ clearTimeout(to);
67
+ clearTimeout(again);
68
+ try {
69
+ w?.close();
70
+ } catch {}
71
+ fn();
72
+ };
73
+ const look = () => {
74
+ let text;
75
+ try {
76
+ text = readFileSync(res, "utf8");
77
+ } catch {
78
+ return;
79
+ }
80
+ let out;
81
+ try {
82
+ out = JSON.parse(text);
83
+ } catch {
84
+ return;
85
+ }
86
+ rmSync(res, { force: true });
87
+ finish(() => resolve(out));
88
+ };
89
+ let w;
90
+ try {
91
+ w = watch(resDir(root), { persistent: false }, look);
92
+ } catch {}
93
+ const poll = setInterval(look, 200);
94
+ const again = setTimeout(() => {
95
+ if (!done && Date.now() - body.ts < 55e3) try {
96
+ writeAtomic(join(reqDir(root), `${req.id}.json`), JSON.stringify(req));
97
+ } catch {}
98
+ }, Math.min(timeoutMs / 2, 2e4));
99
+ const to = setTimeout(() => finish(() => {
100
+ rmSync(join(reqDir(root), `${req.id}.json`), { force: true });
101
+ reject(/* @__PURE__ */ new Error("the canvas did not answer - is `marver dev` running in this repo?"));
102
+ }), timeoutMs);
103
+ look();
104
+ });
105
+ }
106
+ /** Check one request file: a known, live connection, a MAC made with its key, recent, never seen. */
107
+ function verify(root, raw, seen, now = Date.now()) {
108
+ const r = raw;
109
+ const id = typeof r?.id === "string" && REQ_ID.test(r.id) ? r.id : void 0;
110
+ if (!r || r.v !== 1 || !id || !validConnId(r.conn) || !OPS.includes(r.op) || !r.args || typeof r.args !== "object" || typeof r.ts !== "number" || typeof r.mac !== "string") return {
111
+ ok: false,
112
+ id,
113
+ error: "not a Jam request"
114
+ };
115
+ const conn = readConn(root, r.conn);
116
+ if (!conn) return {
117
+ ok: false,
118
+ id,
119
+ error: "this session is not connected to the canvas"
120
+ };
121
+ const want = Buffer.from(macOf(conn.key, {
122
+ v: 1,
123
+ id,
124
+ conn: r.conn,
125
+ op: r.op,
126
+ args: r.args,
127
+ ts: r.ts
128
+ }), "hex");
129
+ const got = Buffer.from(/^[0-9a-f]{64}$/.test(r.mac) ? r.mac : "", "hex");
130
+ if (got.length !== want.length || !timingSafeEqual(got, want)) return {
131
+ ok: false,
132
+ id,
133
+ error: "the request is not signed by this session"
134
+ };
135
+ if (Math.abs(now - r.ts) > 6e4) return {
136
+ ok: false,
137
+ id,
138
+ error: "the request is too old - run the command again"
139
+ };
140
+ if (seen.has(id)) return {
141
+ ok: false,
142
+ id,
143
+ error: "this request was already answered"
144
+ };
145
+ seen.add(id);
146
+ return {
147
+ ok: true,
148
+ req: r,
149
+ conn
150
+ };
151
+ }
152
+ function answer(root, id, body) {
153
+ if (!REQ_ID.test(id)) return;
154
+ mkdirSync(resDir(root), {
155
+ recursive: true,
156
+ mode: 448
157
+ });
158
+ writeAtomic(join(resDir(root), `${id}.json`), JSON.stringify(body));
159
+ }
160
+ /** The requests waiting now, oldest first - each read and removed (a request is taken once). */
161
+ function takeRequests(root) {
162
+ let names;
163
+ try {
164
+ names = readdirSync(reqDir(root)).filter((n) => n.endsWith(".json"));
165
+ } catch {
166
+ return [];
167
+ }
168
+ const out = [];
169
+ for (const n of names) {
170
+ const file = join(reqDir(root), n);
171
+ let raw = null;
172
+ let t = 0;
173
+ try {
174
+ t = statSync(file).mtimeMs;
175
+ raw = JSON.parse(readFileSync(file, "utf8"));
176
+ } catch {
177
+ continue;
178
+ }
179
+ rmSync(file, { force: true });
180
+ out.push({
181
+ file,
182
+ raw,
183
+ t
184
+ });
185
+ }
186
+ return out.sort((a, b) => a.t - b.t);
187
+ }
188
+ /** Requests and answers nobody came back for. */
189
+ function sweep(root, now = Date.now()) {
190
+ for (const dir of [reqDir(root), resDir(root)]) {
191
+ let names;
192
+ try {
193
+ names = readdirSync(dir);
194
+ } catch {
195
+ continue;
196
+ }
197
+ for (const n of names) try {
198
+ if (now - statSync(join(dir, n)).mtimeMs > KEEP_MS) rmSync(join(dir, n), { force: true });
199
+ } catch {}
200
+ }
201
+ }
202
+ //#endregion
203
+ export { answer, reqDir, request, sweep, takeRequests, verify };
@@ -1,6 +1,6 @@
1
1
  import { r as NAME } from "./cli.mjs";
2
- import { i as readDevInfo, n as WORK_TTL_MAX, t as WORK_TTL_DEFAULT } from "./work-CNhFF9pU.mjs";
3
- import { unreachable } from "./link-CdTgn94Y.mjs";
2
+ import { i as readDevInfo, n as WORK_TTL_MAX, t as WORK_TTL_DEFAULT } from "./work-DJxH7cCX.mjs";
3
+ import { unreachable } from "./link-BFFRgrMt.mjs";
4
4
  //#region src/cli/work.ts
5
5
  /**
6
6
  * `marver work` - the coding agent's hand on the canvas working state.
@@ -68,7 +68,7 @@ async function workCommand(root, action, frames, opts) {
68
68
  });
69
69
  console.log(active.length ? `still working: ${active.join(", ")}` : "nothing working - all clear");
70
70
  const done = before.filter((f) => !active.includes(f));
71
- const { links, hints } = done.length ? await (await import("./link-CdTgn94Y.mjs")).handBack(root, done) : {
71
+ const { links, hints } = done.length ? await (await import("./link-BFFRgrMt.mjs")).handBack(root, done) : {
72
72
  links: [],
73
73
  hints: []
74
74
  };
@@ -1,5 +1,5 @@
1
1
  import { t as __exportAll } from "./rolldown-runtime-8H4AJuhK.mjs";
2
- import { s as listBoardFiles } from "./boards-BHKP5yhI.mjs";
2
+ import { c as listBoardFiles } from "./boards-EH2onUXM.mjs";
3
3
  import { r as pidRuns } from "./exclusive-B1RtpeeP.mjs";
4
4
  import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
5
5
  import { join } from "node:path";
@@ -25,13 +25,24 @@ dot. While it records, everything you do is part of it:
25
25
  pictured as the capture ends - three at most - at the size you were looking at them (a
26
26
  device, a width you dragged, the play stage). A capture holds twelve pictures in all.
27
27
 
28
- `E` ends it. `Esc` throws it away. One capture records at a time.
28
+ Two ways to end it (0.28): `E` **stops and queues it** - the agent starts on it, nothing to confirm - and `⇧E`
29
+ **stops to review**: its read-back opens so you can check it and add to it first. Both are on the capture bar. `Esc`
30
+ throws it away. One capture records at a time.
31
+
32
+ After `E` the tile reads **Sending** while its last words and pictures come in, then Queued or the agent's state;
33
+ nothing opens and the canvas stays where it is. If the queue cannot take it (rare: another comment already sits
34
+ under its id), it stays on the lane as a draft reading **Not queued** and one line says why - open it to add it to
35
+ the queue. After `⇧E` the tile reads **Finishing**, then **To confirm** as its read-back opens. Either way the capture
36
+ waits for the words you said last: 15 s, longer while the speech engine is still working through them (a minute at
37
+ most). With the microphone on and nothing heard (the speech engine not available, the microphone still opening),
38
+ its record says the words may be incomplete.
29
39
 
30
40
  Closing or reloading the tab asks first while a capture is recording, finishing or not yet taken by the canvas (as it
31
41
  does for any unsaved work). If you leave anyway, the capture
32
42
  is kept as it stood - its words and notes so far, and a line saying the page closed before it finished - and comes
33
- back as a draft to read, resume or drop; it never goes to your agent on its own. (Best effort: a crash gives the page
34
- no chance to keep it.)
43
+ back as a draft to read, resume or drop; it never goes to your agent on its own. One you had already stopped with `E`
44
+ (its tile reading Sending) is queued as `E` does, with that line. (Best effort: a crash gives the page no chance to
45
+ keep it.)
35
46
 
36
47
  A capture the page could not send waits in this browser, for this address, and sends itself the next time the canvas
37
48
  opens there - see [A capture left on an old address](#a-capture-left-on-an-old-address).
@@ -42,7 +53,7 @@ are the frames its run may edit, and the frames pictured before and after it.
42
53
 
43
54
  ## The read-back
44
55
 
45
- When a capture ends, its **read-back** opens: the timeline of what you said and did, with its
56
+ When a capture ends with `⇧E` (and when `J` ends one to wrap the session up), its **read-back** opens: the timeline of what you said and did, with its
46
57
  pictures, under a short name a small model gave it (see [Names](#names)). Read it, fix a
47
58
  mistranscribed word in place, and decide:
48
59
 
@@ -56,7 +67,6 @@ mistranscribed word in place, and decide:
56
67
  A draft's read-back also takes notes after the fact: type in **Add a note** and they are
57
68
  logged under "Added after", in the timeline's style, and go to the agent with the rest.
58
69
 
59
- `jam: { capture: "at-once" }` skips the read-back: a capture queues as soon as it ends.
60
70
 
61
71
  ## The lane
62
72
 
@@ -70,8 +80,11 @@ captures · 6 frames changed" - so the lane keeps its room for what still needs
70
80
  (or `⏎` on it) to open them in place, behind a narrow collapse tile that folds them back.
71
81
 
72
82
  Your agent works on up to `jam.concurrency` captures at once (6 by default), each in its own
73
- run, but never two on the same frame: a capture about a frame another run holds waits for it
74
- ("Queued · next").
83
+ run - your Claude Code session up to 8 more, each in a background subagent of its own - but
84
+ never two runners on the same frame: a capture about a frame another runner holds waits for it,
85
+ and its tile says so ("Waits for 01-slide", the run holding it in its tooltip). One on a frame
86
+ your own session's run is working goes to that session at once, which decides how the two meet
87
+ - after, folded in, or a variant beside it ([Live Jam](live-jam.md#your-own-session-takes-the-work-028)).
75
88
 
76
89
  ## Review
77
90
 
@@ -92,13 +105,25 @@ run - "and this too".
92
105
  When a capture asked for something new beside a frame - "a laptop version of this, next to
93
106
  it" - the frame it pointed at was only where the new one goes. If the run made a new frame
94
107
  and left the one you pointed at unchanged, the capture's thread moves onto the new frame
95
- (when that capture ran alone, so the new frame is surely its own).
108
+ (when that capture ran alone, or its run put the frame on the board with `--run`, so the new frame is surely its own).
96
109
 
97
110
  ## A session: `J`
98
111
 
99
- `J` (or the Jam button in the toolbar) opens the start sheet: what Marver listens to, the
100
- agent the session hands work to, and the keyboard shortcuts. **Start** (`⏎`) begins the
101
- session and its first capture at once.
112
+ `J` (or the Jam button in the toolbar) opens the start sheet: what Marver listens to, who
113
+ works, three switches, and the keyboard shortcuts. **Start** (`⏎`) begins the session and its
114
+ first capture at once.
115
+
116
+ **Who works** (0.28): while the session runs, your tags and captures go to the coding-agent
117
+ session you already have open in the repo - "Your Claude Code session", with everything it
118
+ has. With several open, the newest takes the work; click the row for the next one. With none
119
+ open, a copy of your last session does the run. Claude Code hands each run to a background
120
+ subagent and is free again in seconds, so your captures run side by side; Marver gives Codex
121
+ and Cursor their runs one at a time. Starting the session connects every Claude
122
+ Code, Codex and Cursor session in the repo - nothing else to set up ([Live Jam](live-jam.md#your-own-session-takes-the-work-028)).
123
+ The three switches cover the runs Marver spawns: **MCP servers and skills** (on), **your
124
+ session's context** (on - off means no session and no copy take work, only fresh agents), and
125
+ **collaborators' comments** (off - only your own words reach the agent). They are kept for this
126
+ machine in `design/.local/jam/prefs.json`.
102
127
 
103
128
  While a session runs, the canvas keeps its glowing edge and the Jam button its dot and
104
129
  clock - seconds the first minute, then minutes - and the lane shows **Jam on**, listening
@@ -152,12 +177,12 @@ shows in the review, beside the before and after pictures. The managed instructi
152
177
 
153
178
  ```ts
154
179
  // design/config.ts
155
- jam: { agent: "claude", concurrency: 6, capture: "confirm", chime: true, names: true, loc: true },
180
+ jam: { agent: "claude", concurrency: 6, chime: true, names: true, loc: true },
156
181
  ```
157
182
 
158
183
  | Key | Default | What it does |
159
184
  |---|---|---|
160
- | `capture` | `"confirm"` | `"confirm"`: a capture waits for its read-back. `"at-once"`: it queues at `E` |
185
+ | `capture` | `"confirm"` | No longer used (0.28): `E` queues a capture, `⇧E` stops to review it |
161
186
  | `chime` | `true` | A soft chime when a capture is ready to review |
162
187
  | `names` | `true` | Name each capture with Claude Haiku (Claude Code only) |
163
188
  | `loc` | `true` | Stamp each element of your design files with `data-mv-loc` (dev only, never published) |
@@ -170,7 +195,7 @@ A bad value says so at boot and takes the default; nothing here turns Jam off.
170
195
  | Where | Keys |
171
196
  |---|---|
172
197
  | Anywhere on the canvas | `S` capture · `J` session · `Q` the lane · `V` next to review |
173
- | A capture recording | `E` end · `N` note · `I` picture · `L` laser · `⌥L` inspect · `Esc` drop |
198
+ | A capture recording | `E` stop and queue · `⇧E` stop to review · `N` note · `I` picture · `L` laser · `⌥L` inspect · `Esc` drop |
174
199
  | A read-back | `⏎` add to queue · `K` keep · `R` resume · `Esc` drop |
175
200
  | A review | `⏎` looks good · `⇧⏎` more work · `→` later · `←` back · `B` both/before/after · `⌥←` `⌥→` frames · `Esc` leave |
176
201
  | The lane (`Q`) | `←` `→` move · `⏎` open (or open/fold the Done tile) · `⌘⏎` do next · `K` keep · `⌫` drop · `Esc` leave |
package/docs/live-jam.md CHANGED
@@ -42,6 +42,82 @@ With no agent CLI installed, jam stays off and both `init` and `marver dev` say
42
42
  of going quiet. Workspaces created before 0.9.0 need no re-init; they resolve the same way
43
43
  at every dev boot.
44
44
 
45
+ ## Your own session takes the work (0.28)
46
+
47
+ Start a Jam session on the canvas (`J`, or the Jam button) - that is the one switch. While it runs, your tags and
48
+ captures go to the coding-agent session you already have open in the repo, with its conversation, its tools, your MCP
49
+ servers and skills. When it cannot take a run, a copy of it does; with nothing to copy, a fresh agent with the same
50
+ power. Outside a Jam session, tags go to a background run (a copy of your last session, by default).
51
+
52
+ Nothing to set up. `marver init`, `marver dev` and starting a Jam session write each tool's hooks once, locally -
53
+ `.claude/settings.local.json`, `.codex/hooks.json`, `.cursor/hooks.json` - and keep them out of git (a committed file is
54
+ never changed; one you removed by hand is not written back until you turn that tool on again in the start sheet).
55
+
56
+ | Tool | An idle session | A session at work | A copy of it |
57
+ |---|---|---|---|
58
+ | **Claude Code** | woken through its inbox; it takes the run | reads it between tool calls | `claude -p --resume <id> --fork-session` |
59
+ | **Codex** | a copy of it does the run | its `Stop` hook turns the end of the turn into "run `marver jam next`" | `codex exec fork <id>` |
60
+ | **Cursor** | a full-power Cursor agent does the run | its `stop` hook auto-submits the follow-up | none (Cursor has no fork) |
61
+ | opencode, Grok, droid, pi | background agents | - | - |
62
+
63
+ - **Codex asks you to trust new hooks once** - type `/hooks` in Codex. The start sheet says so while no session is
64
+ connected.
65
+ - **What the session is told**: one line naming the request - "Live Jam: new request from your Marver canvas -
66
+ "Intro frame redesign" (1a2b3c4d) - run `npx marver jam next`" (the same line sent again ends "(again)": Claude
67
+ Code drops a message identical to the one before it). Claude Code shows it in the inbox as a message from another
68
+ session, with a caution that it did not come from you; `design/AGENTS.md` ("Live Jam") tells the agent to expect it and take it as your request.
69
+ - **What the session does** (design/instructions/jam.md, "Runs from the canvas"): `npx marver jam next` takes the run
70
+ and prints a short brief - your request in your words, the frames, how to answer; `jam say <handle> "On it - ..."` posts one line at once; the
71
+ work, with subagents for a capture across frames; `jam progress <handle>` on a long run; `jam done <handle> --file
72
+ <f>` hands back the replies, and the canvas posts them and frees the frames. `jam release` gives a run back,
73
+ `jam status` and `jam mute` are there too. The commands travel through files under `design/.local/jam/`, signed
74
+ with the session's own key, so a sandbox that blocks localhost cannot stop them.
75
+ - **Claude Code dispatches, so it multitasks.** Its brief opens with a few lines for the session - start ONE
76
+ background subagent (the Agent tool, `run_in_background: true`) with the part of the brief below its `----` line and
77
+ what the conversation knows that matters, then `jam next` until nothing waits, and end the turn; every run, however
78
+ small, so the next request never waits behind one - and below the line
79
+ the subagent's own prompt: it owns that run, never takes another, says "On it", works and hands it back itself. A
80
+ subagent's commands carry the session's id, so they speak for its connection; one that cannot reach it adds the
81
+ `--as <id>` its prompt names. Your session is free again in seconds, so several runs go at once: a Claude Code
82
+ session holds up to 8 (Codex and Cursor 3 - Marver gives them their runs one at a time; `jam.sessionMax` caps every
83
+ session), and runs a session holds do not count against `jam.concurrency`, which caps only the runs Marver starts. A
84
+ background subagent's built-in tools can be fewer than the session's, and a permission it needs is asked in the
85
+ session. When you move a run elsewhere, the session is told to stop the subagent on it first, so nothing edits its
86
+ frames once it is released.
87
+ - **Two requests on one frame.** One frame never has two runners - except two runs of your own session: a request on a
88
+ frame your session's run is working is offered to it at once, its ping naming the run it overlaps ("overlaps your
89
+ run r-1a2b3c4d.1"). The session decides: send it to the subagent on that frame, to do after or fold in now, or make it
90
+ a variant in a new frame placed beside it (`boards place --run`). A run your session lets go of while another of its
91
+ runs holds the frame goes back to the queue and waits for the frame; a frame any other runner holds - a copy, a fresh
92
+ agent, your agent in chat - makes the request wait, and its tile says "Waits for <frame>".
93
+ - **A request with no frame** - a capture made on an empty board, a comment on the board itself, the session record -
94
+ goes to your session beside your other runs, in a slot of your session's: with your session full, its tile says
95
+ "Waits · your session is full" until it has room or you choose another session. A capture or a comment reserves no
96
+ frame: it makes what it asks for as new frames, each put on the board with `--run <handle>` (`boards pin <board>
97
+ <scene/frame> --run <handle>` on an empty board). The session record writes its one file and nothing else. With no
98
+ session taking the work it runs alone, as before - a run Marver starts finds the frames it made only when nothing runs
99
+ beside it - and so does one your session does not take or lets go of. Its tile says "Waits to run alone", and the
100
+ requests behind it "Waits · a run goes alone first". Once its run has put a frame on the board it holds that frame, and
101
+ from then on - let go of by your session, retried or tagged again - it is a request on that frame like any other.
102
+ - **Frames placed through Marver.** A run puts a frame next to another with `npx marver boards place <board>
103
+ <scene/frame> --after|--before <scene/frame>` (`--run <handle>`: the new frame is that run's, and its review pictures
104
+ it) - never by editing the board file. A request that still needs a file no run is given (a board file, the comment
105
+ logs, local state, a frame outside its run) comes back to you as a question saying which and why, never as "the
106
+ agent did not answer".
107
+ - **Who works** shows in the start sheet - with several sessions open, the newest takes the work and one click picks
108
+ another - and on every run's tile: "Dispatching" until your session takes it, then "Claude Code is working" (or
109
+ "Codex is working", "Agent is working"). Hover the tile for whose run it is - your session, a copy of it and why a
110
+ copy took it, or a background run; the run's status in its thread says the same.
111
+ - **An offer not taken** - Claude Code not pulling it in 2 minutes, a Codex or Cursor turn ending without taking it -
112
+ goes to a copy or a fresh agent. **A run your session took and went quiet on** for 15 minutes is stalled: give it
113
+ back, run it in the background, or drop it (the tag's status, or the tile's menu). The last two wait for your session
114
+ to let go - it is told to stop, its late `done` is refused, and the frames stay reserved until it releases the run or
115
+ its process is gone.
116
+
117
+ The start sheet's switches: **MCP servers and skills** (on) and **your session's context** (on) for the runs Marver
118
+ spawns, and **collaborators' comments** (off: only your own words reach any runner). Your own session keeps the tools
119
+ you gave it; with context off, no session and no copy take work - fresh agents only.
120
+
45
121
  ## The config block
46
122
 
47
123
  ```ts
@@ -54,10 +130,17 @@ jam: { agent: "claude", concurrency: 6 },
54
130
  | `agent` | detected | The CLI the daemon spawns: `"claude"`, `"codex"`, `"cursor"`, `"droid"`, `"opencode"`, `"grok"`, or `"pi"` |
55
131
  | `concurrency` | `6` | Frames worked on at once (1-16). The same frame never gets two agents |
56
132
  | `subagents` | `true` | Inside one job, fan out one subagent per frame |
57
- | `capture` | `"confirm"` | A capture waits for its read-back, or `"at-once"` queues at `E` ([captures](jam-session.md#configuration)) |
133
+ | `capture` | `"confirm"` | No longer used (0.28): `E` queues a capture, `⇧E` stops to review it ([captures](jam-session.md#configuration)) |
58
134
  | `chime` | `true` | A soft chime when a capture is ready to review |
59
135
  | `names` | `true` | Name each capture with Claude Haiku through Claude Code - its words go to Anthropic (Claude Code only) |
60
136
  | `loc` | `true` | Stamp design elements with `data-mv-loc` (file and line, dev only) so the agent goes straight to the source |
137
+ | `runner` | `"auto"` | Who runs a batch: `"auto"` - your session during a Jam session, else a copy of it, else a fresh agent; `"session"` - wait for a session, never fall back; `"background"` - never a session |
138
+ | `session` | `true` | Connect this repo's Claude Code, Codex and Cursor sessions (their hooks). `false`: none are written, and existing ones go quiet |
139
+ | `context` | `"fork"` | Background runs copy your session; `"fresh"` starts them fresh (and no session takes work) |
140
+ | `mcp` | `true` | Background runs use your MCP servers |
141
+ | `skills` | `true` | Background runs use your skills |
142
+ | `others` | `false` | Other people's words reach the agent, labelled; off: only yours |
143
+ | `sessionMax` | unset | Runs one session holds at once - unset: 8 for Claude Code (it dispatches each to a background subagent), 3 for Codex and Cursor; set, it caps every session |
61
144
 
62
145
  Shorthands: `jam: "codex"` names the agent and takes the rest of the defaults, `jam: true`
63
146
  is the default block, and **`jam: false` is the off switch**.
@@ -71,18 +154,17 @@ that fails to parse also leaves jam off, since it may have been the file that sa
71
154
  ## What the agent may do
72
155
 
73
156
  Be clear-eyed about what this is. The real protection is not a sandbox - it is that the
74
- agent doing the work is **your own**, running on **your machine**, and **every change it
75
- makes is a diff you review** before anything is resolved. On top of that, marver removes the
76
- one tool that would turn a prompt-injected comment into silent damage: an unrestricted
77
- **shell**. Each CLI is spawned so the model can read and edit files but cannot open a shell
78
- (or, for Codex and Cursor, only a shell the OS sandbox contains and cuts off from the
79
- network):
157
+ agent doing the work is **your own**, running on **your machine**, that **only your own words
158
+ reach it** by default, and that **every change it makes is a diff you review** before anything
159
+ is resolved. Since 0.28 a run Marver spawns for Claude Code, Codex or Cursor has full power -
160
+ the shell inside the tool's own sandbox, your MCP servers and skills, a copy of your session -
161
+ because a lesser agent was the wrong trade; the other CLIs keep their jails:
80
162
 
81
163
  | | How it is spawned |
82
164
  |---|---|
83
- | **Claude Code** | `claude -p --permission-mode acceptEdits` with an allowlist of Read, Edit, Write, Glob, Grep, WebSearch, WebFetch - and `--disallowedTools Bash`, so there is no shell |
84
- | **Codex** | `codex exec -s workspace-write`, its own OS sandbox, which bounds what commands touch and blocks network egress, but still lets the model run shell commands |
85
- | **Cursor** | `cursor-agent -p --sandbox enabled --trust` - cursor's print mode carries a shell, so like Codex it runs inside the OS sandbox (verified: network egress is blocked); `--trust` only answers the workspace-trust prompt for the repo you already run `marver dev` in, and `--force` is never passed |
165
+ | **Claude Code** | `claude -p --permission-mode acceptEdits`; Bash runs in Claude Code's sandbox (writes in the repo, no network, `~/.ssh`, `~/.aws`, `~/.gnupg` and keychains unreadable - for the Read tool too - and no way out of the sandbox); every other permission question goes to `marver jam permit`, Marver's small MCP server named with `--permission-prompt-tool`: MCP tools and skills when on, the web, subagents and edits inside the repo are allowed, the rest refused, nobody is asked. A copy adds `--resume <id> --fork-session`; MCP off adds `--strict-mcp-config`, skills off `--disable-slash-commands` |
166
+ | **Codex** | `codex exec --approve-for-me` (Codex's own automatic reviewer answers approvals - MCP calls included - inside `workspace-write`, no network for the shell); a copy is `codex exec fork <id>` with the same settings; MCP off turns each server `codex mcp list` names off. Codex's sandbox does not limit reads: the shell has no network, and the reviewer judges what leaves |
167
+ | **Cursor** | `cursor-agent -p --sandbox enabled --trust`, plus `--approve-mcps` with MCP on - the shell runs inside the OS sandbox (network egress blocked); `--trust` only answers the workspace-trust prompt for the repo you already run `marver dev` in, and `--force` is never passed. Cursor's skills and already-approved MCP servers follow your own Cursor setup |
86
168
  | **droid** | `droid exec --auto low` for file edits, with `--disabled-tools` removing the shell (`Execute`), the delegation tools (`Task`, missions), and the Slack/connector tools |
87
169
  | **opencode** | `opencode run --pure` (no external plugins) with a per-run DEFAULT-DENY `OPENCODE_PERMISSION` grant - read/edit/search/web/task allowed by name, everything else (bash included) denied - never its all-approving `--auto` flag |
88
170
  | **grok** | `grok -p --tools read_file,search_replace,list_dir,grep,todo_write` - an ALLOWLIST of read/edit tools only, so the shell, web, and subagents are simply absent (a deny-list is a footgun: it can miss a tool's real name); `--permission-mode acceptEdits` auto-applies the edits |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@marver-design/marver",
3
- "version": "0.27.2",
3
+ "version": "0.28.0",
4
4
  "description": "The agent-native design canvas. A design/ folder, one command, a canvas of live frames built from your repo's real components - comment @marver and your own coding agent does the work. The tool ships no AI.",
5
5
  "type": "module",
6
6
  "private": false,