talking-stick 0.1.0-alpha.1 → 0.1.0-alpha.3

package/README.md

@@ -2,7 +2,7 @@
 
 An MCP coordination server that lets multiple AI coding agents share a single workspace without stepping on each other. One agent holds the stick at a time; handoffs carry structured context so the next agent doesn't have to re-derive it.
 
-**Version:** 0.1.0-alpha. Multi-process-safe (SQLite WAL), liveness-aware, no daemon. Supports Claude Code, Codex CLI, Gemini CLI, and OpenCode out of the box.
+**Version:** 0.1.0-alpha.3. Multi-process-safe (SQLite WAL), liveness-aware, no daemon. Supports Claude Code, Codex CLI, Gemini CLI, and OpenCode out of the box.
 
 ## Quickstart
 
@@ -27,7 +27,7 @@ That's it. The next time two agents `cd` into the same repo, they see each other
 
 | Method | Command | Notes |
 |---|---|---|
-| **From npm** | `npm i -g talking-stick` | Published as `0.1.0-alpha`. Requires Node ≥ 22. |
+| **From npm** | `npm i -g talking-stick` | Published as `0.1.0-alpha.3`. Requires Node ≥ 22. |
 | **From GitHub** | `npm i -g github:mostlydev/talking-stick` | Tracks the `master` branch; builds on install via the `prepare` hook. |
 | **From source** | `git clone … && npm install && npm link` | For contributors. |
 
@@ -49,6 +49,8 @@ tt install claude-code codex
 tt install-skill gemini
 ```
 
+During normal execution, install commands skip harnesses that are not present instead of failing or creating new harness config roots. For example, `tt install-skill codex` only creates `~/.codex/skills/` if `~/.codex/` already exists.
+
 ### Remove
 
 ```bash
@@ -65,11 +67,13 @@ list_rooms         — which rooms exist under a path
 join_path          — join the room for this workspace
 wait_for_turn      — block until the stick is available, with takeover signals
 heartbeat          — prove liveness while holding the stick
-release_stick      — normal handoff to the next member, with structured Handoff
+release_stick      — normal handoff to the next fair waiter, with structured Handoff
 pass_stick         — explicit handoff to a named agent
 takeover_stick     — deliberate claim when the prior holder is gone/stuck
 get_room_state     — authoritative state projection
 get_room_events    — audit log of turn transitions
+add_note           — leave an async observation for the current owner
+list_notes         — read notes left for the room
 ```
 
 A workspace maps to a room — usually the `git` root or nearest project marker — so two agents `cd`'d anywhere under the same repo join the same room automatically.
@@ -79,6 +83,14 @@ The skill complements the MCP tools:
 - MCP gives the harness the coordination surface
 - the global skill tells the model when to join, wait, heartbeat, take over, and hand off
 
+## Non-owner notes
+
+While you wait your turn you may still need to flag something to the current owner: a subtle invariant, a related bug, a pointer to a doc. Non-owner notes give you a durable channel without interrupting the turn.
+
+- Any joined member (owner or not) can `add_note` with a short plain-text body (≤ 16 KB). An optional `turn_id` scopes the note to a specific turn; omitted, the note is room-scoped and survives turn transitions.
+- `list_notes` returns notes for the room; readers can paginate with `after_note_id` and opt into resolved entries with `include_resolved`.
+- Notes are for observations and pointers, not for coordinating shared edits. Shared workspace changes still require holding the stick.
+
 ## How installation works per harness
 
 `tt install` prefers each harness's own `mcp add` subcommand when available (so the server ends up in the right user-global config with the right schema), and falls back to direct JSON editing when it isn't.
@@ -105,11 +117,14 @@ Talking Stick also ships with a portable `talking-stick` skill:
 
 By default, `tt install-skill` links the bundled skill into each harness so local updates are picked up immediately. Pass `--copy` if you want a standalone snapshot instead.
 
+Human CLI invocations also perform a silent best-effort sync for already-installed file-based skills in Claude Code, Codex, and OpenCode. If the installed skill is a copy, it is refreshed from the bundled skill; if it is a stale symlink, it is relinked. Missing harness config directories and missing skill installs are skipped. Gemini skills are managed by Gemini's own registry, so use `tt install-skill gemini` after updating when needed.
+
 ## Human CLI
 
 The same `tt` binary also works as a human CLI, useful for watching or participating in a room from your terminal:
 
 ```text
+tt whoami [--explain]                                      # show the resolved CLI identity
 tt list [path]                                            # list rooms
 tt join [path] [--force-new]                              # join the room for path
 tt wait [path] [--timeout 30s]                            # block until your turn
@@ -117,21 +132,42 @@ tt try [path]                                             # non-blocking claim a
 tt state [path]                                           # full room state
 tt events [path] [--after N] [--limit N]                  # room event log
 tt release [path] --status TEXT --next-action TEXT        # normal handoff
-tt pass [target] [path] --status TEXT --next-action TEXT  # explicit handoff
-tt takeover [path] --reason TEXT                          # deliberate takeover
+tt pass [path] --status TEXT --next-action TEXT           # pass/end your turn
+tt assign <target|next> [path] --status TEXT --next-action TEXT  # explicit handoff
+tt take [path] [--reason TEXT]                            # human-friendly take/override
+tt takeover [path] [--reason TEXT]                        # alias for take
+tt notes add <body> [--turn N] [--path DIR] [--stdin]     # leave an async note
+tt notes list [--all] [--after ID] [--limit N] [--path DIR] # read notes
 tt mcp                                                    # run the MCP stdio server
 tt install <harness...> | --all [--print]                 # register MCP server
 tt uninstall <harness...> | --all [--print]               # remove MCP server
 tt install-skill <harness...> | --all [--print] [--copy] [--link]  # install global talking-stick skill
 tt uninstall-skill <harness...> | --all [--print]         # remove global talking-stick skill
+tt self-update [--print] [--manager npm|pnpm|yarn|bun]    # update to the latest published tt
 ```
 
-Human CLI commands use a stable identity like `human:<username>`. When `tt wait` or `tt takeover` wins the turn, a small background guardian keeps the lease alive on your behalf until you release or pass it.
+`tt self-update` detects how `tt` was installed (npm / pnpm / yarn / bun, including npm-via-Homebrew/mise/asdf/nvm) and runs the right global-update command. Pass `--print` to see the inferred command without running it; pass `--manager` to override detection. Running `tt self-update` from a development checkout (where `tt` resolves outside `node_modules/talking-stick`) refuses and tells you to `git pull && npm install && npm run build` instead.
+
+Human CLI commands use a stable identity like `human:<username>`. When `tt wait`, `tt take`, or `tt takeover` wins the turn, a small background guardian keeps the lease alive on your behalf until you release, pass, or assign it. Human CLI `take` intentionally works without a required reason so an operator can step into a stuck room quickly; harness-aware CLI takeovers still require `--reason` unless the command includes `--operator-requested`.
+
+### CLI identity
+
+By default, `tt` behaves like a human CLI and resolves to `human:<username>`, even when you run it from a shell embedded inside Claude Code, Codex, Gemini, or OpenCode.
+
+Harness-aware CLI identity is now explicit:
+
+- Set `TT_HARNESS_EXPORT=1` if you want `tt` to derive a harness-style identity from the current environment and process ancestry.
+- Set `TT_HARNESS_AGENT_ID=<agent-id>` if the harness wants to export the exact agent id directly.
+
+If neither variable is set, `tt` stays on the human CLI path. That keeps ordinary shell usage predictable and avoids silently turning a human terminal into a harness participant.
+
+Use `tt whoami --explain` to see which identity path the CLI chose.
 
 ## Design highlights
 
 - **Workspace-root room resolution.** An agent at any depth under `/repo/` joins the `/repo/` room automatically. Nested rooms require explicit `force_new`.
 - **Structured handoffs.** `release_stick` and `pass_stick` carry a typed `Handoff` with required `status` / `next_action` and optional `artifacts[]` pointing at specific files and line ranges.
+- **Fair handoff selection.** Normal release prefers a recent waiter that is new or has gone longest without holding the stick; if the best-known candidate is between wait polls, a short grace window prevents immediate recycling to a less-fair claimant.
 - **Fencing tokens.** `lease_id` + `turn_id` make stale writes impossible — an agent who lost their turn cannot commit anything under the room's name.
 - **Liveness-aware recovery.** Dead or crashed holders are detected with OS-level process checks; claim-timeout takeover skips the prior owner when another active member is waiting.
 - **Multi-process safe.** Shared SQLite with WAL mode, `BEGIN IMMEDIATE` writes, 250 ms polling for `wait_for_turn`. No daemon required.
@@ -155,10 +191,15 @@ npm run typecheck
 npm run build
 ```
 
+## Changelog
+
+See [`CHANGELOG.md`](CHANGELOG.md) for a per-version summary; full release notes live in [`docs/releases/`](docs/releases/).
+
 ## Read next
 
 - [`docs/talking-stick-plan.md`](docs/talking-stick-plan.md) — full protocol, state transitions, persistence model, design rationale, and open questions.
 - [`docs/ambient-presence.md`](docs/ambient-presence.md) — design sketch for shell-prompt awareness, event streaming, and agent skills that make room state ambient rather than appointment-only.
+- [`docs/non-owner-notes.md`](docs/non-owner-notes.md) — design backing the v1 notes feature; documents what shipped, what was deferred (`resolve_note`, wait_for_turn unread hints), and the rationale.
 - [`skills/talking-stick/SKILL.md`](skills/talking-stick/SKILL.md) — the portable skill installed into global harness skill directories.
 
 ## License