Master's new duplication gate flagged 4 clones, all from the website scripts
reusing existing gate patterns by copy. Extracted the shared halves instead of
ignoring:
- scripts/cordis-walk.ts — cordisModuleBody / eventMembers / serviceClasses,
one AST walk consumed by both gen-cordis-catalog and gen-website-api (the
two renderers must agree on WHAT exists; now they structurally do).
- scripts/md-fences.ts — fence extractor with per-gate info-string
classification, consumed by doc-typecheck and verify-website-yaml.
Behavior-neutral: regenerated catalogs and website pages are byte-identical
(--check green), doc-typecheck/yaml block counts unchanged. jscpd now reports
0 clones; full pre-push run 34/34 green.
Conflict resolution notes:
- package.json/run-gates: both sides' new doc-sync gates kept (master's
scoped-events/readme gates + this branch's website-api/website-yaml);
js-yaml devDeps deduped (master added them independently).
- pnpm-workspace/knip: website AND python/sdk-runtime entries kept.
- doc-typecheck/verify-type-equiv: master's condensed headers kept, website
glob retained in both scan scopes.
- vendor/cordis/src/fiber.ts: master's lifecycle-hardening code taken; this
branch's richer FiberState JSDoc reapplied on top. vendor/README.md logs
both local modifications (hardening = 6, JSDoc enrichment = 7).
- pnpm-lock: regenerated from master's side (pnpm install).
Post-merge sync the gates forced (the system working as designed):
- verify-website-yaml caught 4 stale plugin names from master's package
reorg (dsh-stdio-agent -> dsh-stdio-demo, dsh-acp-agent -> dsh-acp-demo);
8 references fixed across guide/ and develop/.
- gen-website-api picked up master's 6 new services automatically
(ctx.approval/permission/sandbox/sessionQuery/skills/tasks -> 6 new pages
+ sidebar); api/index.md hub updated to list them.
- AGENTS.md budget ceiling 1370 -> 1400: the website rows (layout line + two
command lines) and master's own growth collided with the old ceiling; all
three website rows are load-bearing (new top-level dir, new CI command).
Generator (all four structural gaps):
- harness service pages now render public properties/accessors, not just
methods (ctx.codeRuntime.language/isolation were missing);
- the class page merges the same-named interface half, so ctx.root/baseUrl/
events/logger/reflect/registry appear on Context (vendor root JSDoc gains
prose alongside @experimental);
- Pick<…> heritage on a Context merge resolves to the picked class members,
giving ctx.effect a documented signature on the Fiber page;
- {@link} tags normalize to code spans; merge sections get their own h2 so
reflect members no longer nest under 'Static members'.
verify-website-yaml: reject the unloadable 'group:' pseudo-name (tree.import
only special-cases 'cordis:'; no builtin is registered here) and recurse into
@cordisjs/plugin-group nested entry lists instead.
Prose corrected against loader/cordis source: service.md isolation example
uses the real group plugin + group: true + the required isolate map;
config.md documents concurrent entry startup (Promise.all; order via inject)
and the real hmr defaults (root ['.'], base/ignored/debounce); events.md
fixes emit (synchronous, not parallel), bail (null/false also delegate), and
serial (stops at the first bail value).
scripts/gen-website-api.ts renders website/zh-CN/api/{cordis,harness}/* and the
api-sidebar.json fragment the VitePress config imports, so pages and navigation
can never drift from the code: signatures, @param/@returns prose, dispatch
modes, and GitHub source links are extracted, never transcribed, and the
generator hard-errors on any rendered member missing docs. verify-website-api
(doc-sync + run-gates) is the freshness gate.
Replaces the hand-written zh api pages (7 pages covering 7 of 15 services,
with phantom APIs: Context.current/Context.events, agent/post-step, tool/call,
compact/*, llm/pre-request none of which exist) with generated English
references: 5 cordis pages, 15 per-service pages, and a 35-event catalog
grouped by scope. The hand-written hub api/index.md stays and now indexes the
full surface; zh for these pages arrives with the unified translation flow.
New doc-sync gate verify-website-yaml: each ```yaml block under
website/zh-CN (api/ excluded — generator-owned) must parse with the loader's
real schema (JSON_SCHEMA + !!js), use only EntryOptions keys, name only real
workspace packages, and pass only config keys the plugin's declared Config
type / schemastery schema accepts (collectConfigCatalog drives the key sets).
```yaml ignore-check opts out a deliberate-placeholder block (the
capability-trio tutorial keeps its fictional package names).
Comment-only enrichment across cordis/src/*.ts — Context, EventsService (+ the
ctx merges), Fiber, RegistryService, ReflectService, Service, logger — so the
website API generator can render a complete reference and hard-error on any
future undocumented member (vendor sync included). Logged as local
modification 6 in vendor/README.md; retire it when upstreamed to the fork.
INHERITED_SERVICES/EVENTS source pointers refreshed for the shifted lines;
cordis catalogs regenerated.
- website joins the pnpm workspace; root scripts website:dev/website:build;
run-gates gains a website-build gate (ci-primary + ci-static) — the
VitePress build doubles as the site's dead-link check; AGENTS.md documents
the commands.
- doc-typecheck + verify-type-equiv now scan website/zh-CN/**/*.md; every
```typescript fence converted to ```ts and made standalone-compilable
(55 compiled, 1 ignore-check). Phantom APIs the compiler caught are fixed:
invented event names (agent/turn-end, tool/call, llm/pre-request, ready,
dispose) replaced with real catalog events or per-plugin declare-module
merges; presentCall/inject/Config claims corrected to the real shapes.
- guide/config.md entry-fields table completed against loader EntryOptions;
its coding-agent example brought in line with examples/coding-agent.
The public kill result used the awkward phrase already-terminal. Rename it to already-finished and keep the model-facing response aligned; not-alive would be inaccurate because a force-failed registry record can still correspond to orphaned producer work.
Task kinds were open strings even though producer namespaces are an extension point. Add the merge-extensible TaskKindMap and derived TaskKind, cover consumer declarations in task and bundle tests, and retain the runtime non-empty check for untyped callers.
With exactOptionalPropertyTypes, owner?: Agent | undefined allowed an explicit undefined value that no caller needs. Tighten the property to owner?: Agent so unowned work is expressed by omitting it.
Record the requested task-service/backend split as a follow-up, using a systemd-backed runtime as a concrete candidate without guessing its durability and ownership contract in this PR. Regenerate the type and Cordis catalogs so public docs match the declarations.
Refresh the background-task branch onto the latest repository baseline before applying review feedback. This preserves merge ancestry, incorporates the current CI and package-structure changes, and ensures the review fixes are validated against the code that will actually receive the PR.
glob/globSync returns host-separator paths on Windows. Nine scripts that consume these paths for split('/'), manifest-key comparison, startsWith/includes exclusion checks, or committed-output rendering now normalize with .map(s => s.split(sep).join('/')) at ingestion. This replaces the previous replaceAll('\\\\', '/') with an explicit, self-documenting OS-separator-to-POSIX conversion.
Repair cross-group README links whose targets changed groups
(ui/jsonrpc, ui/app-boot -> examples; examples/* -> ui seams),
re-record the bilingual-pair consistency hashes for the docs the
rename touched on both language sides, and condense the AGENTS.md and
packages/README.md group entries. The packages/README ceiling rises
710 -> 760 for the mandated new examples/ hierarchy row (5% headroom).
Move the agent-spine bundle and the stdio/ACP/JSON-RPC app packages out of
core/ and ui/ into a new packages/examples/ group, renamed with a -demo
suffix so the npm name marks them as non-product surface:
core/agent-core -> examples/agent-spine-demo (dsh-agent-spine-demo)
ui/stdio-agent -> examples/stdio-demo (dsh-stdio-demo)
ui/acp-agent -> examples/acp-demo (dsh-acp-demo)
ui/jsonrpc-agent -> examples/jsonrpc-demo (dsh-jsonrpc-demo)
Update every code/config/test reference and reference-only doc mentions, and
regenerate module-graph, config-catalog, and doc-graphs. The jsonrpc bin
(dsh-jsonrpc-agent) and single-file exe (dsh-jsonrpc-agent-pkg) keep their
names; the SDK runtime-startup surface is reconciled separately.
shell:true space-joins the executable and args UNESCAPED (Node DEP0190), so
an absolute .cmd path breaks whenever the repo path contains spaces and
`pnpm run hygiene` fails. Invoke publint's (`node_modules/publint/src/cli.js`)
and tsc's (`node_modules/typescript/bin/tsc`) JS entry through process.execPath
instead — no shell, extension-agnostic, identical on every platform, matching
the pattern already used by doc-typecheck.ts.
Addresses ds-review-bot on #324.
execFileSync on a .cmd shim returns EINVAL on recent Node without shell:true. Same bug class as install-lefthook.mjs. Affected publint-all.ts and verify-node-next-types.ts.
(cherry picked from commit 5ae40bee1c840fbbdd197ee15907aa660a343c52)
execFileSync('node_modules/.bin/tsc') spawns an extensionless shim
that is not executable on Windows (the CVE-2024-27980 class the
sibling scripts hit); the catch treated the spawn failure as a compile
failure with empty diagnostics. The .cmd shim would need shell:true,
which concatenates args unescaped - a hazard for the temp project
path - so invoke typescript/bin/tsc through the current node instead;
identical behavior on every platform.
Note this gate had never actually run on this Windows checkout: with
the pre-eol=lf CRLF working copy the fence regex matched no ts blocks
('.' does not match \\r), so it reported 'no ts code blocks to check'
and exited green. The LF working tree surfaced the spawn bug; with
this fix the gate compiles all 21 blocks on Windows.
(cherry picked from commit b49993c28e068c2beb411eae1f0c8ac4985aa3ae)
spawnSync on a .cmd shim returns EINVAL/null status on recent Node (CVE-2024-27980) unless shell:true, which made postinstall fail and blocked every 'pnpm run' on Windows.
(cherry picked from commit 65a08f889ff9738ddaceeeb724e6e24f3be4b2ea)
