fix(web): correct the preset-layer contracts review found stale

None of these change behavior; each said something that was not true.

`SessionCwdConflict`'s doc block had been left stranded above the
`AgentPresetConflict` inserted under it, so one class carried a comment
about the other and the second carried none.

The roster comment named a `.system` directory that does not exist; the
shipped root is `config/agent-presets/`, and `system` is the trust its
entries carry.

The real-composition test attributed the disabled `api-gateway` row to
"side effects outside this process" alongside the port and the exporter.
It is disabled for a different reason — the api-proxy cannot mount in
this layer at all — and hiding that behind the same phrase would leave a
later layer unable to tell whether the line can come out.

One test claimed to refuse an adoption while asserting only that the
header records the preset; it now says what it checks.

`PERSONA_SECTION`/`PERSONA_ORDER` existed twice, once in the registry
that declares the slot and once restated in the row that replaces it —
a drift that would land a preset's persona beside the deployment's
instead of shadowing it. The registry exports them now.

The preset conflict message read "already runs agent preset undefined"
for a session that records none, which is the shape a deployment with no
roster produces; it names that case instead, with the regression that
reaches it through the gateway.

Finally, `PresetTree.write()` drops the `loader/config-update` the
inherited method emits — recorded on the override, since a future
edit-while-running flow needs its own persistence path.

packages/bundle/web-app/cordis.patch.yml

@@ -300,7 +300,8 @@
 - id: tool-web
   disabled: true
 
-# The preset roster. `.system` ships with the deployment and is read-only;
+# The preset roster. `config/agent-presets/` ships with the deployment and is
+# read-only (its entries carry `system` trust);
 # `$DSH_HOME/.agent-presets` is where a person — or an agent — authors their own, and
 # carries the same trust as shell access because a preset IS a composition.
 # `roots` is an assembly fact, not user config: the shipped preset directory

packages/bundle/web-app/package.json

@@ -32,6 +32,7 @@
     }
   },
   "dependencies": {
+    "@deepseek-ai/dsh-agent-presets": "workspace:^",
     "@deepseek-ai/dsh-client-connection": "workspace:^",
     "@deepseek-ai/dsh-client-hmr": "workspace:^",
     "@deepseek-ai/dsh-client-locale": "workspace:^",

packages/cordis/tool-cordis/src/api-catalog.ts

@@ -96,6 +96,10 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
         signature: 'async mount(agentCtx: Context, id?: string): Promise<AgentPreset>',
         jsDoc: '/**\n * Compose one agent from a preset, installing it under that agent alone.\n *\n * Call from the agent factory\'s `setup(agentCtx)`; a rejection there rolls\n * the agent creation back, so a broken preset never yields a half-composed\n * session.\n * @param agentCtx - the agent\'s scope context.\n * @param id - the preset id, or `undefined` for {@link defaultId}.\n * @returns the preset that was mounted, for the caller to record.\n * @throws when the preset is unknown or its composition is unusable.\n */',
       },
+      {
+        signature: 'serviceFor<K extends string & keyof Context>(agent: { ctx: Context }, name: K): Context[K] | undefined',
+        jsDoc: '/**\n * One agent\'s instance of a service its preset mounted.\n *\n * A preset publishes services behind `isolate` realms, which are invisible\n * outside the group that declares them — including to the host. This is how a\n * caller holding the agent reads one anyway: a request that is ABOUT a\n * session but arrives from outside it, which is every browser RPC.\n *\n * Read addressing only. A host row that `inject`s a service cannot use this,\n * because injection resolves before any session exists and has no agent to\n * key by; such a service belongs on the host plane instead.\n * @param agent - the agent whose composition to look inside.\n * @param name - the service name as the preset\'s rows resolve it.\n * @returns the agent\'s instance, or undefined when its preset mounts none.\n */',
+      },
     ],
   },
   {

packages/core/system-prompt/src/index.ts

@@ -110,6 +110,17 @@ export interface PromptAssembly {
   variables: Record<string, string | undefined>
 }
 
+/**
+ * The deployment persona's section name and order. Exported because a
+ * composition can replace this slot — an agent preset shadows the
+ * deployment's persona with its own — and both sides naming the same section
+ * is what makes the replacement work rather than duplicate.
+ */
+export const PERSONA_SECTION = 'deployment:persona'
+
+/** Prompt order of the persona slot; the first section a model reads. */
+export const PERSONA_ORDER = 0
+
 /** Valid variable names: how they are written between the braces. */
 const VARIABLE_NAME = /^[a-z][a-z0-9_]*$/
 
@@ -337,8 +348,8 @@ export class SystemPrompt extends Service {
       })
     }
     this.section({
-      name: 'deployment:persona',
-      order: 0,
+      name: PERSONA_SECTION,
+      order: PERSONA_ORDER,
       // The fallback narrows the optional input type; the schema already defaults it.
       text: config.persona ?? '',
     })

packages/host/apiproxy/src/api-proxy.ts

@@ -642,7 +642,6 @@ class SubagentSessionOwnership extends Error {
   }
 }
 
-/** Requested identity already belongs to a session with another project cwd. */
 /**
  * The requested preset differs from the one this session already runs.
  *
@@ -658,12 +657,16 @@ class AgentPresetConflict extends Error {
     readonly existingPreset: string | undefined,
   ) {
     super(
-      `session "${sessionId}" already runs agent preset ${JSON.stringify(existingPreset)}; `
+      existingPreset === undefined
+        ? `session "${sessionId}" records no agent preset, so it cannot be adopted under one; `
+        + 'a deployment composing no roster records none on any session — '
+        : `session "${sessionId}" already runs agent preset ${JSON.stringify(existingPreset)}; `
       + `requested ${JSON.stringify(requestedPreset)}. A session's preset is fixed at creation.`,
     )
   }
 }
 
+/** Requested identity already belongs to a session with another project cwd. */
 class SessionCwdConflict extends Error {
   constructor(
     readonly sessionId: SessionId,

packages/host/apiproxy/tests/api-proxy-agent-preset.spec.ts

@@ -153,6 +153,28 @@ describe('session.create with an agent preset', () => {
 
     expect(ctx.sessions.get(SessionId('s6'))?.header.agentPreset).toBeUndefined()
   })
+
+  it('says why a preset-less session cannot be adopted under one', async () => {
+    // Two callers reach this: a deployment that composes no roster, and a
+    // session created before one existed. Both record no preset, so naming
+    // any is a conflict rather than an adoption — the history was produced
+    // under a composition this roster cannot name. The message has to say
+    // that, because "already runs agent preset undefined" reads as a bug.
+    const { api } = await harness()
+    await api.sessions.create(request({ sessionId: SessionId('s7') }))
+
+    const response = await api.sessions.create(request({ sessionId: SessionId('s7'), agentPreset: 'standard' }))
+
+    expect(response.result.ok).toBe(false)
+    if (response.result.ok) throw new Error('unreachable')
+    expect(response.result.error.code).toBe('agent-preset-conflict')
+    expect(response.result.error.message).toContain('records no agent preset')
+    expect(response.result.error.details).toEqual({
+      sessionId: 's7',
+      requestedPreset: 'standard',
+      existingPreset: undefined,
+    })
+  })
 })
 
 /**

packages/preset/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/preset/README.md
-README.md: fcce3013174b5c3b7e545eb48e73cc1d8f4126dc
-README.zh.md: 281885daae9aab8dc989c232e751f9a255075b96
+README.md: d2ed10014af506809b5fd117e08b09b45a31a16c
+README.zh.md: db7bf18e6ba841cc705eafae7c09d4c5d26581b1

packages/preset/agent-presets/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/preset/agent-presets/README.md
-README.md: 8c95719bead97845519b7a334603005df201a34d
-README.zh.md: c5e2fd3c7896437ddb4a2acdf101cd2e0e0eedaf
+README.md: 1592fba1163448aaedbd482c56962fa07ebc897e
+README.zh.md: ef4512ab93783674890bc9a848e590792a820e8c

packages/preset/agent-presets/src/mount.ts

@@ -61,6 +61,11 @@ class PresetTree extends Include {
    * shipped composition to `[]` the first time a session ends. Persisting a
    * preset is also meaningless: nothing here is user state, and the same file
    * backs every session that names it.
+   *
+   * Dropping the write drops the `loader/config-update` the inherited method
+   * emits with it. Nothing observes one for a preset subtree today, and a
+   * future "edit your preset while it runs" flow needs a deliberate
+   * persistence path rather than this method's return.
    */
   override write(): void {
   }

packages/preset/persona/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/preset/persona/README.md
-README.md: 3a9f9f2e2debf9d4274949e14913137ef752baae
-README.zh.md: 2c3bac3bb4a1fbeeb9c30defb225c2b64cb3e577
+README.md: 789776b32d907f7d217accccbca5508f88de0ed1
+README.zh.md: 4e28d75bbd4fd22b77a0fa3b18c5f19df08588d8

packages/preset/persona/package.json

@@ -21,9 +21,7 @@
   "files": [
     "lib/index.js",
     "lib/invariant.js",
-    "lib/types/**/*.d.ts",
-    "lib/types/**/*.d.ts.map",
-    "src"
+    "lib/types/**/*.d.ts"
   ],
   "license": "BSD-3-Clause",
   "peerDependencies": {

packages/preset/persona/src/index.ts

@@ -17,11 +17,12 @@ import type { Context } from 'cordis'
 import z from 'schemastery'
 import type {} from '@deepseek-ai/dsh-system-prompt'
 
-/** The section name this plugin registers; the prompt registry's persona slot. */
-export const PERSONA_SECTION = 'deployment:persona'
+// Imported rather than restated: the registry declares the slot this row
+// replaces, and two hardcoded copies would drift into a preset whose persona
+// silently lands beside the deployment's instead of shadowing it.
+import { PERSONA_ORDER, PERSONA_SECTION } from '@deepseek-ai/dsh-system-prompt'
 
-/** Prompt order of the persona slot, matching the registry's own default. */
-export const PERSONA_ORDER = 0
+export { PERSONA_ORDER, PERSONA_SECTION }
 
 /** Cordis plugin name. */
 export const name = 'persona'