claude-threads 1.36.1 → 1.37.1

package/docs/CONFIGURATION.md

@@ -171,6 +171,7 @@ What happens: every `audio/*` attachment (or a file with an audio extension when
 | `outboundFiles` | No | `send_file` settings: `{ enabled, maxBytes }` (defaults: enabled `true`, `maxBytes` 100 MB) |
 | `sessionHeader` | No | Per-thread header visibility: `full` (default) / `minimal` (status bar only) / `hidden` (no header post) |
 | `stickyMessage` | No | Channel sticky visibility: `full` (default) / `minimal` (status bar only) / `hidden` (no sticky, no bumping) |
+| `lifecycle` | No | Session status posts — idle warning, timeout, pause, resume, and the shutdown notice a deploy leaves in each open thread: `full` (default, all of them) / `minimal` (drops the idle warning, which predicts a timeout the next message would undo anyway) / `hidden` (none). Editing a status post the thread already has is not suppressed at any level: it adds no post and no notification, and leaving a stale "session idle" up across a restart would be worse. ⚠️ An **abnormal exit** (`[Exited: <code>]`, non-zero only) posts at every level including `hidden`: it is a failure report, and silencing it would make a session that died look exactly like one that finished. Note that `hidden` also removes the post a 🔄 reaction resumes from — sending a message in the thread still resumes it, and the channel sticky says so. |
 | `directChannelMode` | No | Direct channel mode: the whole channel is one session, and the bot replies with top-level channel posts instead of thread replies. `true` for defaults, or an options object (`respondTo`). See [Direct Channel Mode](#direct-channel-mode). |
 | `approvals` | No | Who may answer tool-permission prompts and other reaction gates: `owner` (session participants) or `all_users` (everyone on `allowedUsers`). Unset keeps the historical default per mode — `all_users` for thread sessions, `owner` for direct channel mode. See [Approvals](#approvals). |
 | `ackReaction` | No | Read receipt: react to every accepted message (session start, follow-up, resume) the instant it is accepted, before Claude produces output. `true` uses 👀 (`eyes`), a string names a custom emoji. Persistent, unlike the typing indicator — useful in busy channels and for messages queued behind an in-flight session start. The receipt means *accepted*, not *delivered*: a later failure (capacity limit, Claude not coming up) is still reported by its own post. `!commands` are not acked — they have their own immediate feedback, and neither are messages accepted through the message-approval flow (an authorized user approving a non-participant's message) — there the approval reaction is already the visible signal. Note: in direct channel mode this is one reaction API call per accepted message. Default off. |
@@ -195,6 +196,7 @@ What happens: every `audio/*` attachment (or a file with an audio extension when
 | `outboundFiles` | No | `send_file` settings: `{ enabled, maxBytes }` (defaults: enabled `true`, `maxBytes` 100 MB) |
 | `sessionHeader` | No | Per-thread header visibility: `full` (default) / `minimal` (status bar only) / `hidden` (no header post) |
 | `stickyMessage` | No | Channel sticky visibility: `full` (default) / `minimal` (status bar only) / `hidden` (no sticky, no bumping) |
+| `lifecycle` | No | Session status posts — idle warning, timeout, pause, resume, and the shutdown notice a deploy leaves in each open thread: `full` (default, all of them) / `minimal` (drops the idle warning, which predicts a timeout the next message would undo anyway) / `hidden` (none). Editing a status post the thread already has is not suppressed at any level: it adds no post and no notification, and leaving a stale "session idle" up across a restart would be worse. ⚠️ An **abnormal exit** (`[Exited: <code>]`, non-zero only) posts at every level including `hidden`: it is a failure report, and silencing it would make a session that died look exactly like one that finished. Note that `hidden` also removes the post a 🔄 reaction resumes from — sending a message in the thread still resumes it, and the channel sticky says so. |
 | `directChannelMode` | No | Direct channel mode: the whole channel is one session, and the bot replies with top-level channel posts instead of thread replies. `true` for defaults, or an options object (`respondTo`). See [Direct Channel Mode](#direct-channel-mode). |
 | `approvals` | No | Who may answer tool-permission prompts and other reaction gates: `owner` (session participants) or `all_users` (everyone on `allowedUsers`). Unset keeps the historical default per mode — `all_users` for thread sessions, `owner` for direct channel mode. See [Approvals](#approvals). |
 | `ackReaction` | No | Read receipt: react to every accepted message (session start, follow-up, resume) the instant it is accepted, before Claude produces output. `true` uses 👀 (`eyes`), a string names a custom emoji. Persistent, unlike the typing indicator — useful in busy channels and for messages queued behind an in-flight session start. The receipt means *accepted*, not *delivered*: a later failure (capacity limit, Claude not coming up) is still reported by its own post. `!commands` are not acked — they have their own immediate feedback, and neither are messages accepted through the message-approval flow (an authorized user approving a non-participant's message) — there the approval reaction is already the visible signal. Note: in direct channel mode this is one reaction API call per accepted message. Default off. |
@@ -369,6 +371,30 @@ platforms:
 
 Note: the per-platform `stickyMessage: <mode>` field is distinct from the top-level `Config.stickyMessage: { description, footer }` block, which still customizes the full sticky for platforms not in `hidden` mode.
 
+#### End-of-turn marker
+
+Integrations that read the channel (a voice front end, a phone bridge, a dashboard) need to know when Claude's answer is complete. The daemon streams by editing one post, so without help they can only guess from the text going quiet. With a marker, the daemon stamps the turn's last reply post the moment the turn ends:
+
+```yaml
+platforms:
+  - id: slack-main
+    type: slack
+    turnMarker: metadata          # reaction | metadata | off (default)
+    # turnMarkerEmoji: checkered_flag   # reaction only; this is the default
+```
+
+| `turnMarker` | What happens | Who sees it |
+|---|---|---|
+| `metadata` | the last reply post gets Slack message metadata `event_type: claude_threads_turn_complete`, `event_payload: { v, session, turn, ok }` | integrations reading `conversations.history` with `include_all_metadata=true`; invisible in the UI. Slack only |
+| `reaction` | the bot reacts on the last reply post with `turnMarkerEmoji` | everyone. Slack and Mattermost |
+| `off` | nothing | |
+
+**Format stability.** The marker is a published integration contract, not an internal detail. Within a 1.x release line, `event_type` will not change, and `event_payload` will only gain fields — never lose one or change the meaning of one. `v` is the payload version; a reader should ignore fields it does not recognize and treat an unknown `v` as "marker present, payload unread". `session` is `platformId:threadId` and is stable across bot restarts and Claude respawns. `turn` counts turns within one bot process: it restarts at 1 after a bot restart and is an ordering hint within a single run, never a unique key. Readers that need exactly-once should dedupe by post id.
+
+`ok` is false when the turn ended with an error. A turn with no reply post marks nothing. A marker failure never touches the reply.
+
+Each marked turn costs one extra API call (a `chat.update` or `reactions.add`) beyond the streaming writes.
+
 ### Memory (`memory`, default: fully enabled)
 
 Each platform instance (≈ one channel) can carry persistent memory, modeled on
@@ -663,6 +689,7 @@ Exactly one of `home` or `apiKey` should be set per account. Persisted sessions
 | `CLAUDE_PATH` | Path to the `claude` binary. Overrides the PATH lookup and the common install locations. | `claude` (from PATH) |
 | `DECISION_BRIDGE_TIMEOUT_MS` | How long the MCP permission server waits for a plan approval or question answer routed through the decision bridge (the bot's reaction UI) before falling back to the legacy behavior (generic prompt for plans, auto-allow for questions). | `3600000` (1 h) |
 | `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` | Strip `ANTHROPIC_*`, `AWS_*_TOKEN`, `CLAUDE_CODE_OAUTH_TOKEN`, `GOOGLE_APPLICATION_CREDENTIALS`, and similar from Bash, hook, and stdio-MCP subprocesses Claude spawns. Bot-specific vars like `PLATFORM_TOKEN` pass through. **Also forces permission mode to `default`**; `--dangerously-skip-permissions` will be rejected. Requires Claude CLI 2.1.83+. | - |
+| `CLAUDE_THREADS_HOME` | Root under which the bot keeps its state (`<root>/.config/claude-threads`, `<root>/.claude-threads`): config, sessions, logs, audit, memory, worktrees, update state. Lets two bots run under the same user without sharing any of it. One process per root; a second start against the same root is refused. | `$HOME` |
 | `CLAUDE_THREADS_SESSIONS_PATH` | Override the path to the persisted sessions file (default `~/.config/claude-threads/sessions.json`). | - |
 | `CLAUDE_THREADS_GITHUB_EMAILS_PATH` | Override the path to the GitHub-emails store used for commit attribution. | - |
 | `CLAUDE_THREADS_MEMORY_DIR` | Override the root of the persistent memory storage (default `~/.config/claude-threads/memory/`). | - |

package/docs/systemd/claude-threads.service

@@ -37,6 +37,9 @@ ExecStart=/usr/bin/env claude-threads-daemon
 # This is a fallback for unexpected crashes
 Restart=on-failure
 RestartSec=10
+# Exit 3 = another instance holds the state directory (see CLAUDE_THREADS_HOME);
+# restarting would only collide again.
+RestartPreventExitStatus=3
 
 # Resource limits (adjust as needed)
 # LimitNOFILE=65536

package/docs/turn-marker-spec.md

@@ -0,0 +1,149 @@
+# Turn marker: the daemon says when a turn is over
+
+Upstream discussion: anneschuth/claude-threads#528 (the maintainer proposed
+this shape on 2026-09-03).
+
+## What it does
+
+A per-platform setting:
+
+```yaml
+platforms:
+  - id: slack-main
+    type: slack
+    turnMarker: metadata        # reaction | metadata | off (default)
+    turnMarkerEmoji: checkered_flag   # reaction only; default checkered_flag
+```
+
+When Claude's turn ends (the CLI's `result` event) the daemon marks **the
+turn's last reply post**:
+
+| `turnMarker` | What happens | Who can see it |
+|---|---|---|
+| `metadata` | the final edit of that post carries Slack message metadata: `event_type: claude_threads_turn_complete`, `event_payload: { v, session, turn, ok }` | integrations reading history with `include_all_metadata`; invisible in the UI. Slack only |
+| `reaction` | the bot adds `turnMarkerEmoji` to that post | everyone, and any integration reading reactions. Slack and Mattermost |
+| `off` | nothing; today's behaviour | |
+
+`ok` is false when the result event reports an error. `turn` counts the
+session's turns from 1. A turn that produced no reply post (only a task
+list, a question, an approval) has nothing to mark and marks nothing.
+
+Untouched: prompts, questions and approvals (a blocked turn has no `result`
+and is not marked; a `turn_waiting` marker for those is a possible follow-up,
+asked in #528), the streaming itself, every other post.
+
+## Why
+
+Any integration that reads the channel has to know when the answer is
+complete. The daemon streams by editing one post, so "the text stopped
+changing" is the only signal today, and every integration reinvents the same
+guess (voice-desk: identical on three polls, ~8–12 s late, wrong when a tool
+pauses the turn). The daemon knows the truth to the millisecond.
+
+## How
+
+- **Config** (`src/config/types.ts`): `turnMarker?: 'reaction' | 'metadata' | 'off'`,
+  `turnMarkerEmoji?: string` on `PlatformInstanceConfig`; resolved with the
+  other per-platform dials into `PlatformOverhead.turnMarker: { mode, emoji }`
+  (`resolveTurnMarker(mode, emoji, platformType, path)`; `metadata` on a
+  non-Slack platform is a startup config error with the field path, because
+  silently marking nothing would be worse; an emoji with another mode is
+  simply ignored — Gemini plan review: YAML anchors and commented-out modes
+  make that a common, harmless state). Wired like `sessionHeader` through
+  `index.ts` → `SessionManager` → `MessageManager` options.
+- **The result event carries its outcome**: `transformResult` sets
+  `resultOk` on the `flush` op it emits (`FlushOp.resultOk?: boolean`, only
+  with `reason: 'result'`). No new op.
+- **One marker write after the final flush** (`MessageManager`, in the
+  `result` flush branch, after `executeFlush`): the content executor's
+  `currentPostId` / `currentPostContent` name the turn's last reply post and
+  its exact text (both plan reviews: piggybacking on "the final write" is
+  fragile because splits, task-post reuse, empty flushes and failed writes
+  all move that write; a dedicated write after the flush is not).
+  - `metadata`: `platform.updatePost(postId, currentPostContent, { metadata })`
+    — Slack's `chat.update` needs text, so the text is re-sent unchanged.
+    The platform's `createPost` / `updatePost` gain an optional
+    `{ metadata }` (Mattermost accepts and drops it).
+  - `reaction`: `platform.addReaction(postId, emoji)`; Slack's
+    `already_reacted` is not an error.
+  - No post (the turn produced only a task list, a question, an approval):
+    nothing to mark. A marker failure is logged and never touches the reply.
+- **Every flush is tracked, not just the timer's** (`runTrackedFlush`): each
+  one records itself in `flushInFlight` for its duration, and the next flush
+  waits for it. A `tool_complete` flush and the `result` flush that follows
+  are both `handleFlushOp` calls, and `SessionManager.handleEvent` does not
+  await its handling — so without this the second starts while the first is
+  still writing, two `updatePost` calls race on one post and complete out of
+  order, and the marker lands on a post a late write then supersedes.
+- **The turn counter** lives in the `MessageManager` (`turn` increments on
+  each `result`), reset with the manager.
+
+## Reading it (what voice-desk does, for the record)
+
+`conversations.history` with `include_all_metadata=true`; a bot post whose
+`metadata.event_type` is `claude_threads_turn_complete` is delivered at once.
+In reaction mode: a bot post carrying the marker emoji from the bot user.
+Without either, the old quiet rule. No configuration on the reader's side.
+
+### `turn` is not durable — only `session` is
+
+`turn` counts turns completed **by one MessageManager process**. It is not
+persisted, so a resumed session starts counting from 1 again and will repeat
+`{session, turn}` pairs it already emitted before the restart. It does *not*
+restart on a Claude respawn (`!cd`, a worktree switch,
+`!permissions interactive`): that is the same chat session, so the count
+carries on.
+
+The count is of turns that **happened**, not of turns that were successfully
+marked: a turn with no reply post, or one whose flush failed, still advances
+it and emits nothing. So a gap means a turn went missing — but only for a
+reader that has watched an unbroken sequence in this process. A reader that
+connects mid-session sees, say, `turn: 7` and cannot tell it from the seventh
+turn of a second run after a restart; it has no baseline to call anything a
+gap. Within one continuous observation window a gap is a real signal; across
+a reconnect it is not.
+
+Treat `turn` as ordering *within one run*, useful for spotting that gap, and
+never as a unique key. `session` is the durable identity; readers that need
+exactly-once should dedupe by post id, which is what voice-desk does. A
+reader that wants durable turn numbers should count marked posts itself.
+
+## Tests (first)
+
+- config: defaults, `metadata` on Mattermost rejected, emoji with `off`
+  ignored, a malformed emoji rejected, custom emoji accepted.
+- transformer: the result flush op carries `resultOk` true/false.
+- message manager: `metadata` re-sends the last post's text with the
+  payload after the result flush, once, and only then; `reaction` adds the
+  emoji; `off` does nothing; a turn with no post marks nothing; a marker
+  failure leaves the reply alone; the turn counter increments; `ok` false
+  on an error result; a split turn marks the continuation (the current
+  post), not the first part; a soft flush still writing is awaited before
+  the result flush (Codex code review: otherwise the marker can land on a
+  post that a slower earlier write then supersedes); two event-driven
+  flushes (a `tool_complete` and the `result` that follows it) do not
+  overlap either — the timer flush was the only tracked writer, so the
+  waiter had nothing to wait on and two `updatePost` calls raced on one
+  post (maintainer review on #547); the payload carries `v` and exactly
+  the published field set.
+- slack client: `chat.update` / `chat.postMessage` body carries `metadata`
+  when given, not otherwise.
+
+## Decisions
+
+| Decision | Why |
+|---|---|
+| One dedicated marker write after the final flush, not piggybacked on it (both plan reviews) | the "final write" moves with splits, task-post reuse, empty flushes and failed writes; one extra `chat.update` per turn is the price of never marking the wrong post |
+| `(session, turn)` is not a cross-restart unique key | the counter lives in the manager and is not persisted; readers dedupe by post id, which is what voice-desk does. Spelled out under **`turn` is not durable** rather than left to be inferred (maintainer review on #547) |
+| A Claude respawn does NOT restart the count | `!cd` and friends replace the CLI process, not the conversation; restarting would re-issue `{session, turn}` pairs the reader has already seen. The old `this.turn = 0` in `reset()` said the opposite and only ever ran from `dispose()`, where the manager is discarded anyway |
+| `reaction` default emoji 🏁 `checkered_flag` | rare in real conversations, reads as "finished" without words |
+| `metadata` refused on Mattermost at config time | rather than silently marking nothing |
+| Payload is small and flat: v, session, turn, ok | Slack caps metadata size; readers need identity and outcome, not the answer |
+| The payload carries a version `v`, and the format is a stated contract | the payload leaves the process and is parsed by code we do not control; once someone builds on it the shape is frozen. `v` is the only escape hatch if it ever has to break, and it costs one field now. The stability statement lives in `docs/CONFIGURATION.md` where integrators read it, not only here (maintainer review on #547) |
+| Emoji names validated lowercase only (Gemini code review suggested allowing uppercase) | Slack and Mattermost create custom emoji names lowercase; an uppercase name in config can only be a typo |
+| One extra `chat.update` per turn is accepted (Gemini code review called it redundant) | see the plan-review decision above: the alternative marks the wrong post under splits and reuse |
+| `ok` from the result event, not from the text | the daemon has the fact; parsing "error" from the reply would be the guess this replaces |
+
+## Lessons learned
+
+(none yet)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-threads",
-  "version": "1.36.1",
+  "version": "1.37.1",
   "description": "Run Claude Code from Slack or Mattermost. Sessions stream live into threads where your whole team can watch and steer.",
   "main": "dist/index.js",
   "type": "module",
@@ -77,7 +77,7 @@
     "commander": "^14.0.2",
     "diff": "^8.0.3",
     "express-rate-limit": "^8.3.0",
-    "hono": "4.13.5",
+    "hono": "4.13.7",
     "ink": "^6.6.0",
     "ink-scroll-view": "^0.3.5",
     "js-yaml": "^4.3.1",
@@ -100,10 +100,10 @@
     "@types/ws": "^8.18.0",
     "eslint": "^10.7.0",
     "husky": "^9.1.7",
-    "knip": "6.34.0",
+    "knip": "6.35.1",
     "lint-staged": "^17.0.4",
     "prettier": "^3.9.5",
-    "react-devtools-core": "^7.0.1",
+    "react-devtools-core": "^8.0.0",
     "typescript": "^6.0.2",
     "typescript-eslint": "^8.64.0"
   },