dsh-plugin-dev-kb 1.5.2 → 1.8.0

package/kb/site/en/reference/cookbook/adding-a-package.md

@@ -17,7 +17,7 @@ packages/<group>/<pkg>/
                    # ../../../vendor/cordis (+ ../../../vendor/schemastery if
                    # you use Config, + ../../<group>/<dep> for each dsh dep)
   src/index.ts     # service default export or plugin (name/inject/apply/Config)
-  locale/en.json   # optional display metadata: meta.title and meta.description
+  locale/en.json   # optional display metadata: meta.title, meta.description, and meta.detail
   locale/zh.json   # translations using the same fields
   README.md        # service API, events, extension points, design notes,
                    # + gated Model Experience context blocks or short form
@@ -139,7 +139,7 @@ Merge these entries into `package.json`, retaining existing runtime exports and
 }
 ```
 
-Keep language files together in `locale/`, with `en.json` as the discovery entry. Fields are optional; present values must be non-empty strings. Missing files or fields permit fallback, while malformed JSON or invalid fields produce a per-plugin diagnostic.
+Keep language files together in `locale/`, with `en.json` as the discovery entry. Fields are optional; present values must be non-empty strings. English `meta.title` and `meta.description` use sentence case: capitalize only the first word, proper nouns, and product names, as in `Git worktrees` ([rule](https://github.com/deepseek-ai/deepseek-harness/blob/master/.agents/skills/dsh-prose-standard/SKILL.md#required-coverage-by-prose-location)). At runtime, missing files or fields permit fallback, while malformed JSON or invalid fields produce a per-plugin diagnostic. First-party packages and plugin templates must provide `ja.json`, `es.json`, `fr.json`, `de.json`, `ru.json`, and `pt.json` covering every field present in `en.json` or optional `zh.json`, preserving placeholders, slash commands, and API field names; detail paths may point to the existing English document. Subpath resources under `locale/<subpath>/` follow the same checks. English descriptions explain user-visible behavior and end with sentence punctuation. Run `pnpm run check:i18n` to verify JSON metadata and UI dictionary completeness; the JSON checks also run in `check:all`, CI static checks, and hygiene.
 
 Fields fall back independently before view-specific name formatting, using the existing locale language chain first:
 
@@ -150,6 +150,8 @@ Export `<package name>/locale/en.json` for locale lookup; expose `<package name>
 
 For an image on bundle cards, details, and component rows, a package-root plugin sets top-level `"icon": "./icon.svg"` in its exported manifest, or exports `./icon` when that field is omitted. A subpath plugin exports its own icon, such as `"./search/icon": "./search.svg"`. Include each image in `files`. A manifest `icon` is relative to the manifest's directory; absolute paths, URLs, paths outside that directory, and symlinks resolving outside it are rejected. An exported icon resolves through Node exports like locale resources and must remain inside its package. SVG, PNG, JPEG (`.jpg`/`.jpeg`), and WebP files are supported up to 256 KiB. Images must be self-contained; SVG is rendered as an image, not inline HTML. The Host returns a data URL without activating the plugin. Invalid declarations or unreadable files produce a metadata diagnostic while retaining valid text, without trying the export; missing or undecodable images use the panel's default artwork.
 
+A bundle can also set `meta.detail` to a Markdown file path relative to the package root, such as `"docs/DETAIL.md"` in `locale/en.json` and `"docs/DETAIL.zh.md"` in `locale/zh.json`; it is read from these files at the package root. The path uses `/`, stays inside the package, ends in `.md` or `.markdown`, and has no package-field fallback; keep its images beside it, and list its top-level directory, such as `docs`, in `files` right after the locale resources, as `check-workspace-constraints` requires. The named file must exist in a subdirectory of the package; a root-level document is rejected because its neighboring images would not be published. A bundle's page in **Plugins**, and its index entry page when the [custom plugin indexes bundle](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/experimental/plugin-market-bundle/README.md) is on, show the file for the active UI language as the plugin's detail document. Without `meta.detail` they show the package README, and an index entry page then falls back to the declared repository's README; the [document order](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/util/plugin-detail/README.md#document-order) defines the rules. Write it for users, and reference images by paths relative to the file.
+
 Installed bundle cards and details, component lists and configuration details, and Settings' plugin inventory display this metadata, including disabled and preset plugins. Reads do not activate plugins.
 
 Only Settings shortens literal package-name and module-name fallbacks by removing npm scope and Cordis/DSH prefixes; Plugin Manager keeps complete names. Locale titles and descriptions remain unchanged. A row configuration page can use its registered summary when the plugin has no display description.

package/kb/site/en/reference/cookbook/extension-cookbook.md

@@ -106,7 +106,7 @@ Every product feature maps to a listener on a documented extension point — the
 
 | Product feature | Plugin mechanism |
 |---|---|
-| Hook system (user + project level) | listeners on `agent/created`, `agent/pre-step`, `agent/request`, `tools/pre-execute`, `tools/post-execute`, and `agent/turn-stopping`; the waterfalls return typed decisions, while `agent/turn-stopping` may steer another step; the `dsh-hooks-claude-code` / `dsh-hooks-codex` bridges map hook config files onto these extension points |
+| Hook system (user + project level) | listeners on `agent/created`, `agent/pre-step`, `tools/pre-execute`, `tools/post-execute`, and `agent/turn-stopping`; the waterfalls return typed decisions, while `agent/turn-stopping` may steer another step; the `dsh-hooks-claude-code` / `dsh-hooks-codex` bridges map hook config files onto these extension points |
 | `/goal` | `ctx.goals` owns durable state, `dsh-goal-round-driver` schedules same-session rounds through the public `Agent`, and separate command/tool producers expose human/model control |
 | `/loop` | on the `turn/end` session event, `followup()` the next iteration; or force-continue |
 | Dynamic workflow | `ctx.workflowEngine` + the PTC workflow engine + the `workflow` tool; structured in-process children enforce output with scoped prompt/tool registrations, a monotonic tool guard, final `tools/result` commit (including enclosing `run_code`), and the structured-output execution's monotonic `concludeTurn()` marker |

package/kb/site/en/reference/cordis-api/context.md

@@ -115,7 +115,7 @@ The root context of the application (every child context shares it). @experiment
 
 ```ts cordis-catalog
 /** Base URL used to resolve relative plugin/module specifiers, if the runtime sets one. */
-baseUrl?: string
+baseUrl?: string | undefined
 ```
 
 Base URL used to resolve relative plugin/module specifiers, if the runtime sets one.

package/kb/site/en/reference/cordis-api/events.md

@@ -31,7 +31,7 @@ Dispatch an event, running all listeners concurrently.
 
 **Returns** a promise resolving once every listener has settled.
 
-[Source](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/events.ts#L44)
+[Source](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/events.ts#L43)
 
 ### ctx.emit(name, ...args)
 
@@ -51,7 +51,7 @@ Dispatch an event synchronously, ignoring listener return values.
 - `name` — the event name.
 - `args` — arguments passed to every listener.
 
-[Source](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/events.ts#L53)
+[Source](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/events.ts#L52)
 
 ### ctx.serial(name, ...args)
 
@@ -74,7 +74,7 @@ Dispatch an event, awaiting listeners in order until one bails.
 
 **Returns** the first bail value (non-null, non-false, non-undefined), if any.
 
-[Source](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/events.ts#L63)
+[Source](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/events.ts#L62)
 
 ### ctx.bail(name, ...args)
 
@@ -97,7 +97,7 @@ Dispatch an event, calling listeners in order until one bails.
 
 **Returns** the first bail value (non-null, non-false, non-undefined), if any.
 
-[Source](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/events.ts#L73)
+[Source](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/events.ts#L72)
 
 ### ctx.waterfall(name, ...args)
 
@@ -125,7 +125,7 @@ Each listener wraps the rest of the chain: calling `next()` invokes the next lis
 
 **Returns** the outermost listener's return value.
 
-[Source](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/events.ts#L86)
+[Source](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/events.ts#L85)
 
 ### ctx.on(name, listener, options?)
 
@@ -149,7 +149,7 @@ Register an event listener owned by the current fiber.
 
 **Returns** a disposer removing the listener; `true` if it was still registered.
 
-[Source](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/events.ts#L97)
+[Source](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/events.ts#L96)
 
 ### ctx.once(name, listener, options?)
 
@@ -173,7 +173,7 @@ Same as `on()`, but the listener disposes itself after its first call.
 
 **Returns** a disposer removing the listener; `true` if it was still registered.
 
-[Source](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/events.ts#L106)
+[Source](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/events.ts#L105)
 
 ## EventOptions
 
@@ -189,7 +189,7 @@ interface EventOptions {
 }
 ```
 
-[Source](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/events.ts#L112)
+[Source](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/events.ts#L111)
 
 ## DispatchMode
 
@@ -209,4 +209,4 @@ Event dispatch strategy used by the event service.
 type DispatchMode = 'emit' | 'parallel' | 'serial' | 'bail' | 'waterfall'
 ```
 
-[Source](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/events.ts#L32)
+[Source](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/events.ts#L31)

package/kb/site/en/reference/cordis-api/fiber.md

@@ -39,7 +39,7 @@ Register a cleanup-aware effect on this fiber.
 
 **Returns** a disposer that tears the effect down and settles once done.
 
-[Source](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L415)
+[Source](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L421)
 
 ### ctx.fiber
 
@@ -56,7 +56,7 @@ The fiber (plugin runtime instance) that owns this context.
 
 Runtime instance of one plugin application.
 
-A fiber tracks dependency state, validated config, lifecycle effects, and cleanup for the plugin context returned by `ctx.plugin()`.
+A fiber tracks dependency state, raw and effective config, lifecycle effects, and cleanup for the plugin context returned by `ctx.plugin()`.
 
 [Source](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L184)
 
@@ -85,11 +85,11 @@ The context this fiber's plugin runs in (extends the parent context).
 ### fiber.config
 
 ```ts cordis-catalog
-/** The validated plugin config (updated by `update()`). */
+/** Raw plugin input retained for the next activation. */
 public config: any
 ```
 
-The validated plugin config (updated by `update()`).
+Raw plugin input retained for the next activation.
 
 [Source](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L190)
 
@@ -102,7 +102,7 @@ public state
 
 Current lifecycle state; transitions emit `internal/status`.
 
-[Source](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L194)
+[Source](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L192)
 
 ### fiber.dispose
 
@@ -113,16 +113,27 @@ public readonly dispose: () => Promise<void>
 
 Dispose this fiber: unload the plugin, then settle once cleanup finished.
 
+[Source](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L194)
+
+### fiber.committed
+
+```ts cordis-catalog
+/** Required implementations retained through dependent teardown. */
+public committed: Readonly<Dict<Impl>> | undefined
+```
+
+Required implementations retained through dependent teardown.
+
 [Source](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L196)
 
-### fiber.store
+### fiber.provisions
 
 ```ts cordis-catalog
-/** Snapshot of required service implementations while loaded; `undefined` otherwise. */
-public store: Dict<Impl> | undefined
+/** Service implementations owned by this fiber, including isolated provisions. */
+public readonly provisions: Set<Impl>
 ```
 
-Snapshot of required service implementations while loaded; `undefined` otherwise.
+Service implementations owned by this fiber, including isolated provisions.
 
 [Source](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L198)
 
@@ -146,7 +157,7 @@ get name()
 
 The plugin's display name, inherited from the nearest named ancestor, else `'root'`.
 
-[Source](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L336)
+[Source](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L342)
 
 ### fiber.assertActive()
 
@@ -164,7 +175,7 @@ Throw if the fiber has already been disposed.
 
 **Returns** nothing when the fiber is still active.
 
-[Source](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L351)
+[Source](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L357)
 
 ### fiber.effect(execute, label?)
 
@@ -195,7 +206,7 @@ Register a cleanup-aware effect on this fiber.
 
 **Returns** a disposer that tears the effect down and settles once done.
 
-[Source](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L415)
+[Source](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L421)
 
 ### fiber.getEffects()
 
@@ -212,7 +223,55 @@ Return metadata for currently registered effects.
 
 **Returns** one `EffectMeta` tree per labeled live effect.
 
-[Source](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L568)
+[Source](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L574)
+
+### fiber.rawConfig
+
+```ts cordis-catalog
+/** Raw input retained for the next activation, without evaluating expressions or validating it. */
+get rawConfig(): unknown
+```
+
+Raw input retained for the next activation, without evaluating expressions or validating it.
+
+[Source](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L649)
+
+### fiber.effectiveConfig
+
+```ts cordis-catalog
+/**
+ * The object passed to plugin activation or the latest successful update that retained the instance.
+ * Candidate resolution does not publish it; volatile updates retain its references.
+ * Undefined before activation and readable after unload; callers requiring a live instance check `state`.
+ */
+get effectiveConfig(): unknown
+```
+
+The object passed to plugin activation or the latest successful update that retained the instance. Candidate resolution does not publish it; volatile updates retain its references. Undefined before activation and readable after unload; callers requiring a live instance check `state`.
+
+[Source](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L664)
+
+### fiber.resolveConfig(config)
+
+```ts cordis-catalog
+/**
+ * Evaluate and validate a candidate using this fiber's `internal/config` hooks and runtime schema.
+ * Does not publish the result, replace raw input, or commit running volatile references.
+ * Required injections must be available when a hook uses them.
+ * @param config Raw candidate input.
+ * @returns The candidate's resolved config, retaining the schema's result identity.
+ * @throws {ValidationError} when the runtime schema rejects the candidate; hook errors propagate.
+ */
+resolveConfig(config: unknown): unknown
+```
+
+Evaluate and validate a candidate using this fiber's `internal/config` hooks and runtime schema. Does not publish the result, replace raw input, or commit running volatile references. Required injections must be available when a hook uses them.
+
+- `config` — Raw candidate input.
+
+**Returns** The candidate's resolved config, retaining the schema's result identity.
+
+[Source](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L676)
 
 ### fiber.await()
 
@@ -230,7 +289,7 @@ Wait for current lifecycle work and rethrow startup errors.
 
 **Returns** this fiber, once it has settled into a stable state.
 
-[Source](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L704)
+[Source](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L754)
 
 ### fiber.restart()
 
@@ -248,35 +307,29 @@ Dispose and immediately reload this plugin with its current config.
 
 **Returns** a promise resolving once the reload settled.
 
-[Source](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L718)
+[Source](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L768)
 
 ### fiber.update(config, noSave?)
 
 ```ts cordis-catalog
 /**
- * Validate and apply new config, then restart the plugin.
- *
- * Runs the `internal/update` waterfall first, so update hooks (and HMR)
- * can veto or replace the restart.
- *
- * @param config — the new raw config; validated before anything restarts.
- * @param noSave — hint for persistence hooks not to write the change back.
- * @returns nothing; the restart runs behind the `internal/update` waterfall.
- * @throws {ValidationError} when the new config fails validation.
+ * Resolve a candidate, retain its raw config and apply it through the update waterfall.
+ * @param config Raw config; pending fibers defer resolution until activation.
+ * @param noSave Suppress the persistence notification when true.
+ * @returns The awaited update/restart result, or undefined when a synchronous listener handles it.
+ * @throws {ValidationError} when an active fiber's candidate is invalid.
  */
-update(config: any, noSave = false)
+update(config: any, noSave = false): Awaitable<void>
 ```
 
-Validate and apply new config, then restart the plugin.
-
-Runs the `internal/update` waterfall first, so update hooks (and HMR) can veto or replace the restart.
+Resolve a candidate, retain its raw config and apply it through the update waterfall.
 
-- `config` — the new raw config; validated before anything restarts.
-- `noSave` — hint for persistence hooks not to write the change back.
+- `config` — Raw config; pending fibers defer resolution until activation.
+- `noSave` — Suppress the persistence notification when true.
 
-**Returns** nothing; the restart runs behind the `internal/update` waterfall.
+**Returns** The awaited update/restart result, or undefined when a synchronous listener handles it.
 
-[Source](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L736)
+[Source](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L783)
 
 ## Effect
 

package/kb/site/en/reference/cordis-api/inherited.md

@@ -26,15 +26,16 @@ This file is GENERATED from source (`scripts/gen-cordis-catalog.ts`) and verifie
 
 ## Inherited events (cordis core + loader/hmr/timer)
 
-- `internal/plugin` — A plugin fiber was created. ([`vendor/cordis/src/events.ts:331`](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/events.ts))
-- `internal/status` — A fiber changed lifecycle state. ([`vendor/cordis/src/events.ts:333`](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/events.ts))
-- `internal/service` — Interception hook for a service binding (no core producer). ([`vendor/cordis/src/events.ts:341`](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/events.ts))
-- `internal/update` — Waterfall: a fiber config update is being applied. ([`vendor/cordis/src/events.ts:343`](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/events.ts))
-- `internal/config` — Waterfall: a fiber config is being resolved before validation. ([`vendor/cordis/src/events.ts:339`](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/events.ts))
-- `internal/get` — Waterfall: a service is being read from the store. ([`vendor/cordis/src/events.ts:345`](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/events.ts))
-- `internal/set` — Waterfall: a service is being written to the store. ([`vendor/cordis/src/events.ts:347`](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/events.ts))
-- `internal/listener` — A listener was registered. ([`vendor/cordis/src/events.ts:349`](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/events.ts))
-- `internal/dispatch` — An event is being dispatched to listeners. ([`vendor/cordis/src/events.ts:351`](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/events.ts))
+- `internal/plugin` — A plugin fiber was created. ([`vendor/cordis/src/events.ts:337`](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/events.ts))
+- `internal/status` — A fiber changed lifecycle state. ([`vendor/cordis/src/events.ts:339`](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/events.ts))
+- `internal/service` — A service binding was refreshed in the matching isolation scope. ([`vendor/cordis/src/events.ts:341`](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/events.ts))
+- `internal/update` — Waterfall: apply resolved config; omitting next() keeps the current instance. ([`vendor/cordis/src/events.ts:348`](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/events.ts))
+- `internal/commit` — Persist raw config from a programmatic update unless noSave is set. ([`vendor/cordis/src/events.ts:355`](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/events.ts))
+- `internal/config` — Waterfall: resolve a candidate after injections are active without publishing it. ([`vendor/cordis/src/events.ts:362`](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/events.ts))
+- `internal/get` — Waterfall: a service is being read from the store. ([`vendor/cordis/src/events.ts:364`](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/events.ts))
+- `internal/set` — Waterfall: a service is being written to the store. ([`vendor/cordis/src/events.ts:366`](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/events.ts))
+- `internal/listener` — A listener was registered. ([`vendor/cordis/src/events.ts:368`](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/events.ts))
+- `internal/dispatch` — An event is being dispatched to listeners. ([`vendor/cordis/src/events.ts:370`](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/events.ts))
 - `exit` — The process is exiting on a signal. ([`vendor/loader/src/index.ts:25`](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/loader/src/index.ts))
 - `loader/config-update` — The loader config tree changed. ([`vendor/loader/src/index.ts:26`](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/loader/src/index.ts))
 - `loader/entry-init` — A config entry is being initialized. ([`vendor/loader/src/index.ts:27`](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/loader/src/index.ts))

package/kb/site/en/reference/experimental-persistence-catalog.md

@@ -16,5 +16,8 @@ Shared Session event declarations and resolved schemas appear in the [Session pe
 
 | Record | Owner | Purpose | Payload and source |
 |---|---|---|---|
+| `plugin:action-cards/decision` | `@deepseek-ai/dsh-action-cards` | Dismissals and kind-defined progress of action cards. | <code>ActionCardDecision</code> · [`packages/experimental/action-cards/src/types.ts`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/experimental/action-cards/src/types.ts) |
+| `plugin:client-ui-forge/worktree` | `@deepseek-ai/dsh-experimental-client-ui-forge` | A request, withdrawal, or creation of the worktree a Session starts in. | <code>WorktreeRecord</code> · [`packages/experimental/client-ui-forge/src/types.ts`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/experimental/client-ui-forge/src/types.ts) |
+| `plugin:forge-session/binding` | `@deepseek-ai/dsh-experimental-forge-session` | A caller or discovery action that binds, restores, or hides one change request. | <code>BindingRecord</code> · [`packages/experimental/forge-session/src/types.ts`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/experimental/forge-session/src/types.ts) |
 | `plugin:translator/request` | `@deepseek-ai/dsh-experimental-translator` | Provider-independent translation input, retained before dispatch. | <code>TranslationRequestRecord</code> · [`packages/experimental/translator/src/types.ts`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/experimental/translator/src/types.ts) |
 | `plugin:translator/result` | `@deepseek-ai/dsh-experimental-translator` | Successful translation, retained before it is returned to the consumer. | <code>TranslationResultRecord</code> · [`packages/experimental/translator/src/types.ts`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/experimental/translator/src/types.ts) |

package/kb/site/en/reference/index.md

@@ -69,15 +69,17 @@ Electron starts the private Desktop Host in Electron Node mode. The Host invokes
 
 ## Events
 
-Events are the extension points, and picking the right domain is the first decision in most changes.
+Events provide extension points in three domains.
 
 - **Session events** are durable facts appended to the log and broadcast through `session/event`. Use one when the fact must survive a reload.
 - **Agent events** (`agent/*`) carry a live `Agent`: inbox, step, status, request, validation, continuation. Use one to observe or intercept work in flight.
 - **Capability events** attach policy and adapters to a seam (`fs/*`, `tools/*`, `telemetry/*`) without importing the loop.
 
-AgentLoop awaits serial `agent/created` before queued work and rolls back failed initialization. Unload retains resources through Agent teardown; [agent-loop](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/core/agent-loop/README.md#understand-the-implementation) defines ordering.
+Subagent Activations own runtime tree membership.
 
-The [event map](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/event-producer-consumer.md) lists every event's producers and consumers.
+AgentLoop rolls back failed initialization and awaits serial `agent/created` before queued work; unload retains resources through teardown ([ordering](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/core/agent-loop/README.md#understand-the-implementation)).
+
+[Event producers and consumers](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/event-producer-consumer.md).
 
 ## Turn flow
 
@@ -86,7 +88,7 @@ A **step** is one model request plus the tools it calls. A **turn** is zero or m
 ```text
 turn/start
   claim next-step input plus one queued message
-  assemble prompt sections + tool schemas
+  snapshot Session model selection; assemble prompt sections + step-admitted tool schemas
   -> agent/pre-step; project runtime context at fallback
                                      reject | enter(messages, startsRequestSeries?)
      reject, or a first enter rewritten empty -> close the turn with no step
@@ -108,9 +110,11 @@ turn/end
 
 `turn/*`, `step/*`, `system/message`, `user/message`, `assistant/message`, `assistant/attempt`, and `tool/*` are durable session events; the rest are live extension points across three domains. `agent/assistant-stream` publishes process-local start, transient chunk, and end frames. The loop commits the complete compact stream as one message or log-only attempt before a committed end frame, and the Web Session-follow adapter is the live event's only remote consumer. `agent/pre-step`, `agent/request`, `llm/stream`, and the three `tools/*` events are waterfalls, whose listeners must call `next()` to delegate; `agent/turn-stopping` is serial and has no `next()`.
 
+Factory setup follows SessionStore entry and `session/created`, preceding `agent/created`; closing events commit before removal.
+
 One inbox feeds the driver; injected context waits for a waking message. AgentLoop’s durable `inbox` projection exposes pending input without live Agents.
 
-`agent/pre-step` decides the accepted input. Listeners may rewrite or reject claimed messages; a rejected or empty first claim closes a durable turn without a step. An enter decision may set `startsRequestSeries`: the loop logs a fresh `request/header` (reason `series`, or `change` with `startsSeries: true` when the envelope also changed). Wrapping listeners preserve that declaration with `{ ...decision, messages }`. After assembly and `step/start`, `agent/request` and `prepareCall()` resolve the actual route before the system prompt and accepted users are committed; cancellation during either async phase commits neither. Prepared call capabilities govern prompt admission, not preceding `request/context`. Each attempt refreshes registered runtime facts, reconciles the bound prompt, admits users once, and restores removed runtime context, logs header/context as needed, and freezes the request before streaming the bound call. Retries do not repeat assembly or `agent/pre-step`. Surface replacements and image-offload decisions after attachment start a new request series, including during the first resumed pre-step; unchanged resume continues the series. The first admitted step reserves the system head before user messages even for an empty prompt (no wire message). The prompt travels only as `system/message` history: an empty rendering clears all active system nodes, leaving no old prompt model-visible; capable routes append non-empty updates after cached history, including supported tool updates; incapable routes and new request series consolidate non-empty prompt text at the first system node, with logged empty replacements for non-empty later system nodes ([decision](https://github.com/deepseek-ai/deepseek-harness/blob/master/.agents/notes/implemented/architecture/2026-09-02-system-prompt-as-surface-node.md); [decision rule](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/core/agent-loop/README.md#understand-the-implementation)).
+Before assembly, the loop snapshots Session model selection in `AssembleContext.modelSelection` and `agent/pre-step.modelSelection`; retries retain it; omitted reasoning effort uses adapter defaults. `agent/pre-step` listeners accept, rewrite, or reject claimed messages; a rejected or empty first claim closes a durable turn without a step. An enter decision may set `startsRequestSeries`: the loop logs a fresh `request/header` (reason `series`, or `change` with `startsSeries: true` when the envelope also changed). Wrapping listeners preserve that declaration with `{ ...decision, messages }`. After assembly and `step/start`, the deprecated `agent/request` hook adjusts controls without changing the provider, model, or effort selection, and `prepareCall()` binds the adapter before the system prompt and accepted users are committed; cancellation during either async phase commits neither. Prepared call capabilities govern prompt admission, not preceding `request/context`. Each attempt refreshes registered runtime facts, reconciles the bound prompt, admits users once, and restores removed runtime context, logs header/context as needed, and freezes the request before streaming the bound call. Retries do not repeat assembly or `agent/pre-step`. Surface replacements and image-offload decisions after attachment start a new request series, including during the first resumed pre-step; unchanged resume continues the series. The system prompt travels as `system/message` history: empty text clears it, capable routes append updates, and other routes consolidate it at the first system node. [Agent-loop](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/core/agent-loop/README.md#understand-the-implementation) owns prompt admission and replacement details.
 
 The loop sends immutable requests with live cancellation and reuses freeze evidence for frozen identities; [agent-loop](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/core/agent-loop/README.md) owns construction and cancellation causes.
 
@@ -118,6 +122,8 @@ Failed steps [record missing tool results](https://github.com/deepseek-ai/deepse
 
 Details: the [sequence diagram](./agent-lifecycle.md), the [tool pipeline](./tool-execution-pipeline.md), and [cancellation and error recovery](./subsystems/core.md#the-agent-handle).
 
+[`ctx.tools.execute()`](./subsystems/tools.md) receives raw batches and concurrency limits.
+
 ## Session log
 
 The session log is the source of the context the model sees. `deriveMessages()` projects model history from it. Each `assistant/message` embeds the exact compact timed stream that produced its assembled content; `assistant/attempt` retains settled failed, retried, cancelled, and stream-error attempts without adding model history. Fork, resume, transcripts, telemetry, and persistence all derive from these durable settlements, while live UI incrementality comes from `agent/assistant-stream`; a hard process loss before settlement leaves no durable attempt stream ([decision](https://github.com/deepseek-ai/deepseek-harness/blob/master/.agents/notes/implemented/architecture/2026-09-01-v2-embedded-assistant-streams.md)).
@@ -126,7 +132,7 @@ Session consumers know only the current logical format. Header-only `stat` and `
 
 **Model-visible means logged.** Every model request must be reconstructable from the log. New model-visible inputs require session events. Plugins changing existing message content register [pure message projections](./subsystems/session.md#plugin-owned-message-projections); detached readers supply the same definitions explicitly. Tool changes are capability-independent; [Session tool history](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/core/session/README.md) supplies provider declarations.
 
-**Projection seam.** `dsh-session-projection` owns `ctx.sessionProjections`: registered units fold committed events incrementally, host consumers read one typed state with `stateOf()`, and carriers batch cropped client views with `snapshot()`. A host reader either requires this service during activation or fails explicitly when the registry or required key is absent. Contributors may retain `ctx.inject(['sessionProjections'], ...)` registration without silently defaulting a missing host value. The agent loop registers shared `turnBoundary` state for its readers ([decision](https://github.com/deepseek-ai/deepseek-harness/blob/master/.agents/notes/implemented/architecture/2026-08-19-session-projection-mandatory-seam.md)).
+**Projection seam.** `dsh-session-projection` owns `ctx.sessionProjections`: registered units fold committed events; carriers read selected client views through `snapshot()`. Domain services await registration, retain private handles, and expose business methods ([registration lifecycle](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/session/session-projection/README.md)). `AgentRegistry` exposes turn and step state through `turnBoundaryOf(session)`. `AgentLoop` owns `modelSelection` and inbox state ([loop lifecycle](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/core/agent-loop/README.md)).
 
 [Working directories](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/subsystems/working-directory.md) supply user context and execution paths without changing original project identity, sandbox write roots, or existing process directories.
 
@@ -136,7 +142,7 @@ A **seam** is a swappable capability with three roles: a **Service Definition**
 
 Seams are why one provider swap changes the whole product. Filesystem and subprocess providers share one execution world, so pointing them at a remote sandbox moves Bash, PTY, and LSP with them, with no provider forks. [Subagent providers](./subsystems/subagent.md) vary just as widely behind one interface, from a fresh child agent to a delegated turn in another product.
 
-[Experimental Agent Teams](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/subsystems/agent-team.md) exposes opt-in `ctx.agentTeams` coordination with durable roster and task state plus direct inbox messaging over continuable subagents.
+[Agent Teams](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/subsystems/agent-team.md) adds task policy and a shared task board when enabled for a root Session. Ordinary subagent controls own identity, messaging, discovery, interruption, and inbox waiting.
 
 ## Where new behavior goes
 
@@ -161,7 +167,7 @@ New behavior attaches to a documented extension point. Changing the loop itself
 | Add durable session state | extend `SessionEventMap`; render and replay from the log |
 | Generate session titles | register the sole `ctx.sessionTitle` provider |
 | Manage a same-session objective | use `ctx.goals`; continue through `agent/*` |
-| Fork a session at a turn boundary | `ctx.agents.create({ sessionId, seed, meta: { parentSession, seedLength } })` — only agent-loop-published sessions persist |
+| Fork at a turn boundary | `ctx.agents.create({ sessionId, seed, inheritedEventCount, meta: { isSeeded: true } })` — only agent-loop-published sessions persist |
 | Store sessions in a new backend | implement `SessionPersistence` (`create`/`open`/`stat`/`list`/`export`) over the shared handle scaffolding |
 | Scope a registration to one agent | use that agent's `agent.ctx` |