claude-threads 1.36.1 → 1.37.0

package/dist/mcp/mcp-server.js

@@ -12676,6 +12676,29 @@ var init_emoji = __esm(() => {
   ALLOW_ALL_EMOJIS = ["white_check_mark", "heavy_check_mark"];
 });
 
+// src/config/types.ts
+var STDIO_KEYS, REMOTE_KEYS;
+var init_types = __esm(() => {
+  STDIO_KEYS = new Set(["type", "command", "args", "env"]);
+  REMOTE_KEYS = new Set(["type", "url", "headers"]);
+});
+
+// src/utils/spawn.ts
+import { spawn as nodeSpawn, spawnSync as nodeSpawnSync } from "child_process";
+function addWindowsShell(options) {
+  if (isWindows && options.shell === undefined) {
+    return { ...options, shell: true };
+  }
+  return options;
+}
+function crossSpawn(command, args, options) {
+  return nodeSpawn(command, args, addWindowsShell(options ?? {}));
+}
+var isWindows;
+var init_spawn = __esm(() => {
+  isWindows = process.platform === "win32";
+});
+
 // src/utils/logger.ts
 function createLogger(component, useStderr = false, sessionId) {
   const isDebug = () => process.env.DEBUG === "1";
@@ -14593,7 +14616,7 @@ var require_semver2 = __commonJS(function(exports, module) {
 
 // src/claude/version-check.ts
 import { execSync } from "child_process";
-import { existsSync as existsSync2 } from "fs";
+import { existsSync } from "fs";
 import { join } from "path";
 function tryClaudeVersion(claudePath) {
   try {
@@ -14646,7 +14669,7 @@ function getClaudePath() {
     return whichResult;
   }
   for (const path of COMMON_CLAUDE_PATHS) {
-    if (existsSync2(path)) {
+    if (existsSync(path)) {
       const result = tryClaudeVersion(path);
       if (!result.error) {
         discoveredClaudePath = path;
@@ -14674,29 +14697,6 @@ var init_version_check = __esm(() => {
   ];
 });
 
-// src/utils/spawn.ts
-import { spawn as nodeSpawn, spawnSync as nodeSpawnSync } from "child_process";
-function addWindowsShell(options) {
-  if (isWindows && options.shell === undefined) {
-    return { ...options, shell: true };
-  }
-  return options;
-}
-function crossSpawn(command, args, options) {
-  return nodeSpawn(command, args, addWindowsShell(options ?? {}));
-}
-var isWindows;
-var init_spawn = __esm(() => {
-  isWindows = process.platform === "win32";
-});
-
-// src/config/types.ts
-var STDIO_KEYS, REMOTE_KEYS;
-var init_types = __esm(() => {
-  STDIO_KEYS = new Set(["type", "command", "args", "env"]);
-  REMOTE_KEYS = new Set(["type", "url", "headers"]);
-});
-
 // src/mcp/outbound-env.ts
 var OUTBOUND_ENV;
 var init_outbound_env = __esm(() => {
@@ -14759,7 +14759,7 @@ function buildClaudeChildEnv(parentEnv, account, opts) {
   }
   return env;
 }
-var log14, STDERR_AGGREGATE_SOFT_CAP;
+var log, STDERR_AGGREGATE_SOFT_CAP;
 var init_cli = __esm(() => {
   init_types();
   init_spawn();
@@ -14768,7 +14768,7 @@ var init_cli = __esm(() => {
   init_outbound_env();
   init_agent_features_env();
   init_rate_limit_detector();
-  log14 = createLogger("claude");
+  log = createLogger("claude");
   STDERR_AGGREGATE_SOFT_CAP = 10 * 1024 * 1024;
 });
 
@@ -15007,7 +15007,7 @@ var init_render = __esm(() => {
 });
 
 // src/usage/index.ts
-import { homedir as homedir5 } from "os";
+import { homedir as homedir2 } from "os";
 import path4 from "path";
 function toLimits(usage) {
   const limits = [
@@ -15057,7 +15057,7 @@ async function collectUsage(options) {
     }
     return results;
   }
-  const configDir = process.env.CLAUDE_CONFIG_DIR ?? path4.join(homedir5(), ".claude");
+  const configDir = process.env.CLAUDE_CONFIG_DIR ?? path4.join(homedir2(), ".claude");
   return [await readSeat(profileNameFor(configDir), configDir)];
 }
 var USAGE_PROBE_TIMEOUT_MS = 1e4;
@@ -33912,9 +33912,11 @@ function formatToolForPermission(toolName, input, formatter, options = {}) {
   });
   return result.permissionText ?? result.display ?? toolName;
 }
+// src/operations/transformer.ts
+init_cli();
 // src/session/lifecycle-fsm.ts
 init_logger();
-var log = createLogger("fsm");
+var log2 = createLogger("fsm");
 var ALLOWED_TRANSITIONS = {
   starting: new Set(["active", "paused", "interrupted", "cancelling", "restarting"]),
   active: new Set([
@@ -33956,7 +33958,7 @@ function createSessionLog(baseLog) {
 init_logger();
 
 // src/version.ts
-import { readFileSync, existsSync } from "fs";
+import { readFileSync, existsSync as existsSync2 } from "fs";
 import { dirname, resolve } from "path";
 import { fileURLToPath } from "url";
 var __dirname2 = dirname(fileURLToPath(import.meta.url));
@@ -33967,7 +33969,7 @@ function loadPackageJson() {
     resolve(process.cwd(), "package.json")
   ];
   for (const candidate of candidates) {
-    if (existsSync(candidate)) {
+    if (existsSync2(candidate)) {
       try {
         const pkg = JSON.parse(readFileSync(candidate, "utf-8"));
         if (pkg.name === "claude-threads") {
@@ -33995,23 +33997,34 @@ function formatShortId(id) {
 }
 
 // src/utils/error-handler/index.ts
-var log2 = createLogger("error");
+var log3 = createLogger("error");
 
 // src/operations/post-helpers/index.ts
 init_emoji();
 
 // src/git/worktree.ts
 init_spawn();
+
+// src/utils/state-home.ts
+import { homedir } from "os";
+import { resolve as resolve2 } from "path";
+function stateHome() {
+  return resolve2(process.env.CLAUDE_THREADS_HOME || homedir());
+}
+
+// src/git/worktree.ts
 import * as path from "path";
 init_logger();
-import { homedir } from "os";
-var log3 = createLogger("git-wt");
-var WORKTREES_DIR = path.join(homedir(), ".claude-threads", "worktrees");
-var METADATA_STORE_PATH = path.join(homedir(), ".claude-threads", "worktree-metadata.json");
+var log4 = createLogger("git-wt");
+var WORKTREES_DIR = path.join(stateHome(), ".claude-threads", "worktrees");
+var METADATA_STORE_PATH = path.join(stateHome(), ".claude-threads", "worktree-metadata.json");
 
 // src/operations/post-helpers/index.ts
-var log4 = createLogger("helpers");
-var sessionLog = createSessionLog(log4);
+var log5 = createLogger("helpers");
+var sessionLog = createSessionLog(log5);
+
+// src/operations/message-manager.ts
+init_types();
 
 // src/operations/task-tracker.ts
 var VALID_STATUSES = new Set(["pending", "in_progress", "completed"]);
@@ -34144,7 +34157,7 @@ init_emoji();
 
 // src/persistence/audit-log.ts
 init_logger();
-var log5 = createLogger("audit");
+var log6 = createLogger("audit");
 var enabledPlatforms = new Set;
 var preparedDirs = new Set;
 var openFds = new Map;
@@ -34157,13 +34170,13 @@ init_emoji();
 // src/operations/executors/worktree-prompt.ts
 init_emoji();
 init_logger();
-var log6 = createLogger("wt-prompt");
+var log7 = createLogger("wt-prompt");
 // src/operations/message-manager.ts
 init_logger();
 
 // src/transcription/elevenlabs.ts
 init_logger();
-var log7 = createLogger("transcribe");
+var log8 = createLogger("transcribe");
 
 // src/transcription/types.ts
 var AUDIO_EXTENSIONS = new Set(["m4a", "mp3", "ogg", "opus", "wav", "aac", "flac", "webm"]);
@@ -34192,12 +34205,11 @@ function formatBytes(bytes) {
 }
 
 // src/operations/streaming/handler.ts
-var log8 = createLogger("streaming");
+var log9 = createLogger("streaming");
 // src/operations/message-manager.ts
-var log9 = createLogger("msg-mgr");
+var log10 = createLogger("msg-mgr");
 // src/persistence/session-store.ts
 init_logger();
-import { homedir as homedir2 } from "os";
 import { join as join3 } from "path";
 
 // src/sponsor.ts
@@ -34208,13 +34220,12 @@ function formatSponsorFooter(formatter) {
 }
 
 // src/persistence/session-store.ts
-var log10 = createLogger("persist");
-var DEFAULT_CONFIG_DIR = join3(homedir2(), ".config", "claude-threads");
+var log11 = createLogger("persist");
+var DEFAULT_CONFIG_DIR = join3(stateHome(), ".config", "claude-threads");
 var DEFAULT_SESSIONS_FILE = join3(DEFAULT_CONFIG_DIR, "sessions.json");
 
 // src/config/index.ts
-import { resolve as resolve3, dirname as dirname3 } from "path";
-import { homedir as homedir3 } from "os";
+import { resolve as resolve4, dirname as dirname3 } from "path";
 
 // node_modules/js-yaml/dist/js-yaml.mjs
 function getDefaultExportFromCjs(x) {
@@ -37356,7 +37367,7 @@ init_types();
 init_types();
 
 // src/config/index.ts
-var CONFIG_PATH = resolve3(homedir3(), ".config", "claude-threads", "config.yaml");
+var CONFIG_PATH = resolve4(stateHome(), ".config", "claude-threads", "config.yaml");
 
 // src/utils/battery.ts
 import { exec } from "child_process";
@@ -37365,13 +37376,13 @@ var execAsync = promisify(exec);
 
 // src/changelog.ts
 import { readFileSync as readFileSync2, existsSync as existsSync3 } from "fs";
-import { dirname as dirname4, resolve as resolve4 } from "path";
+import { dirname as dirname4, resolve as resolve5 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 var __dirname3 = dirname4(fileURLToPath2(import.meta.url));
 function getReleaseNotes(version) {
   const possiblePaths = [
-    resolve4(__dirname3, "..", "CHANGELOG.md"),
-    resolve4(__dirname3, "..", "..", "CHANGELOG.md")
+    resolve5(__dirname3, "..", "CHANGELOG.md"),
+    resolve5(__dirname3, "..", "..", "CHANGELOG.md")
   ];
   let changelogPath = null;
   for (const p of possiblePaths) {
@@ -37465,7 +37476,7 @@ init_logger();
 // src/utils/keep-alive.ts
 init_logger();
 import { spawn } from "child_process";
-var log11 = createLogger("keepalive");
+var log12 = createLogger("keepalive");
 function keepAliveSpawnSpec(platform, parentPid) {
   switch (platform) {
     case "darwin":
@@ -37521,7 +37532,7 @@ class KeepAliveManager {
     if (!enabled && this.keepAliveProcess) {
       this.stopKeepAlive();
     }
-    log11.debug(`Keep-alive ${enabled ? "enabled" : "disabled"}`);
+    log12.debug(`Keep-alive ${enabled ? "enabled" : "disabled"}`);
   }
   isEnabled() {
     return this.enabled;
@@ -37531,7 +37542,7 @@ class KeepAliveManager {
   }
   sessionStarted() {
     this.activeSessionCount++;
-    log11.debug(`Session started (${this.activeSessionCount} active)`);
+    log12.debug(`Session started (${this.activeSessionCount} active)`);
     if (this.activeSessionCount === 1) {
       this.startKeepAlive();
     }
@@ -37540,7 +37551,7 @@ class KeepAliveManager {
     if (this.activeSessionCount > 0) {
       this.activeSessionCount--;
     }
-    log11.debug(`Session ended (${this.activeSessionCount} active)`);
+    log12.debug(`Session ended (${this.activeSessionCount} active)`);
     if (this.activeSessionCount === 0) {
       this.stopKeepAlive();
     }
@@ -37554,11 +37565,11 @@ class KeepAliveManager {
   }
   startKeepAlive() {
     if (!this.enabled) {
-      log11.debug("Keep-alive disabled, skipping");
+      log12.debug("Keep-alive disabled, skipping");
       return;
     }
     if (this.keepAliveProcess) {
-      log11.debug("Keep-alive already running");
+      log12.debug("Keep-alive already running");
       return;
     }
     switch (this.platform) {
@@ -37572,12 +37583,12 @@ class KeepAliveManager {
         this.startWindowsKeepAlive();
         break;
       default:
-        log11.warn(`Keep-alive not supported on ${this.platform}`);
+        log12.warn(`Keep-alive not supported on ${this.platform}`);
     }
   }
   stopKeepAlive() {
     if (this.keepAliveProcess) {
-      log11.debug("Stopping keep-alive");
+      log12.debug("Stopping keep-alive");
       this.keepAliveProcess.kill();
       this.keepAliveProcess = null;
     }
@@ -37592,18 +37603,18 @@ class KeepAliveManager {
         detached: false
       });
       this.keepAliveProcess.on("error", (err) => {
-        log11.error(`Failed to start caffeinate: ${err.message}`);
+        log12.error(`Failed to start caffeinate: ${err.message}`);
         this.keepAliveProcess = null;
       });
       this.keepAliveProcess.on("exit", (code) => {
         if (code !== null && code !== 0 && this.activeSessionCount > 0) {
-          log11.debug(`caffeinate exited with code ${code}`);
+          log12.debug(`caffeinate exited with code ${code}`);
         }
         this.keepAliveProcess = null;
       });
-      log11.info("Sleep prevention active (caffeinate)");
+      log12.info("Sleep prevention active (caffeinate)");
     } catch (err) {
-      log11.error(`Failed to start caffeinate: ${err}`);
+      log12.error(`Failed to start caffeinate: ${err}`);
     }
   }
   startLinuxKeepAlive() {
@@ -37616,19 +37627,19 @@ class KeepAliveManager {
         detached: false
       });
       this.keepAliveProcess.on("error", (err) => {
-        log11.debug(`systemd-inhibit not available: ${err.message}`);
+        log12.debug(`systemd-inhibit not available: ${err.message}`);
         this.keepAliveProcess = null;
         this.startLinuxKeepAliveFallback();
       });
       this.keepAliveProcess.on("exit", (code) => {
         if (code !== null && code !== 0 && this.activeSessionCount > 0) {
-          log11.debug(`systemd-inhibit exited with code ${code}`);
+          log12.debug(`systemd-inhibit exited with code ${code}`);
         }
         this.keepAliveProcess = null;
       });
-      log11.info("Sleep prevention active (systemd-inhibit)");
+      log12.info("Sleep prevention active (systemd-inhibit)");
     } catch (err) {
-      log11.debug(`Failed to start systemd-inhibit: ${err}`);
+      log12.debug(`Failed to start systemd-inhibit: ${err}`);
       this.startLinuxKeepAliveFallback();
     }
   }
@@ -37639,15 +37650,15 @@ class KeepAliveManager {
         detached: false
       });
       this.keepAliveProcess.on("error", (err) => {
-        log11.warn(`Linux keep-alive fallback not available: ${err.message}`);
+        log12.warn(`Linux keep-alive fallback not available: ${err.message}`);
         this.keepAliveProcess = null;
       });
       this.keepAliveProcess.on("exit", () => {
         this.keepAliveProcess = null;
       });
-      log11.info("Sleep prevention active (xdg-screensaver)");
+      log12.info("Sleep prevention active (xdg-screensaver)");
     } catch (err) {
-      log11.warn(`Linux keep-alive not available: ${err}`);
+      log12.warn(`Linux keep-alive not available: ${err}`);
     }
   }
   startWindowsKeepAlive() {
@@ -37659,25 +37670,25 @@ class KeepAliveManager {
         windowsHide: true
       });
       this.keepAliveProcess.on("error", (err) => {
-        log11.warn(`Windows keep-alive not available: ${err.message}`);
+        log12.warn(`Windows keep-alive not available: ${err.message}`);
         this.keepAliveProcess = null;
       });
       this.keepAliveProcess.on("exit", (code) => {
         if (code !== null && code !== 0 && this.activeSessionCount > 0) {
-          log11.debug(`PowerShell keep-alive exited with code ${code}`);
+          log12.debug(`PowerShell keep-alive exited with code ${code}`);
         }
         this.keepAliveProcess = null;
       });
-      log11.info("Sleep prevention active (SetThreadExecutionState)");
+      log12.info("Sleep prevention active (SetThreadExecutionState)");
     } catch (err) {
-      log11.warn(`Windows keep-alive not available: ${err}`);
+      log12.warn(`Windows keep-alive not available: ${err}`);
     }
   }
 }
 var keepAlive = new KeepAliveManager;
 
 // src/operations/sticky-message/handler.ts
-var log12 = createLogger("sticky");
+var log13 = createLogger("sticky");
 var botStartedAt = new Date;
 var stickyPostIds = new Map;
 var needsBump = new Map;
@@ -37920,10 +37931,9 @@ init_version_check();
 
 // src/persistence/thread-logger.ts
 init_logger();
-import { homedir as homedir4 } from "os";
 import { join as join4, dirname as dirname5 } from "path";
-var log13 = createLogger("thread-log");
-var LOGS_BASE_DIR = join4(homedir4(), ".claude-threads", "logs");
+var log14 = createLogger("thread-log");
+var LOGS_BASE_DIR = join4(stateHome(), ".claude-threads", "logs");
 
 // src/operations/bug-report/handler.ts
 var piiRedactor = new Redactor({ aggressive: true });
@@ -38830,11 +38840,10 @@ var sessionLog3 = createSessionLog(log21);
 var contextPromptTimeouts = new Map;
 var contextPromptFiles = new Map;
 // src/memory/store.ts
-import { homedir as homedir6 } from "os";
 import { basename as basename3, dirname as dirname6, join as join5, sep as sep2 } from "path";
 init_logger();
 var log22 = createLogger("memory");
-var DEFAULT_ROOT = join5(homedir6(), ".config", "claude-threads", "memory");
+var DEFAULT_ROOT = join5(stateHome(), ".config", "claude-threads", "memory");
 var CHANNEL_BLOCK_MAX_BYTES = 25 * 1024;
 
 // src/memory/distiller.ts
@@ -38849,9 +38858,8 @@ import { join as join7 } from "path";
 init_logger();
 
 // src/persistence/platform-list-store.ts
-import { homedir as homedir7 } from "os";
 import { join as join6 } from "path";
-var STORES_CONFIG_DIR = join6(homedir7(), ".config", "claude-threads");
+var STORES_CONFIG_DIR = join6(stateHome(), ".config", "claude-threads");
 
 // src/persistence/routines-store.ts
 var log24 = createLogger("routines");
@@ -38904,11 +38912,10 @@ init_logger();
 init_quick_query();
 
 // src/persistence/github-emails-store.ts
-import { homedir as homedir8 } from "os";
 import { join as join9 } from "path";
 init_logger();
 var log32 = createLogger("gh-emails");
-var DEFAULT_CONFIG_DIR2 = join9(homedir8(), ".config", "claude-threads");
+var DEFAULT_CONFIG_DIR2 = join9(stateHome(), ".config", "claude-threads");
 var DEFAULT_FILE3 = join9(DEFAULT_CONFIG_DIR2, "github-emails.yaml");
 
 // src/operations/commands/handler.ts

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