SETUP 4 STEPS PROFILE: ~/.dsh
Set up the family in a DeepSeek Harness profile.
Four steps: add the bundles to the profile, add the patch entries, restart, verify the ledgers. Every step below is the actual wiring the loader reads - no separate configuration UI exists.
A profile's package.json lists the bundles as link: dependencies and in the dsh.profile.bundles list - the list is what activates them. The linked checkout must carry its own node_modules, and each bundle needs its own pnpm-workspace.yaml (packages: [.]): an install inside a bundle under the profile's workspace acts on the workspace root and does nothing to the bundle. Remote installs work the same way: pnpm add @playform/<pkg> in the profile directory plus the package in the bundles list, or dsh plugin --profile <name> add <tarball>.
{ "name": "my-dsh-profile", "dependencies": { "@playform/plugin-dsh-factory": "link:../bundles/plugin-dsh-factory", "@playform/hook-dsh-governor-package": "link:../bundles/hook-dsh-governor-package", "@playform/hook-dsh-pinner-package": "link:../bundles/hook-dsh-pinner-package", "@playform/hook-dsh-normalize-dash": "link:../bundles/hook-dsh-normalize-dash" }, "dsh": { "profile": { "bundles": [ "@playform/plugin-dsh-factory", "@playform/hook-dsh-governor-package", "@playform/hook-dsh-pinner-package", "@playform/hook-dsh-normalize-dash" ] } } }
Each bundle ships a cordis.patch.yml whose insert: entries declare the loader row and the config. A bare id: row patches an existing entry; the loader rejects unknown ids with entry "..." not found. The factory needs no config - it registers the service, and the consumers' rows do the rest. The example below is the deployed combination: the two governance plugins with raw-write added to mutationTools, and the dash flavor with the example patch's opt-in toolArgs:
- insert: - id: plugin-dsh-factory name: "@playform/plugin-dsh-factory" config: {} - insert: - id: hook-dsh-governor-package name: "@playform/hook-dsh-governor-package" config: log: true logFile: ~/.dsh/hook-dsh-governor-package.log updateCooldownMs: 3000 strict: false mutationTools: [write, edit, str_replace_editor, raw-write] maxUpdateFailures: 3 ncuBin: /usr/local/bin/ncu updateMode: programmatic policyFile: "" exclude: [node_modules, .git, .dsh, .pnpm, .store, DeepSeek Harness.app] - insert: - id: hook-dsh-normalize-dash name: "@playform/hook-dsh-normalize-dash" config: log: true logFile: ~/.dsh/hook-dsh-normalize-dash.log replacement: "-" normalizeReasoning: true normalizeToolArguments: true
Bundle layers compose when the host boots - activation is at the next start, not at install time. A file: dependency alone is NOT activation: the bundles list plus the restart is what loads the entries from each bundle's built Target/. Every rebuild of a linked bundle's Target is fresh on the next restart, so the dev loop is edit - build - restart.
"Did it activate" is answerable from the ledger alone: each plugin writes its activation line to its own ~/.dsh/<name>.log at boot - the ledgers and the runtime's inspect providers are the activation assessors (the old --dump-config verification path is gone behind the app-managed profile guard). Read the effective config from the bundle patch layers, not the schema projection alone: a patch config replaces the entry config wholesale, so the defaults the schema advertises may not be what runs.
hook-dsh-governor-package: activated (anywhere mode, logFile=~/.dsh/hook-dsh-governor-package.log, updateMode=programmatic, ncuBin=/usr/local/bin/ncu, exclude=[node_modules, .git, .dsh, .pnpm, .store, DeepSeek Harness.app], policyFile=(discovery)) hook-dsh-pinner-package: activated (pinner, logFile=~/.dsh/hook-dsh-pinner-package.log, sections=[dependencies, devDependencies, peerDependencies, optionalDependencies], exclude=[node_modules, .git, .dsh, .pnpm, .store, DeepSeek Harness.app]) hook-dsh-normalize-dash: activated (replacement=-, reasoning=on, toolArgs=off, logFile=~/.dsh/hook-dsh-normalize-dash.log)
Every knob below is a real field in the packages' Config schemas; volatile cells (log, logFile, replacement and each plugin's own hot fields) commit without remounting the plugin. Each plugin's full table lives on its page: the package governor, the pinner, the cargo governor, the dash flavor, the normalize-file tool and the factory service.
The governance trio
log / logFile - the durable ledger file (each plugin keeps its own, separate by default)
mutationTools - which actor tools count as triggers - the deployed layers set [write, edit, str_replace_editor, raw-write]
exclude - the exclusion segments - the plugin's own fence (node_modules, .git, .dsh, ...)
updateCooldownMs / maxUpdateFailures - the update stage's pacing and its circuit breaker (3 failures pause a directory)
updateMode + ncuBin / cargoBin - programmatic (library) vs bin (external binary via the subprocess seam); absolute paths because host PATH != shell PATH
strict - strip unknown dependencies - explicit only, never a default-delete
policyFile / keepFile / sections - the update-policy and keep-list sidecars, and which dependency sections the pinner touches
The stream flavors
log / logFile - the flavor's own ledger, separate from the family's logs
replacement - the transform's only knob on class flavors (dash - / ellipsis ... / spaces space / invisible empty) - hot-editable, the next stream picks it up with no remount
normalizeReasoning - default ON - normalize reasoning deltas and the assembled reasoning block too
normalizeToolArguments - default OFF - tool-call arguments are execution-critical raw JSON; the example patch turns it on (opt-in)
The file tool
log / logFile - the normalize-file ledger
replacement - the dash step's replacement - the transform's only knob
normalize (per call) - the raw-write tool's sibling flag: absent/false = verbatim, true = all six transforms, or the flavor-name array
normalizeToolArguments: false DEFAULT OFF
The default. Tool-call arguments are execution-critical raw JSON - rewriting them is the user's accepted risk, so the schema default is OFF and the example patch turns it on. Even when on, edit and raw-write calls pass through by identity and a {"__normalize":false-marked call passes through unnormalized.
govern: absent ESCAPE HATCH
The raw-write tool's escape hatch: with no govern flag the write emits fs/observed exactly like a built-in write and the event path governs it as always - the per-call direct chain only runs when you ask for it.
normalize: absent (raw-write) VERBATIM BY DEFAULT
The default posture of the raw-write tool: content lands verbatim, byte-for-byte. Normalization happens only when the call selects it - all six transforms, or specific flavors.
Tracing: no-op by default ZERO COST BY DEFAULT
The Effect-TS release wraps every governance stage in spans (dsh.gate, dsh.discover, dsh.chain-pass, dsh.write) but ships Effect's no-op Tracer as the default - zero cost, no behavior change. The OTLP exporter attaches only when configured, and spans never alter ledger strings or timing-sensitive gates.
The parallel-govern toggle PLANNED · DEFAULT SEQUENTIAL
The direct-govern path is deliberately SEQUENTIAL (the awaited fold - the live-verified race fix); the event path is inherently concurrent. A per-call toggle to run the steps concurrently is designed (#14) to ride the same govern flag shape in both releases - planned, with the sequential fold as the default.
Best-effort everywhere SILENCE AS INVARIANT
Storage records buffer or drop when no storage facility is present (the human ledger stays the complete record); excluded paths log one line and move on; a no-op write writes nothing; a thrown-away stream writes no ledger line. Silence is the invariant; the ledger is the receipt.
Each plugin writes its own durable ledger - the governor's, the pinner's and the cargo governor's are separate files and separate concerns: activating one never implies another. The line format is [<ISO>] <message> in the file and <plugin>: <message> on the logger, both composed by the factory's Append around the plugin's own string.
| Plugin | Ledger | First line at boot |
|---|
| hook-dsh-governor-package | ~/.dsh/hook-dsh-governor-package.log | activated (anywhere mode, ...) |
| hook-dsh-pinner-package | ~/.dsh/hook-dsh-pinner-package.log | activated (pinner, ...) |
| hook-dsh-governor-cargo | ~/.dsh/hook-dsh-governor-cargo.log | activated (cargo flavor, ...) |
| hook-dsh-normalize-dash | ~/.dsh/hook-dsh-normalize-dash.log | activated (replacement=-, reasoning=on, ...) |
| hook-dsh-normalize-file | ~/.dsh/hook-dsh-normalize-file.log | activated (replacement=-, ...) |