kaizen-agent 1.67.0 → 1.69.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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "kaizen-agent",
3
- "version": "1.67.0",
3
+ "version": "1.69.0",
4
4
  "description": "Staged workflow for AI agents — code, writing, research, operations: plan, human approval, build, independent review, bounded fix loop.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -58,6 +58,7 @@
58
58
  "@lezer/highlight": "1.2.5",
59
59
  "@xterm/addon-fit": "0.11.0",
60
60
  "@xterm/addon-search": "0.16.0",
61
+ "@xterm/addon-unicode11": "0.9.0",
61
62
  "@xterm/addon-web-links": "0.12.0",
62
63
  "@xterm/addon-webgl": "0.19.0",
63
64
  "@xterm/xterm": "6.0.0",
@@ -110,9 +110,8 @@ A tool that charges the same for a typo and a payroll change gets turned off for
110
110
  files or fifty lines, run the stages in this session (`runner: lite`, below)
111
111
  rather than dispatching them. Keep the plan and review brief, then apply the same
112
112
  bounded fix loop to review findings. Small size does not leave a finding for a later
113
- run when it can be fixed within this one.
114
-
115
- **Short work still gets a run.** A one-line change is not skipped past the stages: the card on the board moves through plan, build and review like any other. Run it with `runner: lite` and the short path above — a brief plan, the build, a short review — so the cost stays small and the run stays visible.
113
+ run when it can be fixed within this one. Even a one-line change gets a run this way,
114
+ so its card still moves through plan, build and review.
116
115
 
117
116
  This is a judgement, not a threshold to enforce: fifty lines that change how money is
118
117
  rounded are not a small change. Say which path you took (short or full) and why, in one line, when the
@@ -128,7 +127,8 @@ Set by `mode` in config, overridable per invocation.
128
127
  - **`approve`** (default) — stop at every approval enabled in config and wait for an
129
128
  explicit human decision.
130
129
  - **`auto`** — run every stage back to back with no approval, report at the end. The fix
131
- loop still respects `max_iterations`.
130
+ loop still respects `max_iterations`, and `auto_guard` stops a run that changed too
131
+ many files or kept a serious finding (*Auto guard* in `spec-main.md`).
132
132
  - **`review-only`** — skip plan and implementation, run the reviewer against existing
133
133
  code or a diff.
134
134
 
@@ -247,19 +247,13 @@ final report, so nobody reads a same-session review as an independent one.
247
247
 
248
248
  ## Running a stage
249
249
 
250
- **If the tool you are running in has no subagents** — Codex, and anything else that
251
- runs one session at a time — do not try to fake them. Run the stages sequentially in
252
- the one session, following [`adapters.md`](adapters.md): start each stage by reading
253
- only its declared inputs, write its artifact before moving on, and when reviewing,
254
- judge the work on its own terms rather than defending the reasoning you used writing
255
- it. Everything else in this file holds unchanged.
256
-
257
- **Check `runner` first.**
250
+ **Check `runner` first.** A tool with no subagents (Codex, anything that runs one
251
+ session at a time) runs as `lite` whatever the setting, following
252
+ [`adapters.md`](adapters.md); do not fake subagents.
258
253
 
259
- - `runner: lite` — do not call the Agent tool, except for the review as below. You run plan, build and review
260
- yourself, in that order, reading only each stage's declared inputs and writing its
261
- artifact before starting the next. The stage table below still applies; you are the
262
- agent for every row.
254
+ - `runner: lite` — do not call the Agent tool, except for the review as below. You run
255
+ plan, build and review yourself, as *Who runs the stages* says; the stage table below
256
+ still applies, and you are the agent for every row.
263
257
  Read `spec-build.md` before building and `spec-main.md` before moving the run to
264
258
  `review`: being the main thread does not excuse a stage its contract. Its *Preview
265
259
  gate* holds in full — a result that shows on a screen needs a real screenshot under
@@ -296,7 +290,7 @@ knob: when it is not `inherit`, make sure the frontmatter of the agent's definit
296
290
  carries `effort: <value>` — edit or add that one line, nothing else — before the
297
291
  first dispatch of the run. `inherit` means leave the file alone.
298
292
 
299
- After a subagent returns, update `state.json` yourself in the main thread. Subagents
293
+ After a subagent returns, update `state.json` yourself in the main thread, with `kaizen state` from 1.69.0, by hand before that (`spec.md`, Stage 0). Subagents
300
294
  report; the main thread owns the state machine.
301
295
  Before moving any run from `build` to `review`, under either runner, apply the
302
296
  *Preview gate* in [`spec-main.md`](spec-main.md): no `## Preview` with a screenshot
@@ -351,28 +345,10 @@ shown automatically.
351
345
  state.json
352
346
  ```
353
347
 
354
- `state.json` is the resume point, and records the runner and the agent the run started with, so a
355
- run picked up later keeps the shape it was reviewed under rather than silently
356
- changing because a setting moved:
357
-
358
- ```json
359
- {
360
- "id": "2026-09-02-add-oauth",
361
- "mode": "approve",
362
- "runner": "full",
363
- "agent": "claude",
364
- "stage": "review",
365
- "awaiting": "approvals.review",
366
- "iteration": 1,
367
- "updated": "2026-09-02T14:31:00+07:00"
368
- }
369
- ```
370
-
371
- Every run writes all nine keys, from intake on: `id`, `mode`, `runner`, `agent`,
372
- `track`, `stage`, `awaiting`, `iteration` (0 until the fix loop runs), `updated`. Where
373
- the environment has `CLAUDE_CODE_SESSION_ID`, also `session` with its value: without it
374
- a card launched from the board can stay stuck in planning beside its own run. The
375
- legal values of `stage` and `awaiting` are in [`spec.md`](spec.md).
348
+ `state.json` is the resume point. Its keys (all nine from intake on, plus `session`
349
+ where `CLAUDE_CODE_SESSION_ID` is set, and `review_executor` on a lite run), their legal
350
+ values, and why `runner` and `agent` are frozen at intake are in *Stage 0* of
351
+ [`spec.md`](spec.md), with when to write it through `kaizen state` (1.69.0 and later) and when by hand.
376
352
 
377
353
  In a git repository, `init` also adds a gitignore entry that ignores run state but
378
354
  keeps the workflow: it ignores `.kaizen/*` and un-ignores `.kaizen/spec*.md` and
@@ -62,6 +62,16 @@ auto_fix:
62
62
  # knob in the file. A third round rarely closes what two could not.
63
63
  max_iterations: 2
64
64
 
65
+ # Stops for auto mode only (mode: auto); approve mode already stops at every approval.
66
+ # Auto runs every stage back to back, so these are what bring a runaway run back to you:
67
+ # the run stops at the final approval with the reason instead of finishing.
68
+ auto_guard:
69
+ # Stop when the build changed more files than this. 0 turns this check off.
70
+ max_files: 25
71
+ # Stop when a finding at or above this severity is still open after the fix loop.
72
+ # critical | high | medium | low | off
73
+ stop_on: high
74
+
65
75
  review:
66
76
  # Who reviews a lite run. Only read when runner is lite; under full the reviewer is
67
77
  # always its own agent.
@@ -188,6 +198,10 @@ agent:
188
198
  # (tmux -L kaizen, your own sessions untouched) and keep working through
189
199
  # a kaizen restart or crash; the next kaizen shows them again mid-step.
190
200
  # Linux and macOS with tmux installed; elsewhere it acts as off.
201
+ # On Linux with systemd the server gets a scope of its own, so it also
202
+ # outlives a stop or restart of a systemd unit that runs kaizen. Through
203
+ # a logout only with lingering on: loginctl enable-linger.
204
+ # The wheel scrolls tmux's history; Shift+drag selects text to copy.
191
205
  keep_alive: off
192
206
  # Stops idle sleep from kaizen. off | auto (while kaizen runs agents) | on
193
207
  # (while kaizen is open). Linux and macOS; agents in an outside terminal don't count.
@@ -139,7 +139,10 @@ success poisons the review stage, which trusts this report.
139
139
 
140
140
  **A `## Preview` section says how to see the result.** For an app or service: the
141
141
  commands to start it locally and the URL to open, copied from the material's own README
142
- where one exists. For anything else — a document, copy, a runbook, a memo — the path
142
+ where one exists. An app with a dev server: leave it running when the build ends
143
+ (started in the background, its log in a file), and write its full `http://localhost:<port>`
144
+ address here; the board's Browser opens that address on its own, a phone included, and
145
+ its Preview button starts the folder's `dev` script when the server has stopped. For anything else — a document, copy, a runbook, a memo — the path
143
146
  to open, or the result itself when it fits in a screen. The board shows this section on
144
147
  the run's card, so a person can try the work without reading the rest of the report.
145
148
  Every run whose result shows on a screen must put at least one screenshot of it here,
@@ -206,6 +209,12 @@ be run, opened, or read by someone, doing so is part of building it: the suite r
206
209
  the page opened and clicked, the runbook walked start to finish, the copy read aloud.
207
210
  A gate item whose evidence is an argument that the code should work is a `FAIL`.
208
211
 
212
+ Then check the request itself, as the reviewer will: each requirement in the verbatim
213
+ request and its *done* and *wrong* lines in `00-request.md` that no `G-nn` covers gets a
214
+ line `R PASS: <what was tried and what came back>` or `R FAIL: <what>`. The reviewer
215
+ writes its own criteria cold and trusts none of these; they exist so a gap the plan
216
+ missed is found here instead of costing a fix round.
217
+
209
218
  The stage does not hand off with a `FAIL` standing. Fix it and re-run the gate, or —
210
219
  if it cannot be fixed inside the plan's scope — stop and report, exactly as with an
211
220
  impossible step. A `FAIL` carried into review wastes the reviewer's pass on something
@@ -153,6 +153,18 @@ whose changes leave every note true touches nothing and says so in one line.
153
153
 
154
154
  ---
155
155
 
156
+ ## Auto guard
157
+
158
+ Only in `auto` mode. After the fix loop ends and before the final approval, check
159
+ `auto_guard` from config: the build changed more files than `max_files` (count the
160
+ changed paths `03-impl.md` names; `0` turns this off), or a finding at or above
161
+ `stop_on` is still open (`off` turns this off). Either way, stop: `kaizen state <id>
162
+ awaiting=approvals.review` (by hand before 1.69.0), and tell the user in one line which
163
+ check fired. The run then waits for an explicit accept as in *Final approval*, even with
164
+ `auto_accept` on. Neither check fires in `approve` mode, which already stops.
165
+
166
+ ---
167
+
156
168
  ## Final approval
157
169
 
158
170
  Controlled by `approvals.review`. `auto` skips every stop before it, not this one, unless `auto_accept` is on.
@@ -14,7 +14,10 @@ notes it lists for areas the request touches — the output of
14
14
  `kaizen recall --track <track> --tags <stack tags> --query "<words from the request>"`
15
15
  — past experience from other projects, to verify against this one, never binding
16
16
  like project rules; the Framing ends with `Recalled: <n> lessons; used: <the lines it
17
- relied on>` or `Recalled: none` — and the existing material —
17
+ relied on>` or `Recalled: none` — the output of `kaizen related <the File manifest's
18
+ paths>` (1.69.0 and later): earlier runs that changed those files, whose plans, findings
19
+ and open backlog may bear on this one; the Framing adds `Related: <ids it used>` or
20
+ `Related: none` — and the existing material —
18
21
  the codebase, the manuscript, the current campaign, whatever this run builds on.
19
22
  **Output:** `01-plan.md`.
20
23
 
@@ -207,6 +210,13 @@ The planner reads code but writes none. Its plan must contain:
207
210
  Reviewer severity `medium`.
208
211
  - **lock** — consistency with what is already there. Reviewer severity `low`.
209
212
 
213
+ End every item with `— proof: <how>`: the test or command to run, the screenshot to
214
+ take, the source to check a claim against, the person who reads it. The builder
215
+ produces that proof and the reviewer re-runs it, so a check nobody can run is found
216
+ at the approval rather than as `CANNOT VERIFY` after the build. Where the only proof
217
+ needs something no agent has (a live account, a real device, taste), say so in the
218
+ proof: it is a human check from the start.
219
+
210
220
  Phrase every item so the answer is yes or no. "Handles errors well" is not a gate
211
221
  item; "every new query path has a covering test" is. A tier fixes the severity
212
222
  before the reviewer has an opinion, which is what stops the same class of problem
@@ -111,6 +111,10 @@ G-02 FAIL: see finding 3
111
111
  R-01 CANNOT VERIFY: needs a live Stripe account; the test-mode fixture skips webhooks. Human: refund one real charge and confirm the ledger row.
112
112
  ```
113
113
 
114
+ A `G-nn` item's `— proof:` is the first check to run. `CANNOT VERIFY` on an item
115
+ whose proof the reviewer could run is not an answer: run it. Where the plan already
116
+ marked the proof a human check, `CANNOT VERIFY` is expected and names that check.
117
+
114
118
  `CANNOT VERIFY` is for a check that needs something the reviewer does not have —
115
119
  taste, a live account or device, a real reader, production data, a person's decision.
116
120
  It states what was tried, why that does not settle it, and exactly what a human must
@@ -132,7 +136,10 @@ human check never reads as a clean pass.
132
136
  Where `review.write_memory` is true (the default), the reviewer also appends any
133
137
  durable lesson about this material to `memory.md` —
134
138
  a recurring bug pattern, a non-obvious constraint, a convention worth keeping. Not
135
- run-specific detail; only what the next run would want to know.
139
+ run-specific detail; only what the next run would want to know. Where the state
140
+ directory has `notes/Project/Index.md`, a lesson about one area's files goes to that
141
+ area's note under `## Watch out` instead, since planners open only the notes for the
142
+ areas they touch; `memory.md` keeps the lessons that hold across the project.
136
143
 
137
144
  `memory.md` is read by every stage of every future run, so its size is a tax on all of
138
145
  them. Keep it under `review.memory_max_lines` (default 100): before appending, drop
@@ -73,7 +73,9 @@ connected in the session: cite what it returns, limitations included. When they
73
73
  not connected, say the claim is unverified rather than guess at internals.
74
74
 
75
75
  Record the track in `state.json` as `track`, with the three answers written into
76
- `00-request.md`. Every subsequent stage reads them before starting, and the words
76
+ `00-request.md`. The description stays free; the stored `track` word is the nearest of
77
+ `code`, `writing`, `communication`, `operations`, `research`, or a new word where none
78
+ fits (a mix joined with `+`), because `kaizen recall --track` looks lessons up by it. Every subsequent stage reads them before starting, and the words
77
79
  *build*, *verify*, and *finding* below are always to be read in the track's terms.
78
80
 
79
81
  ---
@@ -123,6 +125,12 @@ is building and a recheck is reviewing, whoever runs them and whether the loop o
123
125
  user picked the findings: `build` with `iteration` raised and `awaiting: null` before
124
126
  each iteration's first edit, `review` before its recheck reads. Any other word
125
127
  (`implement`, `fix`, `building`) is unknown to every reader and shows as still planning.
128
+ After intake, where `kaizen --version` prints 1.69.0 or later, write these keys with
129
+ `kaizen state <id> stage=build awaiting=null` (`iteration=<n>` likewise): one atomic
130
+ write that refuses unknown words and stamps `updated`. An older `kaizen` reads `state`
131
+ as a plain `kaizen` call and starts the installer, so there, and where no `kaizen` is
132
+ installed, edit `state.json` by hand in its two-space JSON layout. Finish with
133
+ `kaizen done <id>` either way.
126
134
 
127
135
  `awaiting` is `null` or the config key of the approval being waited on —
128
136
  `approvals.plan`, `approvals.review`, `approvals.each_file` — or `findings` when the
@@ -28,6 +28,9 @@ anything.
28
28
  | `/kaizen review [target]` | Review-only: audit existing code, no plan, no implementation |
29
29
  | `/kaizen status` | List every run grouped waiting-on-you / in flight / done / abandoned, plus open backlog count |
30
30
  | `kaizen done <id> [--user-approved]` | Finish a run; refused while the review gate waits on the user, `--user-approved` after a clear yes in chat |
31
+ | `kaizen state <id> key=value ...` | (1.69.0+) Set a run's `stage`, `awaiting` or `iteration` in `state.json`; refuses words no board knows (`done` goes through `kaizen done`) |
32
+ | `kaizen stats [<id>] [--json]` | (1.69.0+) Fix-round and CANNOT VERIFY rates, stage times, tokens for one run |
33
+ | `kaizen related <path> ...` | (1.69.0+) Earlier runs that changed these files |
31
34
  | `/kaizen backlog` | Print open backlog items across all runs, grouped by source run, rescued items last under `Orphaned` |
32
35
  | `/kaizen gather` | Read request sources kaizen cannot read by itself; their requests land in the icebox, nothing starts |
33
36
  | `/kaizen discover` | Group what is in the icebox and promote the tasks you pick; nothing starts |
@@ -1,15 +1,16 @@
1
- // First-run onboarding: one panel over the board with three steps (default agent, look,
2
- // notifications), then "Add your first project". Where a user got to is kept by the board in
1
+ // First-run onboarding: one panel over the board with four steps (default agent, look,
2
+ // notifications, phone), then "Add your first project". Where a user got to is kept by the board in
3
3
  // ~/.kaizen/onboarding.json (/onboarding), so a skipped or half-done flow can be continued from the
4
4
  // side menu's Setup row or the "Continue setup?" popup. Existing users, who have a project, never see it.
5
5
  import { html, raw } from "./dom.ts";
6
6
  import { openAdd } from "./add-project.ts";
7
+ import { mountPhone } from "./phone-setup.ts";
7
8
 
8
9
  type Cfg = { show: boolean; resume: boolean; step: number; total: number; default: string; installed: string[]; agents: { cmd: string; name: string }[]; install: Record<string, { command?: string; docs: string }> };
9
10
  // The tools agent.default accepts.
10
11
  const PICKABLE = ["claude", "codex", "agy", "opencode", "gemini"];
11
12
  const MOD = /Mac|iP(hone|ad)/.test(navigator.platform) ? "⌘" : "Ctrl";
12
- const NAMES = ["Default agent", "Appearance", "Notifications"];
13
+ const NAMES = ["Default agent", "Appearance", "Notifications", "Phone"];
13
14
  const ASKED = "kz-onb-asked";
14
15
 
15
16
  async function call(path: string, body?: object) {
@@ -30,7 +31,7 @@ let more = false;
30
31
 
31
32
  // The side menu's Setup row follows what is saved.
32
33
  const row = (s: number, outcome: string | null) =>
33
- (window as any).kzSetupRow?.({ resume: outcome === "skipped" || (outcome === null && s > 0), step: s, total: cfg?.total ?? 3 });
34
+ (window as any).kzSetupRow?.({ resume: outcome === "skipped" || (outcome === null && s > 0), step: s, total: cfg?.total ?? 4 });
34
35
 
35
36
  const save = (patch: { step?: number; outcome?: string | null }) => {
36
37
  row(patch.step ?? step, patch.outcome ?? null);
@@ -89,6 +90,7 @@ const COPY = [
89
90
  { title: "Pick your default agent", sub: "kaizen works with every CLI agent. Choose the one you will reach for most. You can change it any time in Settings.", body: agents },
90
91
  { title: "Choose your look", sub: "Follow your system, or pick light or dark. You can change it any time.", body: looks },
91
92
  { title: "Set up notifications", sub: "kaizen can tell you when a run needs you or an agent is done.", body: alerts },
93
+ { title: "Use kaizen on your phone", sub: "Optional. Check runs and answer agents from your phone. Continue to skip; it is also in Settings → Mobile.", body: () => html`<div class="onb-panel" id="onb-phone"></div>` },
92
94
  ];
93
95
 
94
96
  function draw() {
@@ -102,6 +104,8 @@ function draw() {
102
104
  <div class="onb-prog">${COPY.map((_, i) => html`<button type="button" class="${i === step ? "on" : i < step ? "was" : ""}" data-s="${i}" aria-label="Go to step ${i + 1}: ${NAMES[i]}" title="${NAMES[i]}"></button>`)}<span>${step + 1} of ${c.total}</span></div>
103
105
  <div class="onb-main">${step === 0 ? html`<small class="onb-eb">Welcome to kaizen</small>` : ""}<h2>${s.title}</h2><p class="onb-sub">${s.sub}</p>${s.body()}</div>
104
106
  <div class="onb-ft"><button type="button" class="onb-lnk" data-a="skip">Skip to project setup</button><span></span>${step > 0 ? html`<button type="button" class="btn" data-a="back">‹ Back</button>` : ""}<button type="button" class="btn pri" data-a="next">${last ? "Add your first project" : "Continue"}<kbd>${MOD} ↵</kbd></button></div>`);
107
+ const ph = dlg!.querySelector<HTMLElement>("#onb-phone");
108
+ if (ph) void mountPhone(ph);
105
109
  dlg!.querySelector<HTMLElement>(step === 0 ? ".onb-card[aria-checked=true]" : "[data-a=next]")?.focus();
106
110
  }
107
111
 
@@ -0,0 +1,79 @@
1
+ // The phone card: Settings → Mobile and the onboarding phone step. Walks the user from no
2
+ // Tailscale to a QR the phone scans, through /phone/setup on the board.
3
+ import { html, raw } from "./dom.ts";
4
+
5
+ type State = { state: "missing" | "login" | "ready" | "connected"; account: string; url: string; phones: { name: string; online: boolean }[]; qr: string };
6
+
7
+ const DOWNLOAD = "https://tailscale.com/download";
8
+
9
+ async function call(body?: object) {
10
+ try {
11
+ const r = await fetch("/phone/setup", body ? { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body) } : undefined);
12
+ return await r.json();
13
+ } catch {
14
+ return { error: "The board did not answer." };
15
+ }
16
+ }
17
+
18
+ const btn = (a: string, text: string, pri = false) => html`<button type="button" class="btn${pri ? " pri" : ""}" data-ph="${a}">${text}</button>`;
19
+ const ol = (items: unknown[]) => html`<ol class="ph-steps">${items.map((i) => html`<li>${i}</li>`)}</ol>`;
20
+
21
+ function body(s: State, err: string, busy: boolean) {
22
+ const e = err ? html`<p class="ph-err" role="alert">${err}</p>` : "";
23
+ const acct = s.account ? html`<b>${s.account}</b>` : "the same account";
24
+ if (s.state === "missing")
25
+ return html`<p>Your phone reaches this computer through Tailscale, a free private network between your own devices.</p>${ol([
26
+ "Install Tailscale on this computer and log in.",
27
+ "Install it on your phone too and log in with the same account.",
28
+ ])}<div class="ph-row"><a class="btn pri" href="${DOWNLOAD}" target="_blank" rel="noopener">Install Tailscale</a>${btn("check", "Check again")}</div>${e}`;
29
+ if (s.state === "login")
30
+ return html`<p>Tailscale is installed but not logged in on this computer.</p><div class="ph-row">${btn("login", busy ? "Opening…" : "Log in to Tailscale", true)}${btn("check", "Check again")}</div>${e}`;
31
+ if (s.state === "ready")
32
+ return html`<p>Tailscale is running${s.account ? html` as ${acct}` : ""}. Connect to show the code your phone scans.</p><div class="ph-row">${btn("connect", busy ? "Connecting…" : "Connect phone", true)}</div>${e}`;
33
+ const on = s.phones.some((p) => p.online);
34
+ return html`<div class="ph-on">${s.qr ? html`<div class="ph-qr" aria-label="QR code for ${s.url}">${raw(s.qr)}</div>` : ""}<div><p class="ph-h">On your phone</p>${ol([
35
+ html`Install Tailscale from the <a href="${DOWNLOAD}" target="_blank" rel="noopener">App Store or Play Store</a>.`,
36
+ s.account ? html`Log in with ${acct}, the account this computer uses.` : "Log in with the same account as this computer.",
37
+ html`Scan this code with the camera, or open <a href="${s.url}" target="_blank" rel="noopener">${s.url}</a>.`,
38
+ "Choose Add to Home screen so it opens like an app.",
39
+ ])}<p class="ph-st"><i class="ph-dot${on ? " on" : ""}"></i>${on ? `Phone online: ${s.phones.filter((p) => p.online).map((p) => p.name).join(", ")}` : s.phones.length ? "Phone on your tailnet, offline right now" : "No phone on your tailnet yet"}</p></div></div><p class="ph-note">Anyone on your tailnet can use this board. Keep the tailnet to your own devices, or limit it with Tailscale access rules.</p>${e}`;
40
+ }
41
+
42
+ // Draws into `el` and keeps it current while it is on the page.
43
+ export async function mountPhone(el: HTMLElement) {
44
+ let s: State | null = null, err = "", busy = false;
45
+ const draw = () => {
46
+ if (s) el.innerHTML = String(body(s, err, busy));
47
+ };
48
+ const load = async () => {
49
+ const r = await call();
50
+ if (r.error) err = r.error;
51
+ else s = r;
52
+ draw();
53
+ };
54
+ el.innerHTML = `<p class="ph-wait">Checking Tailscale…</p>`;
55
+ el.onclick = async (ev) => {
56
+ const a = (ev.target as HTMLElement).closest<HTMLElement>("[data-ph]")?.dataset.ph;
57
+ if (!a || busy) return;
58
+ err = "";
59
+ if (a === "check") return load();
60
+ busy = true;
61
+ draw();
62
+ const r = await call({ do: a });
63
+ busy = false;
64
+ if (r.error) err = r.error;
65
+ else if (a === "login") {
66
+ if (r.url) window.open(r.url, "_blank", "noopener");
67
+ // The sign-in happens in the browser: look again until Tailscale is running, for two minutes.
68
+ for (let i = 0; i < 40 && el.isConnected && s?.state === "login"; i++) {
69
+ await new Promise((ok) => setTimeout(ok, 3000));
70
+ const n = await call();
71
+ if (!n.error) s = n;
72
+ }
73
+ } else s = r;
74
+ draw();
75
+ };
76
+ await load();
77
+ // The phone's dot follows it joining the tailnet; stops once the card leaves the page.
78
+ const t = setInterval(() => (el.isConnected ? s?.state === "connected" && !busy && void load() : clearInterval(t)), 10_000);
79
+ }
@@ -243,7 +243,7 @@ function draw() {
243
243
  first = item(ids[0]),
244
244
  title = ids.map((id) => item(id).title).join(" + ");
245
245
  return html`<button class="rtab${sc.id === s.on ? " on" : ""}" data-t="${sc.id}" draggable="true" title="${title}">${icon(first)}<span>${title}</span><i data-xs="${sc.id}" role="button" aria-label="Close ${title}" title="Close tab">×</i></button>`;
246
- })}<details class="radd" data-mode="tab"><summary class="rbtn" title="New tab" aria-label="New tab">${ico("plus")}</summary>${menu}</details><span class="sp"></span>${cur ? html`<details class="radd rsplit" data-mode="cols"><summary class="rbtn" title="Split right: add to this tab" aria-label="Split right">${ico("lcols")}</summary>${menu}</details><details class="radd rsplit" data-mode="rows"><summary class="rbtn" title="Split down: add to this tab" aria-label="Split down">${ico("lrows")}</summary>${menu}</details>` : ""}`,
246
+ })}<details class="radd" data-mode="tab"><summary class="rbtn" title="New tab" aria-label="New tab">${ico("plus")}</summary>${menu}</details><button type="button" class="rbtn" data-pv title="Preview: open the app, starting its dev server if it is off" aria-label="Preview">${ico("eye")}</button><span class="sp"></span>${cur ? html`<details class="radd rsplit" data-mode="cols"><summary class="rbtn" title="Split right: add to this tab" aria-label="Split right">${ico("lcols")}</summary>${menu}</details><details class="radd rsplit" data-mode="rows"><summary class="rbtn" title="Split down: add to this tab" aria-label="Split down">${ico("lrows")}</summary>${menu}</details>` : ""}`,
247
247
  );
248
248
  $("rside").setAttribute("aria-pressed", String(document.body.classList.contains("rflip")));
249
249
  $("rtabs").querySelector(".rtab.on")?.scrollIntoView({ block: "nearest", inline: "nearest" });
@@ -498,7 +498,8 @@ function browser(el: HTMLElement) {
498
498
  .then((j) => {
499
499
  if (url !== u) return;
500
500
  if (!j.ok) return void (note.textContent = `${far} (${j.error})`);
501
- note.hidden = true;
501
+ note.hidden = !j.hint;
502
+ note.textContent = j.hint || "";
502
503
  frame.hidden = false;
503
504
  frame.src = j.url;
504
505
  if (ext) ext.href = j.url;
@@ -630,6 +631,64 @@ async function newPty(agent?: string) {
630
631
  show("sh:" + sh.key);
631
632
  }
632
633
 
634
+ // The Preview button: the workspace's app in the Browser tab. A dev server already listening
635
+ // opens at once; otherwise the board starts the folder's dev script in a terminal here, waits
636
+ // for its port, then opens it. No dev script: the run's Preview (report and screenshots).
637
+ let starting = false;
638
+ async function previewApp() {
639
+ if (!ctx || starting) return;
640
+ const c = ctx;
641
+ const ports = async (): Promise<number[]> => {
642
+ try {
643
+ return await (await fetch("/devports?ws=" + encodeURIComponent(c.ws))).json();
644
+ } catch {
645
+ return [];
646
+ }
647
+ };
648
+ // The newest run here names the page to open (its ## Preview), when it has one.
649
+ const card = store.S.cards.filter((x) => x.state === c.dir && wsOfCard(x) === c.ws && x.id).sort((a, b) => String(b.id).localeCompare(String(a.id)))[0];
650
+ let pv = "";
651
+ try {
652
+ if (card) pv = preview((await (await fetch(`/run/${encodeURIComponent(card.id)}?dir=${encodeURIComponent(c.dir)}`)).json()).impl) ?? "";
653
+ } catch {}
654
+ const openAt = (u: string) => {
655
+ try {
656
+ localStorage.setItem("kz-browse:" + c.k, u);
657
+ } catch {}
658
+ addTab({ id: "local", kind: "local", title: "Browser" });
659
+ (panes.get("local")?.el as any)?.browseTo?.(u);
660
+ };
661
+ const now = await ports();
662
+ if (now.length) return openAt(devUrl(pv, now)!);
663
+ const u = devUrl(pv, []);
664
+ const r = await fetch("/shell", { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ dir: c.dir, ws: c.ws, run: c.k, dev: true }) }).catch(() => null);
665
+ if (!r?.ok) {
666
+ let why = "";
667
+ try {
668
+ why = (await r!.json()).error;
669
+ } catch {}
670
+ toast(why ? `Preview: ${why}` : "Preview: the dev server did not start");
671
+ return openPreview();
672
+ }
673
+ const sh = await r.json();
674
+ if (!shells.some((x) => x.key === sh.key)) shells.push(sh);
675
+ draw();
676
+ starting = true;
677
+ toast("Starting the app…");
678
+ try {
679
+ // Up to a minute for the first port; Linux only reads ports, elsewhere the run's address after a pause.
680
+ for (let i = 0; i < 40 && ctx?.k === c.k; i++) {
681
+ await new Promise((ok) => setTimeout(ok, 1500));
682
+ const p = await ports();
683
+ if (p.length) return openAt(devUrl(pv, p)!);
684
+ if (i === 5 && u && !navigator.platform.startsWith("Linux")) return openAt(u);
685
+ }
686
+ if (ctx?.k === c.k) toast("The app did not open a port. Its terminal tab shows why.");
687
+ } finally {
688
+ starting = false;
689
+ }
690
+ }
691
+
633
692
  async function closeTab(id: string) {
634
693
  const s = saved();
635
694
  if (id.startsWith("sh:")) {
@@ -685,6 +744,7 @@ function wire() {
685
744
  save();
686
745
  return draw();
687
746
  }
747
+ if (t.closest("[data-pv]")) return void previewApp();
688
748
  const n = t.closest<HTMLElement>("[data-n]")?.dataset.n;
689
749
  if (n) {
690
750
  const d = t.closest<HTMLDetailsElement>(".radd")!;
@@ -38,6 +38,7 @@ const PLACES: [RegExp, string, string][] = [
38
38
  [/^sources\./, "integrations", "Request sources"],
39
39
  [/^(mode|approvals\.|auto_accept)/, "approvals", "Approvals"],
40
40
  [/^auto_fix\./, "autofix", "Auto-fix"],
41
+ [/^auto_guard\./, "autofix", "Auto mode guard"],
41
42
  [/^git\./, "git", "Git"],
42
43
  [/^ui\./, "terminal", "Terminal"],
43
44
  [/^board\.chat_hotkey$/, "shortcuts", "Shortcuts"],
@@ -11,6 +11,7 @@ import { modelInput, modelLabel, orchestrationRows } from "./settings-orchestrat
11
11
  import { cleanupRows, wireCleanup } from "./settings-cleanup.ts";
12
12
  import { automationRows, wireAutomations } from "./settings-automations.ts";
13
13
  import { skillRows, wireSkills } from "./settings-skills.ts";
14
+ import { mountPhone } from "./phone-setup.ts";
14
15
  import { fillMics, micRow } from "./settings-voice.ts";
15
16
  import { placeOf, SETTINGS_NAV } from "./settings-pages.ts";
16
17
  import { askNotify, notifyOn, playSound, soundPick, SOUNDS, toast } from "./toast.ts";
@@ -160,7 +161,7 @@ export async function openSettings() {
160
161
  }
161
162
  }
162
163
  put("voice", "Dictation", row("Microphone", micRow(), "Used by this browser. Names appear after you first allow the microphone. Ctrl+Alt+D dictates into the focused terminal.", "v-mic", "microphone input device mic dictation shortcut"));
163
- put("mobile", "Phone", row("Phone address", cfg?.phoneUrls?.length ? html`<span class="phoneurls">${cfg.phoneUrls.map((url) => html`<a href="${url}" target="_blank" rel="noopener">${url}</a>`)}</span>` : html`<span>Not set</span>`, cfg?.phoneUrls?.length ? "Configured address; Tailscale must be running on both devices." : "Run kaizen setup on this PC to connect your phone.", "phone-url", "phone address url tailscale setup"));
164
+ put("mobile", "Phone", html`<div class="srow ph-card" data-q="phone mobile tailscale qr connect address setup"><div id="phset"></div></div>`);
164
165
  put("integrations", "Google", row("OAuth client id", html`<input class="sel" id="gg-id" placeholder="${gg.hasClient ? "Saved. Paste a new one to replace it" : "Desktop app client id from Google Cloud"}" spellcheck="false" autocomplete="off">`, "", "gg-id", "google oauth client id sheets write back"));
165
166
  put("integrations", "Google", row("OAuth client secret", html`<span class="fpick"><input class="sel" id="gg-secret" type="password" placeholder="${gg.hasClient ? "Saved. Paste a new one to replace it" : ""}" spellcheck="false" autocomplete="off"><button class="btn" id="gg-save" type="button">Save</button></span>`, "", "gg-secret", "google oauth client secret"));
166
167
  let hapton = true;
@@ -260,6 +261,7 @@ export async function openSettings() {
260
261
  if (cl) wireCleanup(cl, openSettings);
261
262
  fillMics();
262
263
  if (ac) wireAccounts(openSettings);
264
+ if ($("phset")) void mountPhone($("phset"));
263
265
  filter();
264
266
  $("smain").scrollTop = top;
265
267
  if (hadFocus) {
@@ -246,14 +246,14 @@ function drawList() {
246
246
  shut = folded.has(dir);
247
247
  // A + for a new worktree on git projects (the main checkout has a branch).
248
248
  const git = p.workspaces.some((w) => w.branch);
249
- return html`<div class="pgrp"><button type="button" class="proj${shut ? " shut" : ""}" data-fold="${dir}" title="${dir}" aria-expanded="${String(!shut)}">${logo(dir, name, last.projects)}<span class="pname">${name}</span><svg class="fchev" viewBox="0 0 24 24" aria-hidden="true"><path d="M9 6l6 6-6 6" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/></svg></button>${git ? html`<button type="button" class="wadd" data-wadd="${dir}" title="New workspace in ${name}" aria-label="New workspace in ${name}"><svg aria-hidden="true"><use href="#i-plus"/></svg></button>` : ""}</div>${shut ? "" : rows.map(({ w, cs }) => {
249
+ return html`<div class="pgrp"><button type="button" class="proj${shut ? " shut" : ""}" data-fold="${dir}" title="${dir}" aria-expanded="${String(!shut)}">${logo(dir, name, last.projects)}<span class="pname">${name}</span><svg class="fchev" viewBox="0 0 24 24" aria-hidden="true"><path d="M9 6l6 6-6 6" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/></svg></button>${git ? html`<button type="button" class="wadd" data-wadd="${dir}" title="New workspace in ${name}" aria-label="New workspace in ${name}"><svg aria-hidden="true"><use href="#i-plus"/></svg></button>` : ""}</div>${shut ? "" : raw('<div class="pws">')}${shut ? "" : rows.map(({ w, cs }) => {
250
250
  // The dot: the most urgent run there, or an agent asking (amber) or working (spinner).
251
251
  const rows = wsAgents(last.agents ?? [], dir, w.path, wsOfCard, now);
252
252
  const st0 = cs.length ? stateOf([...cs].sort((a, b) => RANK[stateOf(a)] - RANK[stateOf(b)])[0]) : "";
253
253
  const st = st0 === "wait" || rows[0]?.st === "asking" ? "wait" : rows.some((r) => r.st === "working") ? "build" : st0 || (rows.length ? "done" : "");
254
254
  // The agent buttons are siblings of the link (a button inside a link is invalid).
255
255
  return html`<div class="wsr wsc"><a class="row ws" href="${wsHref(dir, w.path)}" data-dir="${dir}" data-ws="${w.path}" title="${w.path}"><span class="si ${st || "none"}"></span><div class="wl"><span class="l1"><b>${wsLabel(w)}</b>${pins.has(dir + "\0" + w.path) ? PIN : ""}</span><span class="l2"><span>${folderOf(w)}</span>${w.main ? "" : WT}</span></div></a>${agentsHtml(rows, now, !!wsOpen[dir + "\0" + w.path], dir, w.path)}</div>`;
256
- })}`;
256
+ })}${shut ? "" : raw("</div>")}`;
257
257
  })
258
258
  .join("") || `<div class="none">No projects</div>`;
259
259
  // The same markup is not written again: hover and focus stay, and a tick that changed nothing costs no layout.