A hand-damaged preset was silent until the worst moment. An unparsable
composition listed as an ordinary selectable row and failed only at the
next session start — set as default, every new session failed. A
directory whose composition file was deleted vanished from the roster
while still occupying its id: copy answered "delete the existing preset
first" while remove answered "not found", a dead end.
Discovery now owns health: every id-shaped directory is a roster slot,
broken when its composition is missing or unloadable, checked with the
loader's own entryListSchema dialect (!!js included) so health never
rejects what the loader accepts. `broken` rides AgentPreset, the
agentPreset.list entry, and the UI row; mount/recompose/standingKeyFor
refuse broken up front with the discovery-reported reason, while
resolve/read/remove still answer. The section renders marked red cards —
unselectable, uncopyable, deletable, location kept on custom rows — and
both pickers drop broken rows entirely.
The cordis preset's persona now forbids editing the shipped install
(corrupting cordis would disable the mode itself) and points authoring
at $DSH_HOME/.agent-presets; its skill teaches preset.yml metadata, the
copy-first workflow, the one-escalation sandbox reality, and honest
verification. Exercised live: asked to edit the shipped composition the
composed agent refuses citing both rules; asked for real presets (simple
and complex) it lands them under the user root with one approved
escalation each and self-checks with the loader dialect.
core.md claimed to be the packages/core reference but opened on repo-wide type patterns and never documented the ownership vocabulary: AgentHandle, CreateAgentOptions, ResumeAgentOptions, and AgentFactory were TYPE_LINK_EXEMPTIONS pointing at a package README, invisible to the folder that calls itself the type reference. The page now reads spine map -> creation and ownership (AgentHandle pasted; the options and factory summarized with links into the generated registry section) -> the Agent handle (AgentStatus, AgentOptions, SteeringOutcome, SteeringReceipt, and SettleReason now pasted; the one settlement prose wall split by topic; delivery vocabulary ordered as a message travels) -> initiator -> interception -> a Sessions summary -> the ToolDefinition pointer -> an explicitly framed repo-wide patterns tail (the ...Map pattern, branded ids). The duplicate SessionEvent paste is gone -- session.md owns it and LINK_MAP follows -- the four ownership types moved from TYPE_LINK_EXEMPTIONS into LINK_MAP -> core.md, and three dead LINK_MAP entries (ContinuationDecision, ContinuationStop, HookContext) no longer name types absent from the source tree. The "what this page owns" meta-section folds into the intro.
The subsystems README index silently lost tasks.md and session-reference.md on both language sides during a base absorption; the rows are restored and scripts/project-doc-site.spec.ts now fails when any page misses either side of the index (proven red on a removed row). tools.md links ToolSchema to its llm-streaming.md declaration instead of calling it core; subagent.md links AgentHandle and CreateAgentOptions.seed to the new section. A new Agent Note records the package-anchored page-scoping decision; the 2026-06-20 catalog note marks its spine-vs-seam rule superseded as the page-scoping rule while keeping the type-equiv mechanism current, and docs/AGENTS.md cites the new note.
core.md read as a type grab-bag: LLM wire vocabulary up front, the agent/loop story buried, and no correspondence to packages/core. It now opens on the packages/core control spine — the package-by-package loop map with a Page column into session/system-prompt/tools/scope — and keeps only what the spine group declares plus the repo-wide patterns: the Agent handle with its delivery/cancellation/interception contracts, the SessionEvent envelope, branded ids, the …Map pattern. The conversation vocabulary (Message/ContentBlock, the model request, adapters — 17 type-equiv blocks) moves to llm-streaming.md, which now declares packages/llm end-to-end; the duplicate ContentBlockMap paste near its seam section folds into the moved section, and the manifest, LINK_MAP, README table rows, website label (Core data structures → Core), and inbound anchors follow.
Every packages/<group>/README pair is now a thin front door in one shape: a why-first intro (bash's seam-pattern-first paragraph rewritten as 'shell execution for the agent'), the package table, and a closing pointer to the owning docs/subsystems page — the bash-style table stays the load-bearing middle. Load-bearing trailing paragraphs relocate rather than vanish: the fs no-timeout rationale becomes a filesystem.md section (both languages), session's four sectioned tables merge into one 12-row table, examples' legacy-bin H2 collapses to a pointer at jsonrpc-demo's README, and design rationale that already lives in an Agent Note or subsystem page is now linked instead of restated. All 40 pair records re-recorded.
core.md doubled as the folder index: its intro claimed "this folder catalogs the data structures" and carried the 38-row page table, wording that predates the one-page-per-subsystem shape where every page also carries its generated Cordis surface. The folder index now lives in docs/subsystems/README.md (page table plus the type-equiv note), and core.md is one subsystem page among siblings: the spine vocabulary. Structural referents move with it: the docs/AGENTS.md tier table and update rule, development.md's type-equiv pointer, the dsh-code-review skill, the two owning catalog Agent Notes, and website/docs.ts (README projects as reference/subsystems/index.md and takes the docs/subsystems folder alias; sidebar orders shift by one). Remaining "data-structure catalog" / "sub-page" phrasing in active notes and READMEs is reworded to subsystem-page terms in both languages; touched pairs re-recorded; translation-prompt snapshot re-recorded (its example embeds development.md).
Rebuild of the region machinery (PR3) on the post-#904 Typert projection:
renderPageRegion/renderInheritedPage live in dsh-typert-generator beside the
projection; scripts/gen-cordis-catalog.ts owns the curated SERVICE_PAGE /
EVENT_SCOPE_PAGE / SERVICE_WALK_EXEMPTIONS / LINK_MAP partition (fail-loud in
both directions, with the independent Context-merge scan backstopping the
projection's blind spot), spliceRegion, and the guarded pair auto-record.
docs/cordis-catalog/ is deleted: the flat events/services catalogs dissolve
into per-page regions and docs/cordis-catalog/core moves to docs/cordis-api/
with the inherited tier as its own generated page. The partition absorbs the
post-regrouping surface: ctx.typert → invariants.md, ctx.directoryPicker →
workspace.md, skills/* events → skills.md, and the four launcher-provided tui
accessor values join the named exemptions.
ds-review-bot round 3:
- set() after a turn's final step lands in a later turn (selection
never forces continuation) — the same-turn phrasing overstated the
guarantee; set() JSDoc + subsystem page (both languages).
- Workspace attach/insert/detach no-op claims now carry the
filtered-candidate-prune caveat: mutate() durably prunes stale
candidates even when the requested change is a no-op, a state the
sessionIds contract explicitly permits; Workspace fence re-synced on
both page sides; catalogs regenerated.
ds-review-bot round 2: set() during an open multi-step turn applies at
the next request derivation in that same turn, so 'next turn boundary'
misstated the public timing contract (and propagated into the generated
catalogs). set()'s JSDoc, the module JSDoc, the pending-intent field
comment, and the subsystem page (both languages) now say step boundary;
catalogs regenerated; plan pair re-recorded.
ds-review-bot: ops records deliberately omit event.seq, so the
(session.id, event.seq) dedupe advice cannot apply to them — they are
alert signals that tolerate duplicates. Both language sides; pair
re-recorded.
Codex round-2: the two-line module-JSDoc fix moved every later
declaration in packages/plan/plan-mode/src/index.ts, so the three
generated catalogs' source-line links went stale. Three one-line
regenerated updates; doc-sync back to 25/25.
- plan.md/.zh.md (+ plan-mode module JSDoc and README pair): the sole
flush point is the prepended agent/step listener; prompt admission is
pre-turn and never flushes — the pages had it backwards.
- workspace.md/.zh.md: pending-mutation recovery deletes the marked
table row — completing an interrupted delete but rolling back an
interrupted create; 'completes exactly the marked mutation' oversold.
- telemetry.md/.zh.md: delivery is best-effort with possible loss AND
duplication, not at-most-once; TelemetryRecord.attributes JSDoc (source
+ both fences) now lists session.seed_length, which the coordinator
emits for forked sessions.
- Agent Note consequence bullet: nine pages cover ten services (storage
owns two keys); client-modules.zh.md wire-single-source phrasing.
Pairs re-recorded; plan-mode and telemetry suites green.
The translators' clause-by-clause verification pass caught the English
pages' final wording refinements (tui built-in dialogs enumeration and
display()'s line-feed exception, invariants whitespace-padded/companion
phrasing, client-modules fiber-lifecycle parenthetical, storage strict
sequence, workspace first-successful-start) landing after the initial
zh versions; this aligns the eight pages and re-records their pairs.
telemetry.md joins the eight pages after the OTel telemetry seam landed
on master (ctx.telemetry + telemetry/record were the one service and
event scope still without a page). All nine pages gain zh counterparts
translated whole-document per dsh-translate-docs; the eleven touched
pairs (nine new + core + the subsystems-catalog note) are recorded;
TelemetryRecord moves from TYPE_LINK_EXEMPTIONS to LINK_MAP and the
catalogs are regenerated.
permission, plan, invariants, http-server, storage (hub + backend seam +
domain form + domain/changed), workspace, tui, and client-modules complete
the docs/subsystems tier: every ctx service and event scope now has one
owning page, the precondition for generating per-subsystem service/event
reference into these pages. 25 new type-equiv manifest entries; 16 types
move from TYPE_LINK_EXEMPTIONS to LINK_MAP now that they have catalog
homes (dead InvariantRegistration exemption removed; catalogs
regenerated); core.md's sub-page table gains the eight rows in both
languages; the owning subsystems-catalog Agent Note records the coverage
extension. Chinese counterparts and pair records follow in the next
commit.
- dsh-host-webserver: the service is HttpServerService under ctx.httpServer
(README said WebServerService/ctx.webServer, matching no symbol in source),
and the dev-mode bundle-watch paragraph described machinery that moved to
dsh-client-modules/dsh-client-hmr in the webserver rewrite — removed; those
packages' READMEs already document the current pipeline.
- dsh-workspace: ctx.workspace.touchSession(id) does not exist; the
activity-pinning chain was replaced by Workspace.insertSessionBefore
(2026-07-25 session-list note) — the bullet now documents the real method.
- packages/storage group table: the domain package directory is
storage-domain/, not domain/.
All three pairs updated on both sides and re-recorded.
The folder is becoming the home of one-doc-per-subsystem pages (intro +
data structures + cordis services/events), so the name must describe the
whole contract, not just the type-vocabulary third of it. Mechanical
rename rebuilt on current master: every inbound Markdown link, generator
constant, website route, type-equiv manifest path, and spec expectation
moves together; the zh sides of the notes whose prose names the folder
are aligned (子系统) in the same change; touched bilingual pairs
re-recorded; translation-prompt snapshot re-recorded (its example embeds
development.md). Historical Agent Note slugs keep their dated
filenames.
Move the triplet to implemented/architecture/, rewrite Proposal into a
present-tense Decision, fold Acceptance criteria and Risks into
Consequences (recording what pins the result), retitle the migration
section to what the move actually touched, and repoint the seven
inbound FIXME/README links.
git mv timeout-policy beside repeat-tool-guard (both are loop-hygiene
policies on the tool-execution pipeline, and the timeout/ group name
collided with util/timeout) and tool-cordis into self-modification/
(naming the role the framework name obscured). Merged/renamed group
README triplets, tsconfig globs, generator sources, hierarchy tables,
catalogs, and the timeout-policy design note's group references
follow. Adds the fifth FIXME marker (dsh-timeout-guard, recorded as a
suggestion to settle at resolution time).
guard + self-modification suites: 197 passed.
git mv per the regrouping RFC: the five human-collaboration seams and
tui join packages/interaction/, app-boot becomes packages/boot/, and
jsonrpc joins the renamed scaffold/ (formerly sdk/) as its server half
beside client/protocol/create-sdk/helper/scripts/telemetry, whose
folders drop the legacy sdk- prefix. Three new group README triplets
replace the ui/ and sdk/ ones; tsconfig references/paths/globs,
knip keys, vitest globs, gate scripts, catalogs, docs, and the
lockfile follow. Adds the four settled FIXME rename markers
(dsh-sdk-server, dsh-sdk-telemetry, dsh-sdk-helper, dsh-sdk-scripts).
The scaffold folders diverge from their npm names until those renames
land, so tsconfig.base.json maps the three affected names explicitly
beside the group wildcard. Also repairs two pre-existing stale-path
classes the strengthened sweep surfaced: docs/web-styling.md's retired
web-ui host package and type-model spec fixture-literal joins.
app-boot's three Loader-composition specs time out at the default 5s
under full-suite parallel load on this filesystem (pre-existing;
pass isolated with --testTimeout=30000); interaction/scaffold/boot
suites otherwise green (687 passed).
git mv the 12 packages from session-persistence/, session-projection/,
session-title/, and telemetry/ into one session/ group per the
regrouping RFC; merge the four group READMEs into one bilingual
triplet; rewrite the group segment in tsconfig references (intra-group
references shorten to ../<pkg>), tsconfig.base.json paths/globs,
knip.json keys, vitest include, gate scripts, and authored doc/note
citations; regenerate module graph, doc graphs, catalogs, and the
lockfile importer keys. No npm names change.
Full unit suite: 8779 passed; the 18 reported failures reproduce as
env flakes (ambient-proxy IPv6 tunneling, watched-dir inotify
timeouts under parallel load) — each passes in isolation with
NO_PROXY set, matching their known pre-existing behavior on master.
RFC settling the target group map: fold the session family into one
session/ group, dissolve ui/ into interaction/ (+tui), boot/, and the
scaffold/ developer-tooling family (absorbing jsonrpc as server),
merge timeout/ into guard/, and rename cordis/ to self-modification/.
Zero npm renames now; five FIXME-tracked intended renames. Squash of
the reviewed RFC iterations (turtle1999 map corrections applied).
Copying an existing preset — or drafting one in Creator mode — replaces
the copy-minimal skeleton hint: the creator entry exists now, so the intro
names the two real paths instead of steering everyone at one source.
The stub's confirmed-switch write-back landed with the header-label work
but nothing exercised it, and the module graph regen after the master
merge had been swallowed by a silenced generator run.
The exported mountPreset carries its own unscoped-context guard beside the
service's, and the per-file gate wants it exercised where it lives. The
module graph regen after the master merge had been swallowed by a silenced
generator run.
The settings section gains the conversational authoring entry beside
copying: a dashed add-card (the Models page's affordance) that stages the
self-referential cordis preset and starts a new session on it, closing the
settings panel through the shell's new section owner-prop `close` — the
one shell affordance a section receives, for flows that leave settings.
The seat learns the difference between picking and staging: `select()`'s
immediate apply meets the still-current running session and drops the
stage as unservable, so the entry uses `stage()` and leaves the apply to
the list-change applier that fires when the started session becomes
current. `load()` stops regressing the display when its reply lands after
an applied stage was consumed — staged pick first, then the composition
the current session already carries, then the deployment default.
The authoring lane connects a workspace and drives the gesture to a
composed host session; the section goldens gain the entry.
The duotone folder_open_16 reads a rung heavier than the …Outline16 family
— its 20%-opacity inner fill looks filled beside pure-outline neighbors —
so an icon-button row mixing them looks mismatched. Same geometry, outline
layer only; the workspace surfaces keep the duotone original.
