Release v6.2.7 config sources and stop cleanup

Author: SeemSeam

CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+## v6.2.7 (2026-05-21)
+
+### Config Source And Stop Cleanup Release
+
+- **Three-Layer Config Sources Added**: config resolution now reports explicit source kinds for built-in defaults, user config at `~/.ccb/ccb.config`, and project config at `.ccb/ccb.config`, with project config taking highest priority.
+- **Config Validate Output Clarified**: `ccb config validate` now surfaces `config_source_kind` and `used_builtin_default`, and README/docs/`ccb_config` skill guidance describe the active config layer instead of assuming only project config.
+- **Kill Cleanup Ordering Fixed**: `stop_all` now defers project tmux namespace destruction until after the socket response finalizer, so `ccb kill` and `ccb kill -f` launched from a CCB tmux pane can finish daemon cleanup before their pane is destroyed.
+
 ## v6.2.6 (2026-05-20)
 
 ### Tmux Isolation And Startup Hardening Release

README.md

@@ -7,7 +7,7 @@
   <img src="https://img.shields.io/badge/Every_Model_Controllable-CF1322?style=for-the-badge" alt="Every Model Controllable">
 </p>
 
-[![Version](https://img.shields.io/badge/version-6.2.6-orange.svg)]()
+[![Version](https://img.shields.io/badge/version-6.2.7-orange.svg)]()
 [![Platform](https://img.shields.io/badge/platform-Linux%20%7C%20macOS%20%7C%20Windows-lightgrey.svg)]()
 
 **English** | [Chinese](README_zh.md)
@@ -74,9 +74,9 @@ Build project-local teams with roles, pane layout, provider state, worktree isol
 <details>
 <summary><b>Latest release highlights</b></summary>
 
-- **CCB tmux is isolated from user config by default**: managed tmux commands now use `tmux -f /dev/null ...`, preventing user `~/.tmux.conf` plugins and hooks from changing CCB pane layout.
-- **Source installs are more deterministic**: source/dev installs use a Python wrapper, honor `CCB_PYTHON_BIN`, run post-install entrypoint smoke checks, and bound Droid MCP registration with a timeout.
-- **Provider startup stays compatible and reliable**: restore-fresh takes effect, Claude trust state is written in the managed home, and Claude auto-permission continues to use `--permission-mode bypassPermissions`.
+- **Config sources are explicit**: CCB now reports whether the effective config came from the built-in default, user `~/.ccb/ccb.config`, or project `.ccb/ccb.config`.
+- **`ccb config validate` shows the active layer**: validation output now includes `config_source_kind` and `used_builtin_default`, and docs/`ccb_config` guidance match the three-layer precedence.
+- **`ccb kill` cleanup is ordered after the response**: project tmux namespace destruction is deferred until after `stop_all` finalization, so cleanup completes even when kill is launched from a CCB tmux pane.
 
 See [Release Notes](#release-notes) for the full history.
 
@@ -98,7 +98,7 @@ Tmux copy/paste: drag with the left mouse button to copy, and use `Ctrl+Shift+V`
 
 ## Config Control
 
-`ccb` is controlled by `.ccb/ccb.config`. This file is project-local and user-authored; if it is missing, CCB uses `~/.ccb/ccb.config` when present, then falls back to the built-in default without writing a new project config file.
+`ccb` resolves config in three layers: built-in default, user config at `~/.ccb/ccb.config`, then project config at `.ccb/ccb.config`. Project config has highest priority; if it is missing, CCB uses the user config when present, then the built-in default, without writing a new project config file.
 
 `.ccb/ccb_memory.md` is the project-wide shared memory document.
 
@@ -117,7 +117,7 @@ Invoke it from a supported provider skill surface, for example:
 $ccb_config Design a team for a Python library with one coordinator, two worktree implementation agents, and one reviewer.
 ```
 
-The skill helps choose agent names, providers, `inplace` versus `git-worktree`, compact layout syntax, and whether role instructions belong in shared or per-agent memory. It validates that `.ccb/ccb.config` is the active authority and tells you to restart CCB after file changes are complete.
+The skill helps choose agent names, providers, `inplace` versus `git-worktree`, compact layout syntax, and whether role instructions belong in shared or per-agent memory. It validates which config layer is active and tells you to restart CCB after file changes are complete.
 
 </details>
 
@@ -338,6 +338,15 @@ Thanks to the [Linux.do community](https://linux.do) for testing, feedback, and
 Historical note: older release notes below may mention `askd`, legacy flags, or removed commands. Those references are kept only as changelog history and do not redefine the current CLI surface.
 
 <details open>
+<summary><b>v6.2.7</b> - Config Source And Stop Cleanup Release</summary>
+
+- Reports explicit config source kinds for built-in defaults, user `~/.ccb/ccb.config`, and project `.ccb/ccb.config`, with project config taking highest priority.
+- Updates `ccb config validate`, README/docs, and inherited `ccb_config` skill guidance to describe the active config layer.
+- Defers project tmux namespace destruction until after the stop-all response finalizer so `ccb kill` / `ccb kill -f` can complete cleanup from inside a CCB pane.
+
+</details>
+
+<details>
 <summary><b>v6.2.6</b> - Tmux Isolation And Startup Hardening Release</summary>
 
 - Runs managed tmux commands with `tmux -f /dev/null ...` by default so user tmux config, plugins, hooks, and sidebars cannot reshape CCB-managed layouts.

README_zh.md

@@ -7,7 +7,7 @@
   <img src="https://img.shields.io/badge/模型皆可控-CF1322?style=for-the-badge" alt="模型皆可控">
 </p>
 
-[![Version](https://img.shields.io/badge/version-6.2.6-orange.svg)]()
+[![Version](https://img.shields.io/badge/version-6.2.7-orange.svg)]()
 [![Platform](https://img.shields.io/badge/platform-Linux%20%7C%20macOS%20%7C%20Windows-lightgrey.svg)]()
 
 [English](README.md) | **中文**
@@ -74,9 +74,9 @@
 <details>
 <summary><b>最新版本亮点</b></summary>
 
-- **CCB tmux 默认隔离用户配置**：managed tmux 命令现在使用 `tmux -f /dev/null ...`，避免用户 `~/.tmux.conf` 插件、hook 或 sidebar 改写 CCB pane layout。
-- **源码安装更稳定**：source/dev 安装使用 Python wrapper，支持 `CCB_PYTHON_BIN`，安装后执行真实 entrypoint smoke test，并给 Droid MCP 注册加超时。
-- **Provider 启动保持兼容和可靠**：restore-fresh 正确生效，Claude trust 写入 managed home，Claude auto-permission 继续使用 `--permission-mode bypassPermissions`。
+- **配置来源显式化**：CCB 现在会报告当前配置来自内置默认、用户 `~/.ccb/ccb.config`，还是项目 `.ccb/ccb.config`。
+- **`ccb config validate` 显示生效层级**：validate 输出新增 `config_source_kind` 和 `used_builtin_default`，README/docs/`ccb_config` 说明也对齐三层优先级。
+- **`ccb kill` 清理顺序修复**：project tmux namespace destroy 延后到 `stop_all` 回包后的 finalize 阶段，避免从 CCB tmux pane 执行 kill 时清理只跑一半。
 
 完整历史见 [新版本记录](#新版本记录)。
 
@@ -98,7 +98,7 @@ tmux 复制粘贴：鼠标左键拖拽即可复制，`Ctrl+Shift+V` 粘贴。
 
 ## 配置控制
 
-`ccb` 的行为由 `.ccb/ccb.config` 控制。它是项目级、用户自己维护的配置文件；如果不存在，CCB 会优先使用 `~/.ccb/ccb.config`，再回退到代码内置默认配置，并且不会自动写入新的项目配置文件。
+`ccb` 按三层解析配置：代码内置默认配置、用户配置 `~/.ccb/ccb.config`、项目配置 `.ccb/ccb.config`。项目配置优先级最高；如果项目配置不存在，CCB 会优先使用用户配置，再回退到代码内置默认配置，并且不会自动写入新的项目配置文件。
 
 `.ccb/ccb_memory.md` 是项目全局记忆文档。
 
@@ -117,7 +117,7 @@ tmux 复制粘贴：鼠标左键拖拽即可复制，`Ctrl+Shift+V` 粘贴。
 $ccb_config 为一个 Python library 设计团队：一个 coordinator、两个 worktree 实现 agent、一个 reviewer。
 ```
 
-这个 skill 会帮助选择 agent 名称、provider、`inplace` / `git-worktree`、compact layout 语法，以及哪些说明应写入共享记忆或 per-agent memory。它会验证 `.ccb/ccb.config` 是当前配置 authority，并在文件修改完成后提醒你重启 CCB。
+这个 skill 会帮助选择 agent 名称、provider、`inplace` / `git-worktree`、compact layout 语法，以及哪些说明应写入共享记忆或 per-agent memory。它会验证当前生效的配置层，并在文件修改完成后提醒你重启 CCB。
 
 </details>
 
@@ -329,6 +329,15 @@ ccb reinstall
 历史说明：下面较旧的发布记录里仍可能出现 `askd`、旧 flag 或已移除命令。这些内容仅作为 changelog 历史保留，不代表当前 CLI 入口。
 
 <details open>
+<summary><b>v6.2.7</b> - Config Source And Stop Cleanup Release</summary>
+
+- 显式报告配置来源：内置默认、用户 `~/.ccb/ccb.config`、项目 `.ccb/ccb.config`，并保持项目配置优先级最高。
+- 更新 `ccb config validate`、README/docs 和继承的 `ccb_config` skill 说明，统一描述当前生效的配置层。
+- 将 project tmux namespace destroy 延后到 stop-all response finalizer 之后，让从 CCB pane 执行的 `ccb kill` / `ccb kill -f` 能完成后台清理。
+
+</details>
+
+<details>
 <summary><b>v6.2.6</b> - Tmux Isolation And Startup Hardening Release</summary>
 
 - managed tmux 命令默认使用 `tmux -f /dev/null ...`，避免用户 tmux 配置、插件、hook 或 sidebar 改变 CCB-managed layout。

VERSION

@@ -1 +1 @@
-6.2.6
+6.2.7

ccb

@@ -21,7 +21,7 @@ backend_env = get_backend_env()
 if backend_env and not os.environ.get("CCB_BACKEND_ENV"):
     os.environ["CCB_BACKEND_ENV"] = backend_env
 
-VERSION = "6.2.6"
+VERSION = "6.2.7"
 GIT_COMMIT = "release"
 GIT_DATE = "2026-05-11"
 

docs/ccb-config-layout-contract.md

@@ -9,17 +9,22 @@ It is the authoritative design anchor for:
 - `.ccb/ccb.config`
 - `.ccb/ccb_memory.md` and `.ccb/agents/<agent>/memory.md` project memory placement
 - compact layout grammar
-- built-in default config fallback
+- config source precedence and fallback
 - pane naming and pane color identity
 - tmux split sizing rules for the project UI
 
 ## 2. User-Facing Config Contract
 
-- `.ccb/ccb.config` is the only user-facing project config file.
+- Effective config is resolved in three layers:
+  1. built-in default config from code;
+  2. user config at `~/.ccb/ccb.config`;
+  3. project config at `.ccb/ccb.config`.
+- Higher layers override lower layers by replacing the whole effective config; CCB does not merge partial config documents across layers.
+- `.ccb/ccb.config` is the highest-priority user-facing project config file.
+- `~/.ccb/ccb.config` is the user-level config file used only when project config is absent.
 - CCB must not auto-create, reconstruct, or rewrite `.ccb/ccb.config`; it is a user-authored project file.
-- When `.ccb/ccb.config` is absent, config loading must use the built-in default project config from code and report the source as `<default>`.
-- CCB must not read an implicit global `~/.ccb/ccb.config` or install-location config as a fallback.
-- User help text, validation output, diagnostics, and docs must point to `.ccb/ccb.config`.
+- When both `.ccb/ccb.config` and `~/.ccb/ccb.config` are absent, config loading must use the built-in default project config from code and report the source kind as `builtin_default`.
+- User help text, validation output, diagnostics, and docs must report the active config source kind: `project_config`, `user_config`, or `builtin_default`.
 - `.ccb/config.yaml` is not part of the contract and must not be read or written by current code.
 
 ### 2.1 Project Shared Memory Files

docs/ccbd-startup-supervision-contract.md

@@ -122,8 +122,11 @@ Out of scope:
 
 ### 5.3 Desired Agent Set
 
-- `.ccb/ccb.config` is the only forward authority for the project's desired agent mount set and foreground layout.
-- `.ccb/ccb.config` logical names are also the only forward authority for project-namespace pane display names.
+- Effective config is resolved in three layers: built-in default, user config at `~/.ccb/ccb.config`, then project config at `.ccb/ccb.config`.
+- `.ccb/ccb.config` is the highest-priority forward authority for the project's desired agent mount set and foreground layout when it exists.
+- When `.ccb/ccb.config` is absent, `~/.ccb/ccb.config` is the user-level forward authority for the project's desired agent mount set and foreground layout when it exists.
+- When both files are absent, the built-in default config is the forward authority for the desired agent mount set and foreground layout.
+- Effective config logical names are the only forward authority for project-namespace pane display names.
 - Until a future explicit `enabled` or `desired_state` field exists, all configured agents are desired agents.
 - `default_agents` and CLI `requested_agents` do not redefine long-lived backend ownership.
 - `requested_agents` may affect foreground behavior or warm-start order only.
@@ -132,7 +135,7 @@ Out of scope:
 
 Authority order must be enforced exactly as follows:
 
-1. `.ccb/ccb.config`
+1. effective config, resolved as `.ccb/ccb.config` > `~/.ccb/ccb.config` > built-in default
 2. `.ccb/ccbd/lifecycle.json`
 3. `.ccb/ccbd/lease.json`
 4. `.ccb/ccbd/start-policy.json`

inherit_skills/claude_skills/ccb_config/SKILL.md

@@ -5,11 +5,11 @@ description: Design and edit CCB project teams by updating .ccb/ccb.config plus
 
 # CCB Config
 
-Use this skill to design and edit a CCB-managed project team. The output is a valid `.ccb/ccb.config` plus preserved project memory updates in `.ccb/ccb_memory.md` and `.ccb/agents/<agent>/memory.md`.
+Use this skill to design and edit a CCB-managed project team. The usual output is a valid `.ccb/ccb.config` plus preserved project memory updates in `.ccb/ccb_memory.md` and `.ccb/agents/<agent>/memory.md`. If the user explicitly asks for a user-level default team, edit `~/.ccb/ccb.config` instead.
 
 ## Core Workflow
 
-1. Resolve the config authority first. The current CCB project config is `.ccb/ccb.config`; `.ccb_config/ccb.config` is legacy residue and must be treated as read-only migration evidence, not as the file to edit.
+1. Resolve the config authority first. CCB config precedence is built-in default < user config `~/.ccb/ccb.config` < project config `.ccb/ccb.config`. `.ccb_config/ccb.config` is legacy residue and must be treated as read-only migration evidence, not as the file to edit.
 2. Read the current `.ccb/ccb.config`, `.ccb/ccb_memory.md`, and relevant `.ccb/agents/<agent>/memory.md` files before proposing changes.
 3. If the user's project goal and workflow are not already clear, ask a short clarification question before designing the team.
 4. After the basic workflow is clear, propose one complete config with sensible defaults and ask for confirmation or adjustments.
@@ -18,11 +18,13 @@ Use this skill to design and edit a CCB-managed project team. The output is a va
    - `.ccb/ccb.config`
    - `.ccb/ccb_memory.md`
    - `.ccb/agents/<agent>/memory.md`
-7. Validate the written config with the CCB config loader and verify that the loader read `.ccb/ccb.config`, not the built-in default config.
+7. Validate the written config with the CCB config loader and verify that the loader read the intended source kind.
 8. Tell the user that CCB must be restarted for config changes to take effect.
 
 Do not write runtime state, generated memory, provider-state homes, `.ccb/provider-profiles/`, `.ccb/ccbd/`, legacy `.ccb_config/`, or provider-native project dotfiles such as `.codex`, `.claude`, or `.gemini`.
 
+By default, configure the current project by writing `.ccb/ccb.config`. Only write `~/.ccb/ccb.config` when the user explicitly asks for a user-level or system-wide default CCB team.
+
 Never run `ccb`, `ccb -s`, `ccb kill`, or any restart command as part of this skill workflow. Restarting from inside an active CCB pane can terminate the current session before file edits and validation finish. Finish all file writes and validation first, then tell the user the restart command to run manually.
 
 ## Interaction Pattern
@@ -153,19 +155,21 @@ python - <<'PY'
 from pathlib import Path
 from agents.config_loader import load_project_config
 result = load_project_config(Path('.'))
-if result.used_default or result.source_path is None:
+if result.source_kind != 'project_config' or result.source_path is None:
     raise SystemExit('ERROR: .ccb/ccb.config was not loaded; write the current config authority before validating')
 print(f'{len(result.config.agents)} agents OK: {", ".join(result.config.default_agents)}')
 PY
 ```
 
+After editing `~/.ccb/ccb.config` as the user-level default, validate from a temporary directory without a project config and require `source_kind == "user_config"`.
+
 Also check:
 
 - agent names are valid and not reserved;
 - every configured default agent appears exactly once in the layout;
 - `cmd` is first when enabled;
 - compact/hybrid worktree markers are present on the compact line, not in overlay;
-- validation reports `used_default = False` and a non-empty `source_path`;
+- validation reports the intended `source_kind` and a non-empty `source_path`;
 - no secrets were added unless the user explicitly provided them;
 - memory updates preserved existing unmarked content.
 

inherit_skills/claude_skills/ccb_config/references/ccb-config.md

@@ -2,7 +2,17 @@
 
 ## Authority Files
 
-`.ccb/ccb.config` is the only user-facing project config authority. When it is missing, CCB uses a built-in default and does not write a new file automatically.
+Effective config precedence is:
+
+1. built-in default config from code;
+2. user config at `~/.ccb/ccb.config`;
+3. project config at `.ccb/ccb.config`.
+
+Higher layers replace the whole lower-layer config; CCB does not merge partial config documents across layers.
+
+`.ccb/ccb.config` is the highest-priority project config authority. When it is missing, CCB uses `~/.ccb/ccb.config` if present, then the built-in default. CCB does not write a new project config automatically.
+
+Only write `~/.ccb/ccb.config` when the user explicitly wants a user-level or system-wide default CCB team. For ordinary project setup, write `.ccb/ccb.config`.
 
 Do not write `.ccb_config/ccb.config`. That path is legacy residue in older or migrated workspaces. You may read it as migration evidence, but the current config must be created or updated at `.ccb/ccb.config`.