@excitedjs/dreamux 0.22.0-beta.150 → 0.22.0-beta.151

package/README.md

@@ -24,13 +24,15 @@ Design background:
 - Public CLI bin: `dreamux`. It owns onboarding, serving, status, doctor,
   dispatcher commands, and config commands. TeamMate and Team orchestration are
   available through Dreamux-owned MCP surfaces.
-- Bundled Dreamux skills injected at runtime by role (issue #209 slice 6):
+- Bundled Dreamux skills injected at runtime by role (issues #209 and #313):
   core hands the Dispatcher `dispatcher-workflow` and `dreamux-maintenance`, the
-  TeamLeader `team-workflow`, and the runtime applies them to its engine (Codex
-  `skills/extraRoots/set`, Claude Code `--add-dir`). The package exposes
-  role-specific skill roots so root scanning cannot cross role boundaries.
-  `dreamux onboard` does not install bundled skills into
-  dispatcher workspaces.
+  TeamLeader `team-workflow`, and both roles the shared `workflow` skill. The
+  runtime applies those role-specific plus shared roots to its engine (Codex
+  `skills/extraRoots/set`, Claude Code `--add-dir`). Role-specific roots remain
+  disjoint, while the shared root is deliberately composed into both roles.
+  For admin-created TeamLeaders, required-source normalization protects both
+  `team-workflow` and `workflow` from custom skill-root shadowing. `dreamux
+  onboard` does not install bundled skills into dispatcher workspaces.
 - Providerized dispatcher declarations, a process-local provider registry,
   server-owned state/log paths, the `builtin:feishu` Channel provider, the
   `builtin:codex` and `builtin:claude-code` Agent Runtime providers, and
@@ -107,11 +109,11 @@ logs:
 
 | Path | Purpose | Source of truth |
 |---|---|---|
-| `~/.dreamux/config.json` | User-editable provider config and local channel credentials, created by `dreamux onboard`; edit and restart to apply | the operator |
+| `dreamux config path` (normally `~/.dreamux/config.json`) | User-editable provider config and local channel credentials, created by `dreamux onboard`; edit and restart to apply | the operator |
 | `~/.dreamux/run/admin.sock` | Admin Unix socket (+ `admin.sock.lock`); volatile run file | the server |
 | `~/.dreamux/run/restart-intent.json` | One-shot daemon restart marker; volatile run file | the server |
 | `~/.dreamux/run/sockets/` | Fallback root for ephemeral Codex app-server rendezvous sockets (preferred root: `$XDG_RUNTIME_DIR/dreamux/sockets/`); random per start, never persisted | the server |
-| `~/.dreamux/state/<id>/access.json` | Dispatcher-local access-gate state | the server |
+| `~/.dreamux/state/<id>/access.json` | Dispatcher-local Feishu access state: schema/runtime ledger are Channel-owned; policy fields and quiesced `allow_users` maintenance are operator-authorized | mixed |
 | `~/.dreamux/state/<id>/identity.json` | Dispatcher root agent identity and runtime recovery state | the server |
 | `~/.dreamux/state/<id>/teammate/` | TeamMate task ledger, results, and delivery retry state | the server |
 | `~/.dreamux/cache/<id>/spill/` | Over-budget teammate completion spill files; rebuildable cache, only the path is inlined into a dispatcher turn | the server |
@@ -122,9 +124,9 @@ logs:
 | `~/.dreamux/logs/teammate-mcp/<id>.log` | TeamMate MCP shim diagnostics | the server |
 | `~/.codex/` | Codex global default home: auth, memory, and config | the operator / Codex |
 
-`rm -rf ~/.dreamux/run ~/.dreamux/cache ~/.dreamux/state ~/.dreamux/logs` is a
-run/cache/state/log recovery path (only while no server is running); dreamux
-config and global Codex auth survive.
+`~/.dreamux/run/` and `~/.dreamux/cache/` are rebuildable while no server is
+running. Durable `~/.dreamux/state/` is not a generic cleanup target; preserve
+it unless an exact state owner and documented recovery contract say otherwise.
 
 ## Configure dispatchers
 
@@ -149,7 +151,8 @@ Dispatcher declarations live in `config.json`:
         "extra_env": {
           "EXAMPLE_FLAG": "1"
         },
-        "initialize_timeout_ms": 10000
+        "initialize_timeout_ms": 10000,
+        "turn_timeout_ms": 600000
       }
     }
   ],
@@ -193,6 +196,8 @@ defaults, so any field can be omitted:
 - `extra_args` → `[]`
 - `extra_env` → `{}`
 - `initialize_timeout_ms` → `10000`
+- `turn_timeout_ms` → `600000` (accepted and defaulted by the current config
+  reader, but not passed into `CodexRuntime`; it currently has no runtime effect)
 
 Most operators never touch `bin` or `initialize_timeout_ms`. The optional
 `CODEX_HOST_CODEX_BIN` environment variable is a host-level override of the
@@ -247,39 +252,65 @@ by core; sharing one bot identity across dispatchers is an operator choice.
 Dispatcher ids use a path-safe character set so they map one-to-one to state
 directories.
 
-Access-gate allowlists are not part of `config.json`. Configure them in
-`~/.dreamux/state/<id>/access.json`:
+Access-gate allowlists are not part of `config.json`. The complete secure V3
+default used to initialize a missing `~/.dreamux/state/<id>/access.json` is:
 
 ```json
 {
-  "version": 2,
-  "allow_users": ["<USER_ID>"],
+  "version": 3,
+  "dm_policy": "pairing",
   "group": {
     "policy": "follow-user",
-    "allow_chats": ["<CHAT_ID>"],
+    "allow_chats": [],
     "require_mention": true
   },
+  "allow_users": [],
+  "pending": {},
   "observed_chats": [],
   "warnings": [],
-  "last_gate": null
+  "last_gate": {
+    "at": 0
+  }
 }
 ```
 
-`access.json` is v2-only. `allow_users` is the single global allowlist of
-sender open_ids, shared by direct messages and the group `follow-user` policy.
-`group.policy` is one of `block`, `allowlist`, or `follow-user`; under
-`allowlist` the gate consults `allow_chats`, under `follow-user` it ignores
-`allow_chats` and gates on `allow_users`. dreamux 0.x does not migrate older
-shapes: an unsupported or missing `version` fails loud at startup. To reset,
-delete the file (secure default: no one authorized) and recreate it in this v2
-shape.
-
-The server reads `access.json` directly at runtime and preserves runtime
-observations and warnings in the same file.
+`access.json` remains version 3. `version` is Channel/schema-owned.
+`dm_policy`, `group.policy`, `group.allow_chats`, and
+`group.require_mention` are operator policy. `allow_users` is shared authority:
+live pairing/Owner approval may append it, and a quiesced operator may maintain
+it. `pending`, `observed_chats`, `warnings`, and `last_gate` are Channel-owned
+runtime ledger fields. Add real chat or sender ids only through the quiesced
+field-specific maintenance workflow below; the secure default grants neither
+chat nor sender authority.
+
+For human group messages, `group.require_mention` runs first and `block` drops
+all human traffic. Under `allowlist`, an unlisted chat drops and a listed chat
+trusts every exactly classified human. Under `follow-user`, a listed chat has
+the same trust; an unlisted chat follows the existing `dm_policy` /
+`allow_users` / pairing path. Trusted chats bypass `dm_policy`, `allow_users`,
+and pairing, including `dm_policy: "disabled"`, but never bypass the global
+mention switch. `/introduce` stays sender-scoped and still requires
+`allow_users`.
+
+This meaning changes in place when the new server starts; V3 needs no rebuild.
+Before deploying, review every non-empty `allow_chats` entry under both
+`allowlist` and `follow-user`. Keep only groups whose human membership should
+be trusted and whose passive known-bot observation should remain enabled.
+
+The access path is always `~/.dreamux/state/<id>/access.json`;
+`DREAMUX_CONFIG_DIR` and `dreamux config path` affect `config.json` only. For a
+manual access edit, fully stop the owning Dispatcher, confirm it stopped,
+re-read after stop, apply only the requested policy/shared-authority fields via
+an owner-only sibling temporary file and atomic replacement at mode `0600`,
+validate the complete current V3 shape without printing values, and then start
+the Dispatcher. Preserve `version` and all Channel-owned ledger fields exactly.
+A missing file after confirmed stop is valid current state: start from the full
+secure V3 default shown above, create a missing state directory at `0700`, and
+atomically create the first `0600` file. This is initialization, not a rebuild.
 
 `dreamux config show`, `dreamux status`, `dreamux doctor`, and logs redact
 secret-like config keys generically. There is no CLI raw mode for printing the
-unredacted local file.
+unredacted local file. `dreamux doctor` is not an access-state validator.
 
 ## Codex configuration precedence
 

package/dist/cli/changelog.js

@@ -4,10 +4,9 @@
  *
  * Per issue #98, the 0.x upgrade policy is fail-loud + rebuild rather than
  * accumulating automatic migrations. This command is the upgrade-time
- * information entry point: after installing a new package, an operator (or an
- * LLM following the `dreamux-maintenance` skill) reads the changelog
- * shipped inside that new package, handles any breaking changes / rebuilds, and
- * only then runs `dreamux daemon restart` / `onboard`.
+ * information entry point: after installing a new package, an operator reads
+ * the changelog shipped inside that new package, handles any breaking changes /
+ * rebuilds, and only then runs `dreamux daemon restart` / `onboard`.
  *
  * It reads the rush-generated `CHANGELOG.md` / `CHANGELOG.json` bundled in the
  * package. It never fetches over the network and never inspects a target

package/dist/cli/changelog.js.map

@@ -1 +1 @@
-{"version":3,"file":"changelog.js","sourceRoot":"","sources":["../../src/cli/changelog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAE5C,OAAO,EACL,yBAAyB,EACzB,6BAA6B,GAC9B,MAAM,sBAAsB,CAAC;AAM9B;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,UAAgC,EAAE;IAElC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI;QACvB,CAAC,CAAC,yBAAyB,EAAE;QAC7B,CAAC,CAAC,6BAA6B,EAAE,CAAC;IACpC,IAAI,CAAC;QACH,OAAO,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACtC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAK,GAA6B,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YACrD,MAAM,IAAI,KAAK,CACb,qCAAqC,IAAI,2CAA2C;gBAClF,qGAAqG,CACxG,CAAC;QACJ,CAAC;QACD,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC"}
+{"version":3,"file":"changelog.js","sourceRoot":"","sources":["../../src/cli/changelog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAE5C,OAAO,EACL,yBAAyB,EACzB,6BAA6B,GAC9B,MAAM,sBAAsB,CAAC;AAM9B;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,UAAgC,EAAE;IAElC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI;QACvB,CAAC,CAAC,yBAAyB,EAAE;QAC7B,CAAC,CAAC,6BAA6B,EAAE,CAAC;IACpC,IAAI,CAAC;QACH,OAAO,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACtC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAK,GAA6B,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YACrD,MAAM,IAAI,KAAK,CACb,qCAAqC,IAAI,2CAA2C;gBAClF,qGAAqG,CACxG,CAAC;QACJ,CAAC;QACD,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@excitedjs/dreamux",
-  "version": "0.22.0-beta.150",
+  "version": "0.22.0-beta.151",
   "description": "Dreamux core host for multi-dispatcher agent orchestration through provider interfaces.",
   "license": "MIT",
   "repository": {
@@ -26,11 +26,11 @@
     "CHANGELOG.json"
   ],
   "dependencies": {
-    "@excitedjs/agent-runtime-claude-code": "0.5.0-beta.150",
-    "@excitedjs/agent-runtime-codex": "0.3.5-beta.150",
-    "@excitedjs/dreamux-types": "0.8.0-beta.150",
-    "@excitedjs/dreamux-utils": "0.4.0-beta.150",
-    "@excitedjs/feishu-channel": "4.1.2-beta.150",
+    "@excitedjs/agent-runtime-claude-code": "0.5.0-beta.151",
+    "@excitedjs/agent-runtime-codex": "0.3.5-beta.151",
+    "@excitedjs/dreamux-types": "0.8.0-beta.151",
+    "@excitedjs/dreamux-utils": "0.4.0-beta.151",
+    "@excitedjs/feishu-channel": "5.0.0-beta.151",
     "croner": "^10.0.1",
     "smol-toml": "^1.6.1",
     "yargs": "^17.7.2",

package/skills/dispatcher/dreamux-maintenance/SKILL.md

@@ -1,59 +1,70 @@
 ---
 name: dreamux-maintenance
-description: "Dreamux host operation notes. Load when diagnosing or operating dreamux serve, daemon startup, doctor/status results, dispatcher health, missing replies, stuck turns, restart behavior, config/state/run/log paths, bundled-skill injection, access state, or runtime app-server readiness."
+description: "Dreamux host operation notes. Load when diagnosing or operating dreamux serve, daemon startup, doctor/status results, Dispatcher health, missing replies, stuck turns, restart behavior, current config/state/run/log paths, bundled-skill injection, Feishu access policy, runtime app-server readiness, a Dreamux upgrade, or post-restart recovery."
 ---
 
 # Dreamux Maintenance
 
-## Scope Boundaries
-
-- Prefer Dreamux-owned surfaces first: `dreamux doctor`, `dreamux status`,
-  dispatcher status, config inspection, admin socket behavior, and logs under
-  `~/.dreamux/logs/`.
-- Separate submit, execution, completion delivery, and visible channel delivery.
-  A submitted TeamMate turn or inbound channel message is not proof that the
-  final reply reached the operator.
-- Before changing persistent state, access policy, service units, shell startup
-  files, PATH, environment variables, runtime auth, or Dreamux config, name the
-  target and require explicit operator intent when the request is ambiguous.
-- Keep private paths, socket paths, app ids, tokens, secrets, and local incident
-  details out of broad channel replies and public artifacts.
-
-## Server And Service Notes
-
-- `dreamux serve` is the foreground server entry point. The public
-  `dreamux daemon install|uninstall|start|stop|restart` command group manages
-  the user-level service; do not invent additional daemon command shapes or
-  treat `serve` as self-daemonizing.
-- Check the service manager only for service lifecycle questions. Treat launchd
-  or systemd changes as infrastructure changes and explain before modifying
-  units, linger, environment, or shell configuration.
-- Prefer fail-loud diagnosis over silent repair. If config, state, cache, run, or
-  log paths need deletion or rebuild, name the exact path class and why it is
-  safe or unsafe.
-- `dreamux changelog` reads the installed package's offline release notes. Use it
-  before restart or onboard when an upgrade may require manual rebuild steps.
-- Logs are diagnostics, not durable state. Preserve them unless the operator asks
-  for cleanup or the retention reason is clear.
-
-## Runtime And Delivery Notes
-
-- For missing replies, distinguish channel ingress, dispatcher acceptance,
-  runtime turn execution, TeamMate completion delivery, and channel egress.
-- For stuck turns, inspect the relevant runtime and Dreamux state before
-  restarting. Restarting the server is not proof that a model turn completed or
-  that a channel reply was sent.
-- Codex and Claude Code auth/config remain owned by their runtimes. Do not edit
-  global runtime auth or config unless the operator explicitly asks for that
-  operational action.
-- Bundled skills are injected at runtime by role. When skill loading is suspect,
-  inspect the runtime skill source configuration and logs rather than copying
-  bundled skill files into a dispatcher workspace.
-
-## Reporting Notes
-
-- Report the exact interface checked, the target dispatcher/team/teammate or
-  service, the error summary, what was verified, and whether retrying is safe.
-- When reporting to a channel, keep details useful but sanitized. Mention command
-  names, package versions, high-level path classes, and behavioral status rather
-  than raw private identifiers.
+## Scope And Authorization
+
+- Use Dreamux-owned surfaces first: `dreamux doctor`, `dreamux status`,
+  Dispatcher status, admin socket behavior, and logs under `~/.dreamux/logs/`.
+- Separate submit, execution, completion delivery, and visible Channel delivery.
+  A submitted turn or inbound message does not prove that a final reply reached
+  the operator.
+- Before changing config, state, a service unit, PATH, environment, runtime
+  auth, or the installed package, require explicit operator intent naming the
+  target Dispatcher and exact operation. Load the routed owner before planning
+  a file or field change.
+- Run the self-upgrade procedure only for explicit upgrade intent. Its
+  self-resuming branch has additional preconditions and private recovery
+  ownership; ordinary restart permission is not upgrade permission.
+
+## Secret Safety
+
+- Never print or relay an unredacted config, `app_secret`, `extra_env`, token,
+  captured service environment, private recovery path, or complete provider
+  config to a broad Channel.
+- Report sanitized field names and outcomes. Keep private paths, ids,
+  credentials, environment values, and incident details on an operator-private
+  surface.
+- Never guess a Dispatcher id, config path, state path, provider schema, or
+  managed-service identity.
+
+## Common Diagnostic Sequence
+
+1. Confirm the target Dispatcher, the operator's requested outcome, and the
+   available reply surface.
+2. Identify the failing boundary: Channel ingress, Dispatcher acceptance,
+   runtime execution, TeamMate completion delivery, visible Channel egress, or
+   host/service lifecycle.
+3. Read the single routed reference whose `Read when` condition matches. Load
+   more than one only when the task genuinely crosses those owners.
+4. Inspect Dreamux-owned status, doctor output, admin behavior, and narrowly
+   relevant logs without exposing secrets. Treat logs as diagnostics, not
+   durable state.
+5. Before mutation, restate the exact authority, owner, recovery path, and
+   verification step. Stop when any required identity or private recovery
+   condition is unproven.
+
+## Task Routing
+
+| Task | Read when | Reference |
+|---|---|---|
+| Service lifecycle and reply diagnosis | Diagnosing `dreamux serve`, daemon startup, doctor/status results, Dispatcher health, missing replies, stuck turns, restart behavior, current state/run/log paths, bundled-skill injection, or runtime app-server readiness. | [Service lifecycle](references/service-lifecycle.md) |
+| Managed Dreamux self-upgrade | The operator explicitly requests a Dreamux upgrade, or an injected restart notice requires post-restart recovery and verification. | [Self-upgrade](references/self-upgrade.md) |
+| Host config envelope | Inspecting or safely editing the current `config.json` envelope, path authority, Dispatcher/agent/channel wiring, or an opaque external provider config. | [Config envelope](references/config-envelope.md) |
+| Built-in Codex config | Inspecting or changing the current `builtin:codex` Agent Runtime provider config. | [Built-in Codex](references/builtin-codex.md) |
+| Built-in Claude Code config | Inspecting or changing the current `builtin:claude-code` Agent Runtime provider config. | [Built-in Claude Code](references/builtin-claude-code.md) |
+| Built-in Feishu credentials | Inspecting or changing the current `builtin:feishu` Channel credential config. | [Built-in Feishu](references/builtin-feishu.md) |
+| Feishu access V3 | Diagnosing Feishu access policy or safely editing current V3 `access.json`, including trusted chats and `/introduce`. | [Feishu access V3](references/feishu-access-v3.md) |
+
+## Reporting
+
+- Report the exact interface, target Dispatcher/service, sanitized error,
+  verified state, changes made, and whether retrying is safe.
+- Use the provider reply tool when visible Channel delivery is required.
+  Assistant text alone is not Channel delivery.
+- Preserve logs unless the operator explicitly requests bounded cleanup.
+- For an upgrade, follow the outcome-specific original-Channel and recovery
+  reporting contract in the self-upgrade reference.

package/skills/dispatcher/dreamux-maintenance/references/builtin-claude-code.md

@@ -0,0 +1,17 @@
+# Current `builtin:claude-code` Config
+
+Accepted `agents[].config` fields, defaults, and meanings:
+
+- `bin`: non-empty string, default `"claude"`.
+- `model`: string or null, default `null`; null defers to Claude Code, otherwise
+  maps to its model option.
+- `permission_mode`: `default | acceptEdits | plan | bypassPermissions` or
+  null, default `null`; null defers to Claude Code, otherwise maps to its
+  permission-mode option.
+- `remote_control`: boolean, default `false`; enables Claude Code's external
+  resident-session control surface.
+- `extra_args`: string array, default `[]`; passed to the child process.
+- `extra_env`: string-to-string map, default `{}`; merged into the child
+  environment.
+- `turn_timeout_ms`: positive integer milliseconds, default `600000`; an
+  inactivity window reset by stream activity, not a total-duration cap.

package/skills/dispatcher/dreamux-maintenance/references/builtin-codex.md

@@ -0,0 +1,18 @@
+# Current `builtin:codex` Config
+
+Accepted `agents[].config` fields, defaults, and meanings:
+
+- `bin`: non-empty string, default `"codex"`; `CODEX_HOST_CODEX_BIN` is the
+  higher-priority host binary override.
+- `approval_policy`: `never | auto | auto-approve | on-failure`, default
+  `never`; configures the Codex launch.
+- `sandbox_mode`: `read-only | workspace-write | danger-full-access`, default
+  `workspace-write`; configures the Codex launch.
+- `extra_args`: string array, default `[]`; passed to the child process.
+- `extra_env`: string-to-string map, default `{}`; merged into the child
+  environment.
+- `initialize_timeout_ms`: positive integer milliseconds, default `10000`;
+  bounds the runtime initialize handshake.
+- `turn_timeout_ms`: positive integer milliseconds, default `600000`; the
+  current reader accepts and defaults it, but it is not passed into
+  `CodexRuntime` and currently has no runtime effect.

package/skills/dispatcher/dreamux-maintenance/references/builtin-feishu.md

@@ -0,0 +1,8 @@
+# Current `builtin:feishu` Channel Config
+
+Accepted `dispatchers[].channels[].config` fields:
+
+- `app_id`: required non-empty string identifying this Channel config;
+- `app_secret`: required non-empty string authenticating the Feishu app.
+
+There are no credential defaults and no other built-in Feishu config fields.

package/skills/dispatcher/dreamux-maintenance/references/config-envelope.md

@@ -0,0 +1,59 @@
+# Current `config.json` Envelope
+
+This reference owns the current host envelope, config path authority, provider
+opacity, and safe structural editing workflow.
+
+Use `dreamux config path` as the config path authority.
+`DREAMUX_CONFIG_DIR` may relocate `config.json`. Do not use `dreamux config
+show` to inspect provider config; it is not a field-targeted secret-safe view.
+
+The complete current host envelope has independently optional `agents` and
+`dispatchers` arrays. An omitted array normalizes to an empty collection.
+
+`agents[]` entries contain:
+
+- unique non-empty string `id`;
+- non-empty provider ref `provider`;
+- optional provider-owned object `config`.
+
+`dispatchers[]` entries contain:
+
+- unique path-safe non-empty string `id`;
+- schema-optional or null `cwd`; every enabled Dispatcher must nevertheless
+  have an explicit non-empty usable `cwd` before server startup;
+- optional boolean `enabled`, default `true`;
+- optional `workspace.enabled`, default `true`;
+- required non-empty `channels[]`;
+- required non-empty `agentRuntime` matching an `agents[].id`.
+
+Each `channels[]` entry contains a unique-per-Dispatcher non-empty `id`, a
+non-empty Channel provider ref, optional provider-owned `config`, and optional
+`collaborationSpace.defaultBinding`. One provider ref may appear only once in
+one Dispatcher. `defaultBinding` accepts:
+
+- optional boolean `enabled`, default `false`;
+- optional or null `repo`; when present, `repo.cwd` is required and non-empty,
+  while `repo.baseRef` may be omitted, null, or any string, including empty or
+  whitespace;
+- optional or null `identity`; a string value must be non-empty.
+
+External `npm:` provider configs are opaque. Use the provider's schema as the
+authority; do not infer fields from a built-in provider.
+
+## Safe Current Config Editing
+
+1. Confirm explicit operator intent for the target Dispatcher, config file, and
+   exact fields.
+2. Resolve the file with `dreamux config path` without printing its contents.
+3. Load the separate provider reference for each affected built-in provider;
+   for an external provider, use that provider's own schema.
+4. Apply an exact structural transform that changes only the requested fields.
+   Preserve unrelated Dispatchers, channels, agents, and provider fields. Write
+   a complete sibling temporary file at mode `0600`, then atomically replace
+   the target without echoing untouched values.
+5. When an `agents[]` entry is shared and the request applies only to the
+   current Dispatcher, clone it under a new unique id and repoint only that
+   Dispatcher's `agentRuntime`.
+6. Run `dreamux doctor`, report sanitized validation results, and load the
+   service-lifecycle route before restarting for the config change to take
+   effect.

package/skills/dispatcher/dreamux-maintenance/references/feishu-access-v3.md

@@ -0,0 +1,89 @@
+# Current Built-In Feishu Access V3
+
+This reference owns the current V3 shape, field ownership, trusted-chat and
+`/introduce` meanings, and quiesced edit/`ENOENT` workflow.
+
+The path is fixed at `~/.dreamux/state/<dispatcher-id>/access.json`.
+`DREAMUX_CONFIG_DIR` affects `config.json` only. Never derive this state path
+from `dreamux config path` or a relocated config directory.
+
+The complete secure default is:
+
+```json
+{
+  "version": 3,
+  "dm_policy": "pairing",
+  "group": {
+    "policy": "follow-user",
+    "allow_chats": [],
+    "require_mention": true
+  },
+  "allow_users": [],
+  "pending": {},
+  "observed_chats": [],
+  "warnings": [],
+  "last_gate": {
+    "at": 0
+  }
+}
+```
+
+Current field ownership has four classes:
+
+- Channel/schema-owned: `version`.
+- Operator policy: `dm_policy`, `group.policy`, `group.allow_chats`, and
+  `group.require_mention`.
+- Shared authority: `allow_users`; live pairing/App Owner approval may append
+  it, while an independent quiesced operator may also maintain it.
+- Channel runtime ledger: `pending`, `observed_chats`, `warnings`, and
+  `last_gate`; do not edit these directly.
+
+Current meanings and types:
+
+- `version` is exactly `3`.
+- `dm_policy` is `all | allowlist | pairing | disabled`.
+- `group.policy` is `block | allowlist | follow-user`;
+  `group.allow_chats` is a string array; `group.require_mention` is boolean.
+- `allow_users` and `observed_chats` are string arrays.
+- `pending` is keyed by pairing token. Each entry has `kind` (`dm | group`),
+  string `sender_id` and `chat_id`, numeric `created_at` and `expires_at`,
+  numeric `replies`, and optional string `prompt_message_id`.
+- `warnings` is an array of `{ at, msg, ctx? }`; `last_gate` is an object with
+  numeric `at` and optional string `sender_id`, `chat_id`, `action`, `reason`.
+
+For exactly classified human group messages, `group.require_mention` runs
+first, and `group.policy: block` drops all human messages. A chat in
+`group.allow_chats` is trusted under either `allowlist` or `follow-user`: after
+the mention/block checks, its human members deliver without consulting
+`dm_policy`, `allow_users`, or pairing. An unlisted `allowlist` chat drops. An
+unlisted `follow-user` chat uses the existing `dm_policy` / `allow_users` /
+pairing path. Passive known-bot observation remains scoped to
+`group.allow_chats`. `/introduce` remains sender-scoped and requires exact
+sender ID membership in `allow_users`; this check is not human-only, so a
+manually listed bot/app sender ID may pass authorization.
+
+## Safe Current Access Editing
+
+A target Dispatcher only prepares and reports the requested policy or
+shared-authority patch. It must not stop and then continue to apply its own
+patch. Hand the operation to an independent operator for the full ownership
+window:
+
+```text
+dispatcher stop -> confirmed stop -> post-stop re-read -> exact atomic patch
+-> current-shape validation -> dispatcher start
+```
+
+Keep the Channel owner fully quiesced for the entire read-modify-write window.
+After the post-stop re-read, change only requested operator-policy or
+`allow_users` fields. Preserve `version` and every Channel runtime-ledger field
+exactly. Use an owner-only sibling temporary file, atomic replacement, and final
+mode `0600`. Validate JSON plus the complete V3 shape locally without printing
+values. Do not claim that `dreamux doctor` validates access state.
+
+If the file is absent after confirmed stop, treat that explicit `ENOENT` as
+valid current state. Use the complete secure V3 default above as the in-memory
+baseline and apply only requested policy/shared-authority fields. Create a
+missing state directory at mode `0700`, then atomically create the first
+`access.json` through a sibling mode-`0600` temporary file. Start the Dispatcher
+only after validation.

package/skills/dispatcher/dreamux-maintenance/references/self-upgrade.md

@@ -0,0 +1,363 @@
+# Managed-Daemon Self-Upgrade
+
+This is the sole transition guide in this skill. Run it only after explicit
+operator intent to upgrade a managed Dreamux daemon. It reads release-specific
+actions from the validated staged target; it does not carry historical schemas
+or migration recipes.
+
+## Contents
+
+- [Preflight](#preflight)
+- [Staged inspection and classification](#staged-inspection-and-classification)
+- [Execution before restart](#execution-before-restart)
+- [Post-restart verification and reporting](#post-restart-verification-and-reporting)
+- [Recovery and artifact disposition](#recovery-and-artifact-disposition)
+
+A Dispatcher may take the self-resuming path only when every preflight is
+proven. Otherwise prepare a sanitized plan and hand the operation to an
+independent operator/controller.
+
+## Preflight
+
+### 1. Prove identity and the return Channel
+
+Require the operator to identify or confirm the current Dispatcher id. Require
+an originating Channel message and an available provider reply tool so phase
+two can report to the same Channel. If either fact is unavailable, stop and
+request it. Never guess an id from process state or workspace paths.
+
+### 2. Discover, then re-read under managed authority
+
+Use an initial `dreamux doctor --json` only to discover the managed service.
+Treat `service.execStart[0]` as its launcher authority. Require
+`service.installed`, `enabled`, `loaded`, and `running` to be true, with a
+non-null service PID and captured service environment. Draw no
+caller-environment config or provider conclusion from this discovery result.
+
+Run the exact launcher `doctor --json` again under the captured service
+environment. Require this second result's `configFile` to be the config under
+the captured `DREAMUX_CONFIG_DIR`. Only this result is authoritative for the
+Dispatcher, providers, config, and later doctor calls.
+
+### 3. Prove the resumable managed instance
+
+Under the same managed environment, run the exact launcher `status`. Require a
+matching enabled/running Dispatcher row with a non-empty `thread_id`. Require
+the authoritative doctor result to name its Agent Runtime provider as
+`builtin:codex` or `builtin:claude-code`, whose owner contracts guarantee resume
+support; a non-empty thread alone is not proof for an external provider.
+
+Record the server `pid` and `uptimeSec`. Do not demand equality between the
+service PID and status PID: the service PID is the public CLI parent while
+`server.status` reports its server child. Resolve the status PID's parent with
+the platform process table and require it to equal `doctor.service.pid`.
+Otherwise fail closed because status and service have not been proven to
+describe the same managed instance.
+
+### 4. Prove package, launcher, and prefix identity
+
+Resolve `service.execStart[0]` and `command -v dreamux` to real paths. Compare
+the launcher with the package location under the current `npm root -g` and its
+`npm prefix -g`. Reject an npm-linked package root or any prefix/launcher
+mismatch.
+
+Read the matched package root's `package.json.version`, then run both
+`dreamux --version` and the exact service launcher with `--version`. Require all
+three values to be the same valid semver and record it as the old version. The
+matched package manifest is authoritative, so an npm-linked checkout reporting
+`0.0.0` cannot pass.
+
+### 5. Resolve an exact forward target before mutation
+
+Resolve the npm selector to an exact version before changing disk state:
+
+- when the operator names a version or dist-tag, resolve only
+  `@excitedjs/dreamux@<requested>`;
+- when omitted, use `@excitedjs/dreamux@latest`, the latest stable release
+  rather than `beta` or `alpha`.
+
+Use `npm view @excitedjs/dreamux@<requested-or-latest> version --json` to
+resolve the exact target semver. This step never installs a package. Equal is a
+no-op. A lower target is a downgrade and is always rejected by this SOP. A
+downgrade requires a separate independently reviewed recovery plan; explicit
+version selection does not opt into the forward-only algorithm.
+
+### 6. Stage and validate exact old and target artifacts
+
+Before overwriting the live service prefix, create a private temporary staging
+directory and capture the npm executable, global prefix, and an explicit
+isolated cache path. In the commands below, `npm` is that captured executable.
+Run these two operand-complete commands:
+
+```text
+npm pack @excitedjs/dreamux@<oldVersion> --ignore-scripts --json --pack-destination <private-dir>/artifacts
+npm pack @excitedjs/dreamux@<targetVersion> --ignore-scripts --json --pack-destination <private-dir>/artifacts
+```
+
+Validate each tarball's package name, manifest version, integrity output,
+changelog files, and bundled skill tree without executing target code. A
+top-level tarball alone is not rollback proof. Do not install either package or
+dependency closure until the staged target guidance is read and classified.
+
+## Staged Inspection And Classification
+
+### 7. Read the staged target and select the full version range
+
+Extract the validated target tarball in staging. Read its `CHANGELOG.json`, its
+bundled `dreamux-maintenance/SKILL.md`, and the target owner references named by
+that root. The target version's current-only references are authoritative for
+its schema, defaults, meaning, and ownership. Use the running old version's
+references only to understand and preserve the old values.
+
+The changelog is complete and newest-first. Select `(oldVersion,
+targetVersion]` and order entries by semver from oldest to newest. Do not
+inspect only the newest entry or execute storage order. The `--json` flag used
+later changes only the output format and is not a range selector; range
+selection belongs to the reader.
+
+### 8. Classify live-safe and independent-quiesced work
+
+Classify all applicable `BREAKING:`, `Review:`, and `Rebuild:` instructions
+before touching the live prefix, config, or state.
+
+- A live-safe operator-config action may stay in this self-resuming path only
+  when the staged changelog and target owner references prove that the target
+  can start safely with the untouched old config and with every planned
+  intermediate config state.
+- Any action that stops or quiesces the daemon or Dispatcher, modifies
+  server-owned or mixed-ownership state, re-registers the service, changes the
+  active recovery Channel/Dispatcher identity, or otherwise removes the
+  current execution path cannot be performed by the current Dispatcher.
+
+For the second branch, leave the live prefix untouched and hand an independent
+operator/controller this exact order:
+
+1. verified stage and inspection;
+2. rehearse both dependency closures exactly as specified in step 9;
+3. confirmed stop;
+4. post-stop re-read and owner-only backup;
+5. install the staged exact target with the rehearsed offline closure;
+6. apply actions oldest-to-newest using the staged target owner references;
+7. run the target doctor in the captured service environment;
+8. start and verify.
+
+On any post-stop failure, restore the backups, reinstall the staged old
+artifact with the rehearsed offline closure, run the old exact-launcher doctor,
+and restart the old service only when rollback is proven. Otherwise keep the
+service stopped and report the independent recovery blocker. Do not enter the
+self-resuming phase.
+
+### 9. Rehearse both complete dependency closures
+
+Before either path touches the live prefix, populate and prove the full old and
+target dependency closures without executing lifecycle scripts. Use the
+captured npm executable and the same explicit isolated cache for all four
+operand-complete commands, with four distinct private prefixes:
+
+```text
+<npm-bin> install --global --ignore-scripts --cache <cache> --prefix <private-old-online> <staged-old-tarball>
+<npm-bin> install --global --ignore-scripts --cache <cache> --prefix <private-target-online> <staged-target-tarball>
+<npm-bin> install --global --offline --ignore-scripts --cache <cache> --prefix <private-old-offline> <staged-old-tarball>
+<npm-bin> install --global --offline --ignore-scripts --cache <cache> --prefix <private-target-offline> <staged-target-tarball>
+```
+
+Validate both fresh offline prefixes' manifests, launchers, changelogs, and
+bundled skills. These exact tarballs, the isolated cache, and the rehearsed
+command shape form the target and rollback closure. Failure stops the SOP
+before live-prefix mutation.
+
+### 10. Route target-owned preparation and transfer recovery ownership
+
+For every live-safe config action, use the staged target root routing table to
+resolve the reference whose task/read condition owns config editing and each
+affected provider. Do not hard-code the current reference filenames into this
+generic SOP: a future target may rename or split them while keeping its route
+authoritative. This upgrade reference owns ordering and transaction boundaries,
+not schema or edit facts.
+
+This step is preparation only. Resolve authoritative paths, plan each
+transformation oldest-to-newest, and create owner-only backups using the target
+owner's exact structural and atomic-write contract. Do not mutate config or
+state yet. Follow the staged changelog rather than embedding historical schemas
+in this skill.
+
+The current exact restart-marker path is
+`<captured-managed-HOME>/.dreamux/run/restart-intent.json`, where
+`<captured-managed-HOME>` is the managed `HOME` captured in step 2. Every
+transfer, exact stat/read, removal, and `ENOENT` absence proof in this SOP uses
+this one resolved path.
+
+Before the first live-prefix or config mutation, transfer an exact inventory of
+the staging directory, isolated cache, rehearsal prefixes, backups, launchers,
+captured environment, that exact restart-marker path, and rollback commands to
+an independently executing operator/controller. Use an operator-private path.
+Require acknowledgement. Do not expose private paths or secrets to a broad
+originating Channel. That independent controller owns the recovery material if
+the current Dispatcher disappears.
+
+If no such private handoff and acknowledgement can be established, execute the
+first step 17 outcome: remove only this run's exact scoped artifacts and
+backups, refuse the self-resuming upgrade, and stop. If an independent operator
+is reachable only through a non-private route, provide a sanitized
+independent-quiesced plan from step 8, require that operator to stage fresh
+recovery materials, and clean rather than retain or expose this run's private
+inventory.
+
+## Execution Before Restart
+
+### 11. Install the rehearsed target without scripts
+
+Install the validated target tarball with the exact captured npm executable and
+the rehearsed isolated cache:
+
+```text
+<npm-bin> install --global --offline --ignore-scripts --cache <cache> --prefix <captured-prefix> <staged-target-tarball>
+```
+
+Re-resolve both launcher paths, validate the matched manifest, and require the
+exact launcher and PATH command to report the target version. Re-run the
+installed `dreamux changelog --json` and require it to match the staged target
+changelog before mutating config.
+
+This creates a short, contained skew window in which the old daemon remains in
+memory while the live prefix holds the target. If installation or any
+identity/changelog check fails, immediately run:
+
+```text
+<npm-bin> install --global --offline --ignore-scripts --cache <cache> --prefix <captured-prefix> <staged-old-tarball>
+```
+
+Validate the old manifest/launchers and exact-launcher doctor, and do not
+restart. The rehearsed old closure, no-config-mutation boundary, and
+doctor-before-restart rule must be proven before installation. If rollback
+cannot be proven, report through the original Channel and follow the final
+confirmed-stop handoff from step 12.
+
+An unexpected old-daemon exit during this skew window may reap the caller. The
+live-safe proof ensures the target can start on every intermediate config
+state, but the current Dispatcher then makes no success claim and an
+independent operator must finish verification. This residual process-exit risk
+cannot be removed without choosing the independent stopped path.
+
+### 12. Apply live-safe actions exactly once
+
+Apply the classified live-safe actions exactly once, oldest-to-newest, using
+the staged target owner references. On ambiguity or failure, restore every
+mutation from backup, reinstall the staged old artifact with the rehearsed
+offline closure, validate its manifest/launchers and exact-launcher doctor, and
+leave the old daemon running.
+
+If complete rollback cannot be proven, report the failure through the original
+Channel and hand an independent operator the exact launcher, captured
+environment, staged artifacts/cache, backups, and observed failure. Only that
+independent operator may use the rehearsed old closure's exact launcher to
+issue `dreamux daemon stop`, observe its result, and confirm quiescence before
+recovery.
+
+After confirmed stop, the independent operator removes only the transferred
+exact marker path,
+`<captured-managed-HOME>/.dreamux/run/restart-intent.json`, and proves that same
+exact path is absent. Only explicit `ENOENT` counts as absence; any other
+stat/removal error remains unresolved. No old or target service may start until
+marker absence is proven; otherwise keep the service stopped. The current
+Dispatcher must not claim it can confirm the stop or cleanup that reaps it.
+
+### 13. Run target doctor before restart
+
+Run the target package's exact launcher `doctor --json` in the captured managed
+service environment. On failure, perform the same backup/package rollback and
+do not restart. If rollback cannot be proven, report through the original
+Channel and follow the final confirmed-stop handoff from step 12.
+
+### 14. Trigger the exact restart-resume capability
+
+Trigger the exact target service launcher under the captured managed-service
+environment with:
+
+```text
+<exact-target-service-launcher> daemon restart --notify-resumed --dispatcher <current-id>
+```
+
+Reconstruct the invocation so captured managed `HOME`, `PATH`,
+`DREAMUX_CONFIG_DIR`, and `DREAMUX_NODE_BIN` values override any caller or
+provider `extra_env` values. This keeps the restart marker, launcher, config,
+and service-control target in the same authority domain.
+
+The command writes a one-shot marker before restarting. The new server consumes
+it once and injects the default `Restart completed.` notice into the named
+resumed Dispatcher. The caller may be reaped during restart, so it must not
+depend on seeing the command return successfully or continue post-checks in the
+pre-restart turn.
+
+If the restart CLI fails synchronously while the caller survives, whether
+during marker creation or later service control, enter one failure path. Only a
+service-control failure after marker creation causes the CLI to attempt
+best-effort removal; marker creation itself may fail before that cleanup path
+and can leave partial state. In either case, verify with an exact stat/read. Only
+explicit `ENOENT` proves absence. That verification must use the same
+`<captured-managed-HOME>/.dreamux/run/restart-intent.json` path; permission,
+I/O, or any other result remains unresolved.
+
+Only after `ENOENT` may the failure be treated as rollback-capable. If absence
+is proven, immediately restore config backups, reinstall and verify the staged
+old artifact, dispose of scoped artifacts under the verified-rollback outcome,
+and report failure through the original Channel. If marker absence or rollback
+cannot be proven, classify the operation as unresolved recovery, retain the
+scoped materials with the pre-acknowledged independent owner, and follow the
+final confirmed-stop handoff from step 12. Do not close it as verified rollback
+or clean the recovery material.
+
+## Post-Restart Verification And Reporting
+
+The injected `Restart completed.` notice, when an upgrade was in flight in the
+resumed conversation, is the explicit trigger to continue with steps 15-18.
+
+### 15. Re-prove installed target identity
+
+Re-run the exact service launcher plus PATH `dreamux` with `--version` and
+confirm both still resolve to the same target package and version.
+
+### 16. Re-prove service and Dispatcher identity
+
+Re-run the exact-launcher `doctor --json` under the captured managed
+environment. Require the new service to be installed, enabled, loaded, and
+running, then run exact-launcher `status`. Confirm the current Dispatcher is
+running, resolve the new status PID's parent, and require it to equal the new
+service PID. Report the new `pid` and `uptimeSec` and compare them with the
+pre-restart snapshot so a stale or unrelated server is not mistaken for
+success.
+
+### 17. Dispose of artifacts by outcome
+
+| Outcome | Required disposition |
+|---|---|
+| Failure or refusal before the first live mutation and before private handoff acknowledgement, including a partial step 10 backup or missing private recovery owner | Remove only this run's exact staging directory, isolated cache, rehearsal prefixes, and any backups already created, then stop. No unowned recovery material may remain. |
+| Planned independent-quiesced operation with an acknowledged private operator path | Retain the material and transfer its exact private inventory before stop. |
+| Verified success or fully verified rollback | Remove only the exact staging directory, isolated cache, rehearsal prefixes, and config backups created by this run. |
+| No notice or unresolved recovery | Retain the material with the independent owner who acknowledged it before step 11. |
+
+Never use a broad or unresolved cleanup path, and never delete unresolved
+recovery material.
+
+### 18. Report through the original Channel
+
+Reply through the same originating Channel surface. Report old and new
+versions, target selection (`requested` or `latest`), applicable changelog work
+and backup outcome in sanitized form, doctor result, new process status/uptime,
+and overall success or remaining blocker. Assistant text is not Channel
+delivery.
+
+## Recovery And Artifact Disposition
+
+- A verified rollback before restart performs the verified-rollback row of
+  step 17 immediately, then reports failure through the original Channel.
+- An unresolved recovery retains and transfers the exact scoped paths to the
+  pre-acknowledged independent owner. Never expose them through a broad Channel.
+- If the restart notice does not arrive, the stopped or reaped Dispatcher
+  cannot self-diagnose. The independent operator must run `dreamux status`,
+  inspect daemon logs, and contact the user.
+- Foreground `dreamux serve` is not silently treated as a managed daemon. It
+  needs an external stop/start and recovery path.
+- On any rollback that cannot be proven, use the final confirmed-stop handoff
+  in step 12. The independent operator owns stop confirmation, exact-marker
+  cleanup with `ENOENT`-only absence proof, and recovery restart authority.

package/skills/dispatcher/dreamux-maintenance/references/service-lifecycle.md

@@ -0,0 +1,48 @@
+# Service Lifecycle And Reply Diagnosis
+
+This reference owns current serve/daemon lifecycle, missing-reply and stuck-turn
+diagnosis, bundled-skill injection, runtime app-server readiness, and
+same-version restart cautions.
+
+## Server And Service
+
+- `dreamux serve` is the foreground server entry point. The public
+  `dreamux daemon install|uninstall|start|stop|restart` command group manages
+  the user service; `serve` is not self-daemonizing.
+- Check launchd or systemd only for service-lifecycle questions. Explain before
+  changing units, linger, environment, or shell startup.
+- Use `dreamux doctor` to inspect configuration, provider loading, service
+  state, and runtime app-server readiness. Use `dreamux status` for current
+  Dispatcher and process facts; neither command proves Channel delivery.
+- Current durable state is under `~/.dreamux/state/`, volatile runtime files are
+  under `~/.dreamux/run/`, and logs are under `~/.dreamux/logs/`. Use the path
+  authorities reported by Dreamux instead of guessing alternate roots.
+
+## Missing Replies And Stuck Turns
+
+- For missing replies, distinguish Channel ingress, Dispatcher acceptance,
+  runtime execution, TeamMate completion delivery, and Channel egress.
+- For stuck turns, inspect the relevant runtime and Dreamux state before a
+  restart. A restart does not prove that a turn completed or a reply was sent.
+- Treat a successful submit as acceptance only. Confirm completion and then the
+  provider-visible reply separately.
+
+## Bundled-Skill Injection
+
+Bundled skills are injected by role. Inspect the runtime skill-source config
+and logs instead of copying bundled skills into a workspace. A missing skill is
+an injection/source-readiness problem, not evidence that workspace installation
+is required.
+
+## Same-Version Restart Cautions
+
+- A managed service may use
+  `dreamux daemon restart --notify-resumed --dispatcher <current-id>`.
+  Foreground `dreamux serve` needs an operator-coordinated stop/start and an
+  external recovery path.
+- Warn before renaming or disabling the current Dispatcher, removing its
+  Channel, changing its Agent Runtime provider, or changing Channel
+  credentials. Each can break the active recovery path.
+- The caller may be reaped during a restart. Do not depend on the pre-restart
+  turn to observe success; continue only from the injected restart notice or an
+  independent operator's verification.