feat: v1.0.6 candidate — Worker maintenance release

- Re-vendor light-kanban-worker from LightDevCoder/skills#v0.1.5
  (commit a56aa9d): 14 files byte-identical; skills/manifest.json pins
  repository / tag / commit / per-file SHA-256.
- scripts/verify-vendored-skill.cjs: exact file-set verification — the
  actual recursive package file set must equal the manifest file set;
  missing files, hash drift, and unexpected extra files all fail.
  --self-test: 7 assertions (pristine copy + tampered/deleted/extra-file
  negatives).
- README / README_CN Quick Start: scheduler prompt now carries Agent
  Avatar (first registration only) and the max-concurrency-1 guidance for
  the same Agent ID; first-run one-shot prompt registers a fresh identity
  and the simplified form is documented for later runs; use cases add
  different-agent concurrency vs same-agent non-overlap, the long-running
  task skip example, and the atomic-claim boundary in the manual API
  section.
- Docs sync: spec.md v1.0.6 section (no API/UI/state-machine change),
  AGENTS.md vendor contract + exact file-set gate, PROGRESS.md v1.0.6
  record, manual-test-checklist.md section T (first registration /
  scheduler concurrency / multi-agent regression / snapshot integrity) +
  regenerated xlsx.
- Verification: make check PASS (frontend build, vitest, dist guard,
  gofmt, vet, go test, VENDOR_SKILL=PASS 14 files, VENDOR_SELF_TEST=PASS
  7 assertions); make cross PASS (4 platforms); fresh-database
  first-registration smoke PASS; scheduler non-overlap lock-fixture smoke
  PASS; multi-agent concurrent-claim regression PASS.

Author: Light Cheng

.scratch/task-board/spec.md

@@ -185,16 +185,68 @@ Use light-kanban-worker to process at most one Light-Kanban task.
 
 This repository ships the Skill as a byte-identical snapshot in
 `skills/light-kanban-worker/` (pinned to `LightDevCoder/skills` tag
-`v0.1.4`, commit `a9cc8aa`) for offline / manual host installation. The
+`v0.1.5`, commit recorded in `skills/manifest.json`) for offline / manual
+host installation. The
 upstream repository remains the behavioral authority; the snapshot is
 read-only, integrity-pinned by `skills/manifest.json` (SHA-256), and checked
-by `make check` and CI (`scripts/verify-vendored-skill.cjs`).
+by `make check` and CI (`scripts/verify-vendored-skill.cjs` — the actual
+recursive file set must equal the manifest file set exactly: missing files,
+hash drift, and unexpected extra files all fail).
 
 ### Validation for this release
 
 - Board-side: `make check` + `make cross` (four platforms), no Go/UI behavior
   change — this release is documentation + integration packaging.
 - Cross-repo: the Worker Skill passed its full admission
   (`review-loop agent-skill` PASS), behavioral scenarios A–F against a real
-  Light-Kanban server, and fresh-install verification from Skills v0.1.4.
+  Light-Kanban server, and fresh-install verification from Skills v0.1.5.
+
+## v1.0.6 Worker Maintenance
+
+Status: release candidate — prepared for v1.0.6, published after user
+acceptance. Maintenance release — **no REST API change, no UI
+change, no state-machine change**.
+
+### Same-agent runs must not overlap
+
+- Skills v0.1.5 (the vendored behavioral authority) now explicitly forbids
+  two overlapping runs with the same agentId: at most one invocation per
+  agent id may be active, and a wake that fires while the previous run is
+  still active must skip.
+- Boundary, stated precisely: Light-Kanban's atomic claim protects two
+  **different** workers claiming the same To Do card. It does not protect
+  two runs sharing one agentId, because owned work needs no new claim.
+  Atomic claim is not a concurrency lock for multiple invocations using the
+  same agent identity.
+- Concurrency control stays with the scheduler / agent runtime
+  (`max concurrent runs = 1` or an equivalent skip-while-active setting).
+  This release adds no worker lease, heartbeat, scheduler, or lock endpoint
+  on the server; the scheduler owns the boundary.
+
+### First-registration identity
+
+- First registration of an agentId requires ID + name + avatar; a local
+  image is uploaded via `POST /api/avatars` and the returned
+  `/api/avatars/...` path is used for the claim. Later runs reuse the stored
+  identity (avatar is required for first registration, not every wake).
+- A new agentId without name/avatar reports identity configuration missing:
+  no claim, no task mutation, run ends. Quick Start now carries the
+  first-run one-shot prompt with Agent Avatar.
+
+### Vendor integrity gate (exact file set)
+
+- `scripts/verify-vendored-skill.cjs` verifies the actual recursive file set
+  of `skills/light-kanban-worker/` against `skills/manifest.json` exactly:
+  modified file → hash mismatch FAIL; deleted file → missing file FAIL;
+  added unlisted file → unexpected file FAIL. `--self-test` covers the
+  positive copy and all three negative classes (7 assertions).
+
+### Validation for this release
+
+- `make check` (frontend build, vitest, dist guard, gofmt, vet, go test,
+  vendor guard + self-test) and `make cross` (four platforms) PASS.
+- Fresh-database first-registration smoke with a real avatar PASS; scheduler
+  non-overlap smoke (max concurrency 1 / lock fixture — not a server lease
+  test) PASS; multi-agent regression (two agents, atomic claim, one winner
+  per card) PASS.
 

AGENTS.md

@@ -19,7 +19,7 @@ A single-binary Go kanban board: a human queues tasks (each card points at a wor
 - **Frontend dev**: `make frontend-install` once, then `make dev-frontend` (Vite on :5173, proxies `/api` to a Go backend on :8641). Production staging: `make frontend-build` rebuilds and copies `frontend/dist` → `internal/webui/dist` (commit the result with your change).
 - **Test**: `go test ./...` — tests live at the two agreed Go seams: HTTP API (`internal/api/api_test.go`) and the store (`internal/store/store_test.go`), plus a tiny cmd seam (`cmd/light-kanban/main_test.go`) pinning the listen-address/startup-URL contract. v1.0.4 adds a frontend pure-logic seam: the product tour's decision logic (`frontend/src/components/ProductTour/logic.ts` + `steps.ts`) is unit-tested with vitest (`cd frontend && npm test`). The committed `internal/webui/dist` keeps the Go tests green on a fresh clone without npm.
 - **Vet / format**: `go vet ./...`; `gofmt -l internal cmd scripts` (never `gofmt -l .` — `.tools/` is the vendored toolchain).
-- **Pre-commit gate**: `make check` — rebuilds the frontend, runs the frontend unit tests, verifies the committed `internal/webui/dist` matches the source, runs gofmt / vet / tests, and verifies the vendored Worker Skill snapshot (`node scripts/verify-vendored-skill.cjs` + `--self-test`). CI (`.github/workflows/ci.yml`) runs the same checks on every push to main and every PR.
+- **Pre-commit gate**: `make check` — rebuilds the frontend, runs the frontend unit tests, verifies the committed `internal/webui/dist` matches the source, runs gofmt / vet / tests, and verifies the vendored Worker Skill snapshot (`node scripts/verify-vendored-skill.cjs` + `--self-test`): the actual recursive file set of `skills/light-kanban-worker/` must equal `skills/manifest.json` exactly — missing files, hash drift, and unexpected extra files all fail the gate. CI (`.github/workflows/ci.yml`) runs the same checks on every push to main and every PR.
 - **Cross-compile**: `make cross` (or `scripts\cross-build.ps1`) → `dist/` binaries: linux (amd64), darwin (amd64 + arm64), windows (amd64). Both build the frontend first.
 - **Demo data**: `node scripts/seed-demo.cjs` seeds a running board (35 tasks / 3 agents) for density checks and screenshots.
 - **Data**: SQLite at `-db kanban.db` (default, working directory); `:memory:` accepted. Uploaded agent avatars live in `-avatars avatars` (default) and are served from `/api/avatars/*`.
@@ -31,7 +31,7 @@ A single-binary Go kanban board: a human queues tasks (each card points at a wor
 - **i18n is dual-source**: `frontend/src/i18n/zh.ts` is the key schema; `en.ts` must stay structurally identical (tsc enforces it).
 - **Red-green discipline**: new behavior starts with a failing test at one of the agreed seams (Go: HTTP API / store / cmd; frontend: the ProductTour pure-logic module).
 - **Embedded dist ships with its source**: every change to `frontend/src/` must commit the regenerated `internal/webui/dist/` in the same commit (`make frontend-build`, then verify with `make check`) — otherwise the shipped binary silently keeps the old UI.
-- **Vendored Skill snapshot is read-only**: never edit files under `skills/light-kanban-worker/` in place. The behavioral authority is the upstream `LightDevCoder/skills` repository; to upgrade, re-vendor from the new upstream tag, regenerate `skills/manifest.json` (SHA-256) and update `skills/README.md` — `make check` (and CI) fail on any drift via `scripts/verify-vendored-skill.cjs`.
+- **Vendored Skill snapshot is read-only**: never edit files under `skills/light-kanban-worker/` in place. The behavioral authority is the upstream `LightDevCoder/skills` repository; to upgrade, re-vendor from the new upstream tag (byte-identical copy), regenerate `skills/manifest.json` (repository, tag, commit SHA, package path, per-file SHA-256) and update `skills/README.md` — `make check` (and CI) fail on any drift via `scripts/verify-vendored-skill.cjs`, which enforces the exact file set: manifest-listed files must match byte-for-byte, and no unlisted file may exist.
 
 ## Agent skills
 

PROGRESS.md

@@ -1,14 +1,24 @@
 # PROGRESS — 项目进度与交接记录
 
 > 本文档记录 Light-Kanban 的当前进度、约定、待办与 Mac 迁移指引，供后续维护者快速接上手。
-> 最后更新：2026-08-17（v1.0.5 已发布）
+> 最后更新：2026-08-17（v1.0.6 维护发布准备中）
 
 ## 1. 当前状态
 
 - **远端仓库**：https://github.com/LightDevCoder/light-kanban（public，gh 账号 LightDevCoder）
-- **最新发布**：`v1.0.5`（light-kanban-worker Skill 集成），tag `v1.0.5` + GitHub Release 齐全，四平台二进制（Windows amd64 / Linux amd64 / macOS amd64 / macOS arm64）+ `light-kanban-worker.zip`（Skill 快照）已作为 release 资产上传；`v1.0.4` 及更早的 tag / Release / 二进制保持原样
-- **当前工作**：无进行中的 release；v1.0.5 为最新稳定版本，后续改动等待真实使用反馈
-- **工作树**：与 origin/main 一致（发布标记提交后）
+- **最新发布**：`v1.0.5`（light-kanban-worker Skill 集成）；`v1.0.6`（Worker 维护发布）为当前 release candidate，待用户验收后发布；发布时上传四平台二进制（Windows amd64 / Linux amd64 / macOS amd64 / macOS arm64）+ `light-kanban-worker.zip`（Skills v0.1.5 快照）
+- **当前工作**：v1.0.6 维护发布——Skills v0.1.5 已实现并重新 vendor，`make check` / `make cross` PASS，等待用户验收（manual-test-checklist T 节）后发布
+- **工作树**：v1.0.6 candidate
+
+## 2d. v1.0.6（release candidate，待用户验收发布）— Worker 维护
+
+- **范围**：纯维护发布——无 REST API 变更、无 UI 变更、无任务状态机变更、不重新截图；Skills v0.1.5 先发布并 fresh-install 验证，再重新 vendor 并发布 Light-Kanban v1.0.6
+- **Skills v0.1.5（上游行为权威）**：`light-kanban-worker` 明确禁止同一 agentId 的 scheduled run 重叠（同一 agentId 任意时刻至多一个 invocation 活跃，上一 run 未结束时唤醒必须 skip；不同 agentId 仍可并发）；准确记录 atomic claim 边界（只保护不同 worker 争同一张 To Do，不是同一 agent identity 的并发锁）；并发控制归 scheduler / agent runtime（`max concurrent runs = 1` 或等价设置），worker 不新增 lock/heartbeat/lease service；首次注册明确要求 ID + name + avatar（本地图片经 `POST /api/avatars` 上传），已有身份复用服务器 name/avatar，缺 avatar 的新身份不 claim 不改动；新增 contract/behavior 测试、两个对抗性 negative fixture 与场景 G（同 agent 并发唤醒）/H（无 avatar 新身份，诚实记录验证边界），A–F 不变；`review-loop agent-skill` 第二次 PASS（4 findings 修复：F-001 pre-tag 发布表述 / F-002 api.md 版本表述 / F-003 收据 gate 行 / G-001 残留 published 句子）；release evidence 区分 pre-release gate / post-release verification
+- **Quick Start 修复**：README / README_CN 第四步 scheduler prompt 增加 `Agent Avatar: /path/to/codex-icon.png` 并说明「Avatar 只在首次注册需要」；紧接着写死「同一 Agent ID 的调度并发 = 1」；one-shot 示例改为首次注册可用形式（ID + Name + Avatar），注册后可简化为旧的单行 prompt；Use Cases 增「不同 Agent ID 可并发、同 ID 不得重叠」与长任务跳过示例（15 分钟调度 / 40 分钟任务：08:00 run，08:15/08:30 skip，08:40 结束，08:45 允许下一次）；手动 API 接入补 atomic claim 边界说明
+- **vendored 快照完整性强化**：`scripts/verify-vendored-skill.cjs` 从「只校验 manifest 列出的文件」升级为「实际递归文件集 === manifest 文件集」——缺文件、hash 漂移、**多出来的未登记文件**全部 FAIL；`--self-test` 扩到 7 断言（positive + 改 SKILL.md → hash mismatch + 删 SKILL.md → missing + 新增 unexpected-extra.md → unexpected file），接入 `make check`/CI
+- **重新 vendor**：从 `LightDevCoder/skills#v0.1.5`（commit 见 manifest）逐字节复制 `skills/light-kanban-worker/`（14 文件），`skills/manifest.json` 记录 repository / tag / commit SHA / 包路径 / 每文件 SHA-256
+- **文档**：spec.md v1.0.6 章节、AGENTS.md（vendored 契约 + vendor guard 描述）、manual-test-checklist.md T 节（首次注册 / 缺 avatar / 调度并发 / 多 Agent 回归 / 快照完整性）+ xlsx 重新生成
+- **验收**：`make check` / `make cross` PASS；全新数据库 + 全新 agentId + 真实头像的 first-registration smoke PASS；scheduler non-overlap smoke（max concurrency 1 / lock fixture）PASS；多 Agent 回归（codex-main + claude-code 并发 claim 不同任务）PASS；用户验收后发布 tag `v1.0.6` + GitHub Release
 
 ## 2a. v1.0.5（已发布）
 

README.md

@@ -86,7 +86,7 @@ Download the binary for your machine from [Releases](https://github.com/LightDev
 Install the official worker Skill for your agent host (recommended):
 
 ```bash
-npx skills add LightDevCoder/skills#v0.1.4 \
+npx skills add LightDevCoder/skills#v0.1.5 \
   --skill light-kanban-worker \
   --yes \
   --copy \
@@ -126,13 +126,41 @@ codex-main
 Agent Name:
 Codex
 
+Agent Avatar:
+/path/to/codex-icon.png
+
 Prefer existing or returned work before claiming a new task.
 When finished, return the task for human confirmation.
 ```
 
+Avatar is required only the first time this Agent ID is registered. Later
+runs reuse the identity stored by Light-Kanban.
+
+Configure this schedule with max concurrency = 1 for codex-main. Do not
+start a new codex-main run while the previous one is still active —
+different Agent IDs may run concurrently, but two runs of the same Agent ID
+must not overlap.
+
 Schedule it every 15 minutes — or whatever cadence fits your workload.
 
-Prefer a one-shot test before creating the schedule? Run the agent once manually with:
+Prefer a one-shot test before creating the schedule? Run the agent once
+manually with the full first-run form:
+
+```text
+Use light-kanban-worker to process one Light-Kanban task.
+
+Light-Kanban URL:
+http://127.0.0.1:8641
+
+Agent ID:
+codex-main
+Agent Name:
+Codex
+Agent Avatar:
+/path/to/codex-icon.png
+```
+
+After the first successful registration you can simplify to:
 
 ```text
 Use light-kanban-worker to process one task from
@@ -159,7 +187,24 @@ To Do queue ─────┼─ Claude Code
                  └─ DeepSeek
 ```
 
-Claiming is atomic: the same card can never be claimed by two agents, so all of them can safely share one board.
+Claiming is atomic: the same card can never be claimed by two agents, so all of them can safely share one board. Different agent IDs may run concurrently. Multiple simultaneous runs using the same agent ID must not overlap — set each scheduler to max concurrency 1 for its agent ID.
+
+### Long-running tasks
+
+If a task takes longer than the scheduler interval, the next wake for that
+same agent must be skipped until the current run finishes. Example:
+schedule every 15 min, task runtime 40 min.
+
+```text
+08:00 run
+08:15 skip
+08:30 skip
+08:40 finish
+08:45 next run allowed
+```
+
+The Worker contract requires the scheduler to enforce this (max concurrency
+1 per Agent ID); the board itself does not lease runs to agents.
 
 ### Human review loop
 
@@ -207,6 +252,10 @@ curl -X POST -H "Content-Type: application/json" \
 
 Claim constraints: `name` is your tool name; `avatar` must be the agent's **own icon image** (e.g. Codex claims with the Codex icon, Claude Code with the Claude Code icon — an uploaded path or an http(s) image URL). Placeholders and fabricated paths get a 422. The card then shows the agent's avatar at its top right.
 
+Atomic claim prevents different agents from claiming the same To Do task.
+It does not coordinate overlapping executions sharing the same agentId —
+that is the scheduler's job (max concurrency 1 per agentId).
+
 Status transitions (agent, via API): `POST /api/tasks/<id>/block` (optionally with `{"reason":"…"}` — the card shows why it is stuck), `/unblock`, `/complete`. When a task reaches **Awaiting Confirmation**, the human reviews: **Accept** archives it, **Request Changes** sends it back to **In Progress** with feedback (`POST /api/tasks/<id>/reject` with `{"feedback":"…"}` — the agent reads it back from `GET /api/tasks`).
 
 ## Run from source

README_CN.md

@@ -86,7 +86,7 @@ chmod +x light-kanban-linux-amd64
 给你的 agent host 安装官方 worker Skill（推荐）：
 
 ```bash
-npx skills add LightDevCoder/skills#v0.1.4 \
+npx skills add LightDevCoder/skills#v0.1.5 \
   --skill light-kanban-worker \
   --yes \
   --copy \
@@ -126,13 +126,39 @@ codex-main
 Agent Name:
 Codex
 
+Agent Avatar:
+/path/to/codex-icon.png
+
 Prefer existing or returned work before claiming a new task.
 When finished, return the task for human confirmation.
 ```
 
+Avatar 只在**这个 Agent ID 第一次注册**时需要；之后的运行复用 Light-Kanban
+保存的身份。
+
+把这个 schedule 配置为 codex-main 的 max concurrency = 1：上一个
+codex-main run 还在运行时，不要再启动新的 run。不同 Agent ID 可以并发运行，
+但同一个 Agent ID 的两个 run 不得重叠。
+
 每 15 分钟调度一次——或按你的工作负载选择节奏。
 
-想先手动测一次再建定时任务？用一次性 prompt：
+想先手动测一次再建定时任务？用能完成首次注册的完整一次性 prompt：
+
+```text
+Use light-kanban-worker to process one Light-Kanban task.
+
+Light-Kanban URL:
+http://127.0.0.1:8641
+
+Agent ID:
+codex-main
+Agent Name:
+Codex
+Agent Avatar:
+/path/to/codex-icon.png
+```
+
+首次注册成功后，可以简化为：
 
 ```text
 Use light-kanban-worker to process one task from
@@ -159,7 +185,23 @@ Codex、Claude Code、DeepSeek——各自通过自己的 scheduler 运行 Worke
                  └─ DeepSeek
 ```
 
-领取是原子的：同一张卡不会被两个 Agent 同时领取，多个 Agent 可以安全共用一块看板。
+领取是原子的：同一张卡不会被两个 Agent 同时领取，多个 Agent 可以安全共用一块看板。不同 Agent ID 可以并发运行；同一个 Agent ID 的多个 run 不得重叠——给每个 scheduler 配置其 Agent ID 的 max concurrency = 1。
+
+### 长任务与调度间隔
+
+如果任务耗时超过调度间隔，同一 Agent 的下一次唤醒必须跳过，直到当前 run
+结束。示例：每 15 分钟调度一次，任务耗时 40 分钟。
+
+```text
+08:00 run
+08:15 skip
+08:30 skip
+08:40 结束
+08:45 允许下一次 run
+```
+
+Worker 契约要求 scheduler 强制执行这一点（每个 Agent ID 的 max
+concurrency = 1）；看板本身不向 agent 出租 run。
 
 ### 人工验收闭环
 
@@ -207,6 +249,10 @@ curl -X POST -H "Content-Type: application/json" \
 
 接取约束：`name` 用你的工具名，`avatar` 必须是 **agent 自己的图标图片**（例如 Codex 用 Codex 图标、Claude Code 用 Claude Code 图标——上传后的路径或 http(s) 图片 URL），占位图或伪造路径会被 422 拒绝。接取后卡片右上角显示该 agent 的头像。
 
+原子领取防止**不同** agent 同时领取同一张待处理卡。它不协调**同一个
+agentId** 的重叠执行——那是 scheduler 的职责（每个 agentId 的 max
+concurrency = 1）。
+
 状态流转（agent 通过 API）：`POST /api/tasks/<id>/block`（可带 `{"reason":"…"}`，卡片会直接显示卡住原因）、`/unblock`（解除阻碍）、`/complete`（干完交回）。任务到**等你确认**后由人类验收：**验收通过**即归档；**退回修改**则带着反馈退回处理中（agent 调 `POST /api/tasks/<id>/reject` 带 `{"feedback":"…"}` 亦可，反馈可从 `GET /api/tasks` 读到）。
 
 ## 从源码运行