dsh-tower 2.0.2 → 2.0.4

package/lib/workspaceLock.js

@@ -16,28 +16,53 @@ export function workspaceLockToken() {
 
 async function readRecord(commonDir) {
   const file = workspaceLockPath(commonDir)
+  let text = null
   try {
-    const text = await fsp.readFile(file, 'utf8')
-    const parsed = JSON.parse(text)
-    if (!parsed || typeof parsed !== 'object') return { file, record: null, corrupt: true }
-    return { file, record: parsed, corrupt: false }
+    text = await fsp.readFile(file, 'utf8')
   } catch (error) {
-    if (error?.code === 'ENOENT') return { file, record: null, corrupt: false }
-    return { file, record: null, corrupt: true }
+    if (error?.code === 'ENOENT') return { file, record: null, corrupt: false, raw: null }
+    return { file, record: null, corrupt: true, raw: null }
+  }
+  try {
+    const parsed = JSON.parse(text)
+    if (!parsed || typeof parsed !== 'object') return { file, record: null, corrupt: true, raw: text }
+    return { file, record: parsed, corrupt: false, raw: text }
+  } catch {
+    return { file, record: null, corrupt: true, raw: text }
   }
 }
 
-async function removeLock(file) {
-  for (let attempt = 0; attempt < 5; attempt += 1) {
+/**
+ * Remove the lock only if it is still the record we inspected. A concurrent
+ * release/re-acquire must not be deleted by the loser of the race.
+ */
+async function removeLockIfMatches(file, expectedToken, expectedRaw) {
+  const quarantine = `${file}.stale-${process.pid}-${crypto.randomUUID()}`
+  try {
+    await fsp.rename(file, quarantine)
+  } catch (error) {
+    if (error?.code === 'ENOENT') return true
+    throw error
+  }
+  let moved = null
+  try {
+    moved = await fsp.readFile(quarantine, 'utf8')
+  } catch {
+    moved = null
+  }
+  const same = expectedToken ? (() => {
     try {
-      await fsp.unlink(file)
-      return
-    } catch (error) {
-      if (error?.code === 'ENOENT') return
-      if (!['EPERM', 'EBUSY', 'EACCES'].includes(error?.code) || attempt === 4) throw error
-      await new Promise((resolve) => setTimeout(resolve, 10 * (attempt + 1)))
+      return JSON.parse(moved ?? '')?.token === expectedToken
+    } catch {
+      return false
     }
+  })() : moved !== null && moved === expectedRaw
+  if (!same && moved !== null) {
+    await fsp.rename(quarantine, file).catch(() => {})
+    return false
   }
+  await fsp.unlink(quarantine).catch(() => {})
+  return true
 }
 
 /**
@@ -54,7 +79,7 @@ export async function acquireWorkspaceLock(commonDir, options) {
       return { acquired: true, record, tookOver: attempt > 0 }
     } catch (error) {
       if (error?.code !== 'EEXIST') throw error
-      const { record: current, corrupt, file } = await readRecord(commonDir)
+      const { record: current, corrupt, file, raw } = await readRecord(commonDir)
       if (corrupt || !current) {
         // A corrupt lock is treated like an unknown holder; only a stale one
         // is removed, so a concurrent writer is never silently overwritten.
@@ -66,7 +91,7 @@ export async function acquireWorkspaceLock(commonDir, options) {
           stale = true
         }
         if (stale) {
-          await removeLock(file)
+          await removeLockIfMatches(file, null, raw)
           continue
         }
         return { acquired: false, holder: null, corrupt: true }
@@ -76,7 +101,7 @@ export async function acquireWorkspaceLock(commonDir, options) {
         return { acquired: true, record: { ...record, token: current.token }, tookOver: false }
       }
       if (now - Number(current.at ?? 0) > staleMs) {
-        await removeLock(file)
+        await removeLockIfMatches(file, current.token, raw)
         continue
       }
       return { acquired: false, holder: current }
@@ -97,10 +122,9 @@ export async function touchWorkspaceLock(commonDir, options) {
 /** Release the lock only when this session owns it. */
 export async function releaseWorkspaceLock(commonDir, options) {
   const { token } = options
-  const { record, file } = await readRecord(commonDir)
+  const { record, file, raw } = await readRecord(commonDir)
   if (!record || (token && record.token !== token)) return false
-  await removeLock(file)
-  return true
+  return removeLockIfMatches(file, record.token, raw)
 }
 
 export async function inspectWorkspaceLock(commonDir, options = {}) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-tower",
-  "version": "2.0.2",
+  "version": "2.0.4",
   "type": "module",
   "description": "DSH-native Tower: mission planning, worktree isolation, review-gated merges, and a human-owned Tower mode.",
   "license": "MIT",
@@ -51,7 +51,8 @@
     "LICENSE",
     "CONTRIBUTING.md",
     "SECURITY.md",
-    "docs/"
+    "docs/",
+    "ui-bundle/"
   ],
   "dsh": {
     "bundle": {

package/scripts/check-docs.mjs

@@ -77,11 +77,15 @@ const eventNames = [
   'status',
   'preflight',
   'doctor',
+  'recover',
   'test',
   'batch',
   'resource',
   'import_legacy',
   'legacy_map',
+  'mode',
+  'control',
+  'reload',
 ]
 const documentedEvents = read('docs/reference/events.md')
 const missingEvents = eventNames.filter((name) => !documentedEvents.includes(`\`tower/${name}\``))
@@ -102,6 +106,37 @@ if (missingErrors.length > 0) problems.push(`docs/reference/errors.md misses cod
 if (missingEvents.length > 0) problems.push(`docs/reference/events.md misses events: ${missingEvents.join(', ')}`)
 if (missingChangelog) problems.push(`CHANGELOG.md misses version ${packageJson.version}`)
 
+// Counts and high-risk defaults are part of the contract, not just names.
+const toolsDoc = read('docs/reference/tools.md')
+const blockersDoc = read('docs/reference/blockers.md')
+const errorsDoc = read('docs/reference/errors.md')
+const eventsDoc = read('docs/reference/events.md')
+const configDoc = read('docs/reference/config.md')
+const zhConfigDoc = read('docs/zh/reference/config.md')
+if (!toolsDoc.includes(`up to ${toolNames.length} tools`)) {
+  problems.push(`docs/reference/tools.md must state "up to ${toolNames.length} tools"`)
+}
+if (!blockersDoc.includes(`${blockerCodes.size} stable blocker/failure codes`)) {
+  problems.push(`docs/reference/blockers.md must state ${blockerCodes.size} stable blocker/failure codes`)
+}
+if (!errorsDoc.includes(`${errorCodes.length} tool error codes`)) {
+  problems.push(`docs/reference/errors.md must state ${errorCodes.length} tool error codes`)
+}
+if (!eventsDoc.includes(`${eventNames.length} process-local events`)) {
+  problems.push(`docs/reference/events.md must state ${eventNames.length} process-local events`)
+}
+for (const required of [
+  '| `tests.admission` | `off` |',
+  '| `review.requireReview` | `false` |',
+  '| `mode.allowAgentControl` | `true` |',
+  '| `git.timeoutMs` | `15000` |',
+]) {
+  if (!configDoc.includes(required)) problems.push(`docs/reference/config.md misses required default: ${required}`)
+}
+if (!zhConfigDoc.includes('| `tests.admission` | `off` |')) {
+  problems.push('docs/zh/reference/config.md misses the tests.admission default')
+}
+
 // Chinese parity: when the translation tree exists it must cover the same
 // reference names, so a tool or code cannot be added only in English.
 if (exists('docs/zh')) {

package/skills/tower-recovery.md

@@ -24,8 +24,9 @@ untouched — call `tower_merge` to record it.
 
 ## `state.lock` reports another writer
 
-Wait, then retry. Never delete the lock while a writer may be active; if the process is gone,
-remove `<git-common-dir>/dsh-tower/state.lock` deliberately and retry.
+Wait and retry; a live writer must never be interrupted. If the holder is provably dead, use a
+supported recovery path (or ask the human to run one) that verifies the PID is gone and takes a
+backup first. **Do not delete `state.lock` or the state directory from this playbook.**
 
 ## Worktree missing or dirty
 
@@ -35,6 +36,7 @@ explicit teardown `force` decision.
 
 ## Reset a repository's Tower state
 
-Only when no mission is in flight and you accept losing mission history: stop all agents, remove
-`<git-common-dir>/dsh-tower/`, then `tower_init` again. Worktrees and branches must be cleaned
-manually.
+**Do not delete `<git-common-dir>/dsh-tower/` from this playbook.** That directory contains mission,
+review, roster, finding and activity history; deleting it can lose unrecoverable work. Stop and ask
+the human to inspect `tower_doctor`, take a backup, and decide on a controlled repair. Worktrees and
+branches must be cleaned only after that decision.

package/ui-bundle/README.md

@@ -0,0 +1,111 @@
+# Tower UI (optional Client bundle)
+
+An **optional** Web Client bundle for the Host `dsh-tower` plugin. It never touches Tower state directly: everything it renders is derived from the conversation the user is already looking at, or from the tool results already in that conversation. There is no Host → Client remote channel, no `host.call`, no DOM manipulation, no iframe, and no import of Harness Client packages (the only module it requires is `react` from the browser module table).
+
+Version: **0.2.2** (private, not published). The Host plugin version is unchanged.
+
+This revision fixes GitHub **#11** (persistent, history-derived Tower-mode indicator in the composer dock) and **#12** (mode-aware `Tower mode · disabled` rows for guard-denied tools), see below.
+
+## What it registers
+
+| Surface | Slot | Registration | Data source |
+|---|---|---|---|
+| Tower tool cards | `tool.call.toolview` (keyed, session) | 12 entries, one per `key`: `tower_status`, `tower_roster`, `tower_spawn`, `tower_mission`, `tower_complete`, `tower_review`, `tower_preflight`, `tower_merge`, `tower_teardown`, `tower_interrupt`, `tower_doctor`, `tower_batch` | The Chat tool-call tree's owner props: `toolName`, `phase` (`preparing` / `start` / `result`), `block` (streaming start block or settled `tool/result` block), `callId`. |
+| Composer dock | `conversation.composer.dock` (list, session) | `id: "tower-hint"`, `order: 6` | `useChat` standard selector hook (the durable Chat legacy slice). In Tower mode: a `Tower · on` chip. Otherwise, a Tower tool result in the conversation: a compact latest-status line. Otherwise: the static `/tower` hint. |
+| Denied-tool rows | `tool.call.toolview` (keyed, session) | dynamic entries for the Tower-mode deny list, `priority: -10`, plus `update_goal` | The same history-derived Tower mode. Registered only while the displayed session is in Tower mode and disposed when it leaves, so the native toolviews (priority 0) return. |
+| Overlay status strip | `shell.overlay` (list, root) | `id: "tower-status-strip"`, `order: 20` | The overlay slot is root-scoped, so it receives no chat hooks. The chat-driven toolview components publish a start/result notice into a module-local observable that this entry injects as `useTowerNotice`; a single timer auto-dismisses it after 4.5 s and is disposed by `ctx.effect`. |
+| Locale | Client locale service | namespace `tower-ui` (`en`, `zh`) | Bound `t` seats come from each registration's `locale` option. |
+
+The cards are deliberately compact: mission status/counts, task checklist progress, blockers, roster live/stale counts, review verdict, merge/preflight state, and check/test evidence (exit codes included). All of it is rendered as React elements with inline styles; **theme references are restricted to `--dsw-alias-*` tokens**, so light/dark and token renames degrade gracefully.
+
+The overlay strip is `pointer-events: none` end-to-end and uses `role="status"` / `aria-live="polite"`; it never blocks the composer or the page.
+
+## Persistent Tower-mode indicator (#11)
+
+Tower mode is a Host-side session stance and there is no Client RPC for it. The dock derives it from the durable session history that the Chat projection exposes in `useChat(snapshot.legacy)`:
+
+- the `/tower on|off` command node (`kind: "command"`, `name: "tower"`, `args`, `outcome.kind`); bare `/tower` and `/tower <message>` mean "ensure on", `/tower reload` and `/tower base <branch>` leave the stance unchanged, and a failed command is ignored;
+- `tower_mode` results (`mode: "on" | "off" | "unknown"`, `deniedWhileActive`, `workspaceLock`, `lastChange`);
+- `tower_control` results (`action: enter|exit`, `mode`, `changedBy`, `reason`).
+
+The last recognized event wins. A page refresh re-derives the same stance from the loaded history; when that history window no longer contains a mode event, the dock falls back to a browser-local last-known value for the same session and labels it as such. An old value expires after seven days and never drives the denied-tool shadowing by itself.
+
+While the mode is on the dock shows a `Tower · on` chip with `role="status"` / `aria-live="polite"`, and its tooltip carries the actionable hint plus, when known, the repository basename, workspace-lock state (`held`/`free`), and who changed the mode last. The chip is **deliberately non-interactive**: the only existing standard affordance is `inputActions.setDraft` + `inputActions.submit`, which submits the composer draft and would clobber what the user is typing. The tooltip tells the user to run `/tower off`; the bundle itself does not toggle the mode (the model's supported path is the Host `tower_control` tool when `allowAgentControl` is enabled).
+
+## Mode-aware denied-tool rows (#12)
+
+The Host guard returns a plain tool error like `tower mode: <tool> is disabled while Tower mode is active; use the Tower tools or /tower off` (and `tower mode: goals cannot be resumed while Tower mode is active; use /tower off first` for `update_goal` resume).
+
+While the displayed session is in Tower mode the bundle dynamically registers `tool.call.toolview` entries for:
+
+- `tower_mode.deniedWhileActive` when the latest `tower_mode` output lists it, otherwise `lib/config.js` `DEFAULT_DENY_TOOLS` (`create_goal`, `todo_write`, `team_task_create`, `team_task_update`, `team_task_reopen`, `team_task_list`, `spawn_teammate`, `wait_agent`, `workflow`, `ralph`, `subagent`, `subagent_fork`);
+- `update_goal` unconditionally, because the guard special-cases its `action: "resume"`.
+
+Those entries register with `priority: -10`. The slot core renders the lowest priority for a key, so this shadows the native keyed views without replacing them; disposing the entries (mode off) restores the native views exactly. A denial result renders as a distinct **`Tower mode · disabled`** row (warn marker, label, the preserved denial message, and the `/tower off` hint) — not the generic error text styling. `update_goal` resume denials get the same row. A non-denial result that lands in one of those slots while the mode is on renders a defensive generic row (there is no native view to delegate to while the registration shadows it); ordinary tool errors are not misclassified as Tower-mode denials.
+
+## Verification status
+
+Verified **statically** against the installed DSH **0.2.1-rc.2** sources:
+
+- `tool.call.toolview`: declared by `@deepseek-ai/dsh-client-ui-tool` as `{ kind: "keyed", scope: "session" }`; the Chat tool-call tree dispatches with `entryKey = toolName` and passes `{ callId, toolName, ...call, openFile, cwd, home, loadImage, useDisclosure, inspect }`, where `call` is `{ phase, block }`. A keyed hit replaces the generic tool row; a miss falls back to it.
+- Keyed priority/shadowing: the Client slot core (in the web shell bundle) allows a second keyed registration only at a different `priority` and resolves a key with the **lowest** priority first — `register at a different priority to shadow it (lowest renders)`. Native views use the default priority 0.
+- `conversation.composer.dock`: declared by `@deepseek-ai/dsh-client-ui-conversation` as `{ kind: "list", scope: "session" }`, rendered as `div[data-composer-dock]`. Owner props are empty; session-scope standard props (including `useSession`, `useChat`, `useConversation`) are supplied by the renderer.
+- `shell.overlay`: declared by `@deepseek-ai/dsh-client-ui-layout` as `{ kind: "list", scope: "root" }`, rendered inside `[data-shell-overlay]`. Root standard props are `useSessions`, `useSessionStatus`, `useWorkspaces`, `usePanelInfo` and keyed access hooks — **no chat hook**; hence the toolview-published notice design above.
+- `/tower` history: DSH logs `command/run` with `{ name, args: parsed.rawInput, source }` and `command/done` with `{ kind, text }`, which the Chat command node exposes as `{ kind: "command", name, args, outcome }` in the legacy slice.
+- Guard denial shape: the Host tools pipeline materializes a denial as `{ content: [{ type: "text", text: "Error: <reason>" }], isError: true, error: { message: <reason> } }`.
+- Locale: `ctx.locale.register(ns, { en, zh })`, dictionaries are flat `key → template` maps with `{param}` interpolation; a slot declaration's `locale` option supplies the bound `t` seat.
+- The bundle's `dsh.client.inject` orders activation after `ui-conversation` and `ui-tool`, the two packages that declare the slots it targets. `ctx.slots.inject` only installs a registration while its owner declaration exists; each injection is guarded and reported in diagnostics instead of crashing the whole Client half.
+
+Automated offline coverage: `tests/ui-bundle.test.mjs` loads `client.js` through a fake `window.__ModuleLoader__`, asserts the 12 keys / dock id / overlay id, en–zh dictionary parity, theme-token discipline, and renders every card plus the dock/overlay components with fake hooks. It also drives fake chat history through the dock to assert the off hint, the on chip (including refresh re-derivation), `tower_mode`/`tower_control`/command updates, dynamic registration for default and configured deny lists, disposal on mode off, `update_goal`, denial-row treatment, generic fallbacks, and locale parity — no browser required.
+
+Live/browser verification is **opt-in** (`tests/live/ui-slots.cjs`) because it needs an isolated profile with the bundle installed. From a teammate/subagent session the Client `Slots` inspect query times out by design (the page answers only the agent whose session it displays), so this phase did not run a live inspection; the source-level contract above is the evidence. When the script runs against an installed profile it binds a session with a bare `/tower` command and asserts, through the read-only `window.__TOWER_UI_DIAG__` report, that apply() ran without errors, that all 12 toolview keys and the dock/overlay entries registered, that the dock outlet is visible, and — since the bind command turns the Host mode on — that the history-derived `Tower · on` chip rendered (#11). The chip can be inspected visually in the same run (`data-tower-ui="dock-mode"`).
+
+## Tests
+
+```powershell
+# offline, no browser
+node --check ui-bundle/client.js
+node --test tests/ui-bundle.test.mjs
+
+# opt-in live check (isolated profile only)
+node tests/live/ui-slots.cjs
+```
+
+`tests/live/ui-slots.cjs` prints `SKIP` and exits 0 when `DSH_TEST_URL` (or Playwright) is missing; it never installs anything and never opens the desktop profile. Set `DSH_TEST_EXPECT_HINT=1` when the bundle is installed so a missing client module or missing dock entry fails instead of skipping the assertion, and `DSH_TEST_EXPECT_MODE=1` to require the history-derived `Tower · on` chip after the script's `/tower` bind step (otherwise that check is a warning, since the bind step is best-effort).
+
+## Why it is a separate bundle
+
+It is not installed by default and does not affect installing or running the Host `dsh-tower` plugin. The Host plugin is fully functional without it; the UI half only decorates the conversation that is already on screen.
+
+## Install (isolated profile only)
+
+```text
+# throwaway profile, not the desktop profile
+dsh --profile towertest --from-default-profile web --dump-config
+dsh plugin --profile towertest add <absolute path to this ui-bundle>
+dsh --profile towertest --port 59001 --no-open
+# open the tokenized URL printed at boot, then verify:
+$env:DSH_TEST_URL='http://127.0.0.1:59001/?token=<token>'
+$env:DSH_TEST_EXPECT_HINT='1'; node tests/live/ui-slots.cjs
+```
+
+From a session in that profile, `plugin_manager({ action: "install_bundle", target: "<absolute path to this ui-bundle>" })` performs the same add + enable. Do not install it into the live desktop profile without the user's explicit request.
+
+## Remove
+
+```text
+dsh plugin --profile towertest remove dsh-tower-ui
+```
+
+Without HMR a bundle that has been running since process start may need a DSH restart for removal; with HMR a reconcile can unload it. A page refresh (or hard refresh) is enough to update the Client half after a linked-directory change.
+
+## Known limitations
+
+- **No live Host state / no new RPC.** The mode chip is inferred from the **loaded history window** of the displayed session. If the `/tower on` command (or a `tower_mode` result) sits outside that window, the dock falls back to the static hint and the mode-aware rows are not registered; a later `/tower`, `tower_control`, or `tower_mode` result corrects it. The dock summary is likewise the latest visible Tower tool result, not a dashboard, and does not poll.
+- **Mode-driven registration is slot-global.** The dock follows the displayed session. While that session is in Tower mode, the denied-tool shadow entries also apply to other sessions' rows for those tools (they render the defensive generic row); leaving the mode disposes them globally and restores the native views.
+- **A custom `mode.denyTools` list needs a `tower_mode` result in the visible history.** The dock learns `deniedWhileActive` only from a `tower_mode` output; if the mode was inferred from `/tower on` alone (or the `tower_mode` result is outside the loaded window), the bundle shadows the default list instead, and a custom denied tool falls back to the native error row until a `tower_mode` output appears.
+- **The on-chip is not a button.** `inputActions.submit()` submits the composer draft, so programmatically sending `/tower off` would overwrite the user's draft; the actionable tooltip asks the user to run it. There is no click handler and no automatic toggle from the bundle; the Host `tower_control` tool remains the model's supported path.
+- **The overlay is root-scoped.** It cannot read chat state directly, so a result that lands while every Tower toolview is unmounted (for example the user switches sessions before the result renders) shows no strip. The strip itself carries no actionable content by design.
+- A tool result whose payload is not JSON (older/foreign shape) renders as a plain one-line summary rather than a card; errors render as an error card.
+- Client bundle updates are not auto-rebuilt: edit → reconcile/link → **refresh the page**. Profile patch or manifest changes may need a restart.
+- `window.__TOWER_UI_DIAG__` is a read-only diagnostic seam for tests. It contains no session content — only plugin version, applied flag, slot/toolview names, current mode summary, dynamic deny keys, and guarded registration errors.