dsh-plugin-capabilities 0.1.1 → 0.1.3

package/src/client/McpTab.tsx

@@ -28,7 +28,7 @@ export interface McpInjected {
   remove(id: string): Promise<{ ok: boolean }>
   scanImport(): Promise<{ servers: ImportedServerView[]; existing: string[] }>
   applyImport(items: Array<{ agent: string; name: string }>): Promise<{ ok: boolean; results: Array<{ name: string; ok: boolean; error?: string }> }>
-  restart(): void
+  restart(): Promise<void>
   desktop: boolean
 }
 
@@ -71,6 +71,8 @@ export function McpTab(props: { t: Translate; injected: McpInjected }): ReactEle
   const [importItems, setImportItems] = useState<Array<{ server: ImportedServerView; existing: boolean; checked: boolean }> | null>(null)
   const [busy, setBusy] = useState(false)
   const [pending, setPending] = useState(false)
+  const [restartConfirm, setRestartConfirm] = useState(false)
+  const [restarting, setRestarting] = useState(false)
   const [outcome, setOutcome] = useState<{ ok: boolean; text: string } | null>(null)
   const [formError, setFormError] = useState<string | null>(null)
   const [reload, setReload] = useState(0)
@@ -203,15 +205,36 @@ export function McpTab(props: { t: Translate; injected: McpInjected }): ReactEle
     }
   }
 
+  const doRestart = (): void => {
+    setRestartConfirm(false)
+    setRestarting(true)
+    void injected.restart()
+    // 桌面模式：壳层重启完成后会重载窗口。独立模式：轮询本源，恢复即刷新。
+    if (injected.desktop) return
+    const deadline = Date.now() + 60_000
+    const poll = (): void => {
+      if (Date.now() > deadline) return
+      window.setTimeout(() => {
+        void injected.list().then(
+          () => { window.location.reload() },
+          () => { poll() },
+        )
+      }, 1500)
+    }
+    window.setTimeout(poll, 3000)
+  }
+
   const restartBanner = (
     <div className="dpc-banner" data-kind="info" role="status">
       <StateDot state="ongoing" size={10} />
       <div className="dpc-bannerBody">
-        <span>{t('restartNeeded')}</span>
+        <span>{restarting ? t('restarting') : t('restartNeeded')}</span>
         <span className="dpc-bannerHint">
-          {injected.desktop
-            ? <>{t('restartDesktopHint')}{' '}<Button variant="outline" size="sm" onClick={injected.restart}>{t('restartNow')}</Button></>
-            : t('restartOtherHint')}
+          {restarting
+            ? (!injected.desktop && t('restartPortHint'))
+            : injected.desktop
+              ? <>{t('restartDesktopHint')}{' '}<Button variant="outline" size="sm" onClick={() => setRestartConfirm(true)}>{t('restartNow')}</Button></>
+              : t('restartOtherHint')}
         </span>
       </div>
     </div>
@@ -225,6 +248,7 @@ export function McpTab(props: { t: Translate; injected: McpInjected }): ReactEle
         <IconApiOutline14 aria-hidden="true" />
         <h3>{t('mcpTitle')}</h3>
         <span className="dpc-spacer" />
+        <Button variant="ghost" size="sm" disabled={restarting} onClick={() => setRestartConfirm(true)}>{t('restart')}</Button>
         <Button variant="ghost" size="sm" onClick={() => void openImport()}>{t('importServers')}</Button>
         <Button variant="primary" size="sm" onClick={openCreate}>{t('addServer')}</Button>
       </div>
@@ -236,7 +260,7 @@ export function McpTab(props: { t: Translate; injected: McpInjected }): ReactEle
           <div className="dpc-bannerBody"><span>{outcome.text}</span></div>
         </div>
       )}
-      {pending && restartBanner}
+      {(pending || restarting) && restartBanner}
 
       <div className="dpc-listHead">
         <h3>{t('mcpTab')}</h3>
@@ -352,6 +376,20 @@ export function McpTab(props: { t: Translate; injected: McpInjected }): ReactEle
         <p>{t('removeWarn')}</p>
       </Modal>
 
+      <Modal
+        open={restartConfirm}
+        onClose={() => setRestartConfirm(false)}
+        title={t('restartConfirmTitle')}
+        footer={
+          <>
+            <Button variant="ghost" onClick={() => setRestartConfirm(false)}>{t('cancel')}</Button>
+            <Button variant="primary" onClick={doRestart}>{t('restartNow')}</Button>
+          </>
+        }
+      >
+        <p>{t('restartConfirmBody')}</p>
+      </Modal>
+
       <Modal
         open={importOpen}
         onClose={() => setImportOpen(false)}

package/src/client/index.ts

@@ -80,7 +80,14 @@ export function apply(ctx: CapabilitiesClientContext): void {
     scanImport: () => fetchJson<{ servers: ImportedServerView[]; existing: string[] }>('/dsh-plugin-capabilities/import/scan'),
     applyImport: (items: Array<{ agent: string; name: string }>) =>
       post('/dsh-plugin-capabilities/import/apply', { items }) as Promise<{ ok: boolean; results: Array<{ name: string; ok: boolean; error?: string }> }>,
-    restart: (): void => { window.dshDesktop?.restartSidecar?.() },
+    restart: async (): Promise<void> => {
+      if (window.dshDesktop !== undefined) {
+        window.dshDesktop.restartSidecar?.()
+        return
+      }
+      // 独立 dsh web：自重启路由。连接在关停途中断开属预期，不算失败。
+      try { await post('/dsh-plugin-capabilities/restart', {}) } catch { /* dying mid-restart is expected */ }
+    },
     desktop: window.dshDesktop !== undefined,
   }
 

package/src/client/locales.ts

@@ -62,6 +62,11 @@ export const zh = {
   restartDesktopHint: '重启由桌面应用负责：托盘菜单「重启服务」。',
   restartOtherHint: '重启方式：关闭当前 dsh 进程后重新运行。',
   restartNow: '重启服务',
+  restart: '重启',
+  restartConfirmTitle: '重启 dsh？',
+  restartConfirmBody: '重启会中断正在进行的回合，未保存的输入可能丢失；MCP 行的变更将在重启后生效。',
+  restarting: '正在重启，恢复后将自动刷新页面…',
+  restartPortHint: '若重启后页面长时间未恢复，可能是端口已变化：在终端查看新地址后打开。',
   failed: '操作失败',
 }
 
@@ -127,5 +132,10 @@ export const en = {
   restartDesktopHint: 'The desktop app owns restarts: use the tray “Restart service”.',
   restartOtherHint: 'Restart by closing this dsh process and running it again.',
   restartNow: 'Restart service',
+  restart: 'Restart',
+  restartConfirmTitle: 'Restart dsh?',
+  restartConfirmBody: 'Restarting interrupts any running turn and may lose unsaved input; pending MCP changes apply after the restart.',
+  restarting: 'Restarting — the page will reload once the host is back…',
+  restartPortHint: 'If the page does not recover, the port may have changed: check the terminal for the new URL.',
   failed: 'Operation failed',
 }

package/src/mcp.test.ts

@@ -44,6 +44,41 @@ describe('profile patch CRUD', () => {
     expect(rows[0].env).toEqual({ GITHUB_TOKEN: 'secret' })
   })
 
+  it('writes rows inside an anonymous insert list, never as bare entries', () => {
+    // The loader skips bare `- id:` entries whose target does not exist;
+    // only `- insert:` rows mount. This is the contract that made 0.1.2
+    // rows invisible to the agent.
+    const text = readFileSync(patch(), 'utf8')
+    expect(text).toContain('- insert:')
+    expect(text).not.toMatch(/^- id: mcp-/m)
+    expect(text).toMatch(/^ {4}- id: mcp-github$/m)
+  })
+
+  it('absorbs legacy bare rows into the insert list on the next write', () => {
+    writeFileSync(patch(), [
+      '- id: dsh-market',
+      '  config:',
+      '    allowRestart: false',
+      '- id: mcp-open-websearch',
+      '  name: "@deepseek-ai/dsh-mcp-client"',
+      '  config:',
+      '    serverName: open-websearch',
+      '    transport: stdio',
+      '    command: npx',
+      '',
+    ].join('\n'))
+
+    expect(listMcp(profile)).toHaveLength(1)
+    expect(listMcp(profile)[0]).toMatchObject({ id: 'mcp-open-websearch', serverName: 'open-websearch' })
+
+    upsertMcp(profile, { id: '', serverName: 'context7', transport: 'stdio', command: 'npx' })
+    const text = readFileSync(patch(), 'utf8')
+    expect(text).not.toMatch(/^- id: mcp-open-websearch/m)
+    expect(text).toMatch(/^ {4}- id: mcp-open-websearch$/m)
+    expect(text).toContain('dsh-market')
+    expect(listMcp(profile)).toHaveLength(2)
+  })
+
   it('preserves foreign rows and comments across edits', () => {
     writeFileSync(patch(), [
       '# user comment',
@@ -90,4 +125,11 @@ describe('profile patch CRUD', () => {
     expect(listMcp(profile).find(row => row.id === 'mcp-github')).toBeUndefined()
     expect(removeMcp(profile, 'mcp-github')).toBe(false)
   })
+
+  it('drops the insert entry once its last row is removed', () => {
+    for (const row of listMcp(profile)) removeMcp(profile, row.id)
+    const text = readFileSync(patch(), 'utf8')
+    expect(text).not.toContain('- insert:')
+    expect(listMcp(profile)).toHaveLength(0)
+  })
 })

package/src/mcp.ts

@@ -3,6 +3,13 @@
  * `@deepseek-ai/dsh-mcp-client` row per server. The YAML document API keeps
  * foreign rows and comments intact across edits. Row changes need a dsh
  * restart to compose — callers surface that as a pending-restart notice.
+ *
+ * The loader's patch grammar distinguishes creates from overrides: a bare
+ * `- id: …` entry only overrides an existing row (target missing → skipped
+ * with a warning), while new rows must live in an anonymous `- insert:`
+ * list. Managed rows therefore always sit inside one insert entry, and any
+ * legacy bare rows (written before this contract was understood) are
+ * absorbed into it on the next write.
  */
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
@@ -38,7 +45,12 @@ export type McpInput = Omit<McpRow, 'disabled'> & { disabled?: boolean }
 function loadPatch(profileDirPath: string): Document {
   const path = join(profileDirPath, 'cordis.patch.yml')
   const text = existsSync(path) ? readFileSync(path, 'utf8') : '[]'
-  return parseDocument(text)
+  const doc = parseDocument(text)
+  const contents = doc.contents as YAMLSeq | null
+  // The default-empty file parses as a flow `[]`; the patch layer is
+  // human-edited block YAML, so flip the flag before anything appends.
+  if (contents !== null && contents.flow === true && contents.items.length === 0) contents.flow = false
+  return doc
 }
 
 function savePatch(profileDirPath: string, doc: Document): void {
@@ -53,13 +65,57 @@ function toNode<T>(value: unknown): T {
 
 /** The patch row sequence; an empty file's null root becomes an empty seq. */
 function rowSeq(doc: Document): YAMLSeq<YAMLMap> {
-  if (doc.contents === null) doc.contents = toNode<YAMLSeq<YAMLMap>>([])
+  if (doc.contents === null) {
+    doc.contents = toNode<YAMLSeq<YAMLMap>>([])
+    // An empty seq defaults to flow style (`[]`); the file must stay block.
+    ;(doc.contents as YAMLSeq).flow = false
+  }
   return doc.contents as YAMLSeq<YAMLMap>
 }
 
-/** Rows whose `name` is the MCP client plugin. */
-function mcpRows(doc: Document): YAMLMap[] {
-  return (rowSeq(doc).items ?? []).filter(item => item.get('name') === MCP_PLUGIN)
+function isSeqNode(value: unknown): value is YAMLSeq<YAMLMap> {
+  return typeof value === 'object' && value !== null && Array.isArray((value as YAMLSeq).items)
+}
+
+/** A patch entry's insert list when it is the anonymous create form. */
+function insertListOf(item: YAMLMap): YAMLSeq<YAMLMap> | undefined {
+  if (item.has('id')) return undefined
+  const node = item.get('insert')
+  return isSeqNode(node) ? node : undefined
+}
+
+/** Every managed row: legacy bare entries (no list) and insert-list rows. */
+function mcpRowItems(doc: Document): { node: YAMLMap, list?: YAMLSeq<YAMLMap> }[] {
+  const found: { node: YAMLMap, list?: YAMLSeq<YAMLMap> }[] = []
+  for (const item of rowSeq(doc).items ?? []) {
+    if (item.get('name') === MCP_PLUGIN) found.push({ node: item })
+    const list = insertListOf(item)
+    for (const row of list?.items ?? []) {
+      if (row.get('name') === MCP_PLUGIN) found.push({ node: row, list })
+    }
+  }
+  return found
+}
+
+/** Map one row node to its browser-facing shape. */
+function rowToMcp(doc: Document, item: YAMLMap): McpRow {
+  // config is a YAMLMap node — materialize it before property access.
+  const configNode = item.get('config') as unknown
+  const plain = (typeof configNode === 'object' && configNode !== null && typeof (configNode as { toJS?: unknown }).toJS === 'function'
+    ? (configNode as { toJS(document: Document): unknown }).toJS(doc)
+    : {}) as Record<string, unknown>
+  return {
+    id: String(item.get('id') ?? ''),
+    serverName: String(plain.serverName ?? ''),
+    transport: plain.transport === 'streamable-http' ? 'streamable-http' : 'stdio',
+    disabled: item.get('disabled') === true,
+    ...(typeof plain.command === 'string' && plain.command !== '' ? { command: plain.command } : {}),
+    ...(Array.isArray(plain.args) ? { args: plain.args.map(String) } : {}),
+    ...(isStringMap(plain.env) ? { env: plain.env } : {}),
+    ...(typeof plain.cwd === 'string' && plain.cwd !== '' ? { cwd: plain.cwd } : {}),
+    ...(typeof plain.url === 'string' && plain.url !== '' ? { url: plain.url } : {}),
+    ...(isStringMap(plain.headers) ? { headers: plain.headers } : {}),
+  }
 }
 
 function isStringMap(value: unknown): value is Record<string, string> {
@@ -67,28 +123,52 @@ function isStringMap(value: unknown): value is Record<string, string> {
   return Object.values(value).every(entry => typeof entry === 'string')
 }
 
+/**
+ * The insert list that owns managed rows, creating it when absent and
+ * absorbing legacy bare rows into it. Absorbed rows were inert under the
+ * loader's override-only reading of bare entries, so the move is not just
+ * cosmetic — it is what makes them compose.
+ */
+function managedInsert(doc: Document): YAMLSeq<YAMLMap> {
+  const seq = rowSeq(doc)
+  const bare: YAMLMap[] = []
+  let target: YAMLSeq<YAMLMap> | undefined
+  for (const item of seq.items ?? []) {
+    if (item.get('name') === MCP_PLUGIN) bare.push(item)
+    const list = insertListOf(item)
+    if (list !== undefined && list.items.some(row => row.get('name') === MCP_PLUGIN)) target ??= list
+  }
+  if (target === undefined) {
+    const entry = toNode<YAMLMap>({ insert: [] })
+    seq.add(entry)
+    target = entry.get('insert') as YAMLSeq<YAMLMap>
+    target.flow = false
+  }
+  for (const row of bare) {
+    seq.items.splice(seq.items.indexOf(row), 1)
+    target.add(row)
+  }
+  return target
+}
+
+/** Every id in use: top-level patch entries and rows inside insert lists. */
+function takenIds(doc: Document): Set<string> {
+  const taken = new Set<string>()
+  for (const item of rowSeq(doc).items ?? []) {
+    const id = String(item.get('id') ?? '')
+    if (id !== '') taken.add(id)
+    for (const row of insertListOf(item)?.items ?? []) {
+      const rowId = String(row.get('id') ?? '')
+      if (rowId !== '') taken.add(rowId)
+    }
+  }
+  return taken
+}
+
 /** Read every mcp-client row in the profile layer. */
 export function listMcp(profileDirPath: string): McpRow[] {
   const doc = loadPatch(profileDirPath)
-  return mcpRows(doc).map(item => {
-    // config is a YAMLMap node — materialize it before property access.
-    const configNode = item.get('config') as unknown
-    const plain = (typeof configNode === 'object' && configNode !== null && typeof (configNode as { toJS?: unknown }).toJS === 'function'
-      ? (configNode as { toJS(document: Document): unknown }).toJS(doc)
-      : {}) as Record<string, unknown>
-    return {
-      id: String(item.get('id') ?? ''),
-      serverName: String(plain.serverName ?? ''),
-      transport: plain.transport === 'streamable-http' ? 'streamable-http' : 'stdio',
-      disabled: item.get('disabled') === true,
-      ...(typeof plain.command === 'string' && plain.command !== '' ? { command: plain.command } : {}),
-      ...(Array.isArray(plain.args) ? { args: plain.args.map(String) } : {}),
-      ...(isStringMap(plain.env) ? { env: plain.env } : {}),
-      ...(typeof plain.cwd === 'string' && plain.cwd !== '' ? { cwd: plain.cwd } : {}),
-      ...(typeof plain.url === 'string' && plain.url !== '' ? { url: plain.url } : {}),
-      ...(isStringMap(plain.headers) ? { headers: plain.headers } : {}),
-    }
-  })
+  return mcpRowItems(doc).map(({ node }) => rowToMcp(doc, node))
 }
 
 /** Validate one write request; returns the rejection reason or null. */
@@ -109,17 +189,15 @@ export function validateMcpInput(input: McpInput): string | null {
 export function upsertMcp(profileDirPath: string, input: McpInput): string {
   const inputId = input.id ?? ''
   const doc = loadPatch(profileDirPath)
-  const seq = rowSeq(doc)
+  const list = managedInsert(doc)
 
   const existing = inputId !== ''
-    ? mcpRows(doc).find(item => item.get('id') === inputId)
+    ? mcpRowItems(doc).find(({ node }) => String(node.get('id') ?? '') === inputId)
     : undefined
 
   let id = inputId !== '' ? inputId : `mcp-${input.serverName}`
   if (existing === undefined) {
-    const taken = new Set(
-      (seq.items ?? []).map(item => String(item.get('id') ?? '')).filter(id => id !== ''),
-    )
+    const taken = takenIds(doc)
     let suffix = 2
     while (taken.has(id)) id = `mcp-${input.serverName}-${suffix++}`
   }
@@ -143,8 +221,14 @@ export function upsertMcp(profileDirPath: string, input: McpInput): string {
   if (input.disabled === true) row.disabled = true
 
   const node = toNode<YAMLMap>(row)
-  if (existing === undefined) seq.add(node)
-  else seq.items[seq.items.indexOf(existing)] = node
+  if (existing === undefined) {
+    list.add(node)
+  } else if (existing.list !== undefined) {
+    existing.list.items.splice(existing.list.items.indexOf(existing.node), 1, node)
+  } else {
+    // Bare rows were absorbed above; reaching here means a foreign-shaped row.
+    rowSeq(doc).items.splice(rowSeq(doc).items.indexOf(existing.node), 1, node)
+  }
 
   savePatch(profileDirPath, doc)
   return id
@@ -153,10 +237,11 @@ export function upsertMcp(profileDirPath: string, input: McpInput): string {
 /** Flip one row's disabled flag (absent = enabled). Returns false when missing. */
 export function setMcpDisabled(profileDirPath: string, id: string, disabled: boolean): boolean {
   const doc = loadPatch(profileDirPath)
-  const item = mcpRows(doc).find(row => row.get('id') === id)
-  if (item === undefined) return false
-  if (disabled) item.set('disabled', true)
-  else item.delete('disabled')
+  managedInsert(doc)
+  const hit = mcpRowItems(doc).find(({ node }) => String(node.get('id') ?? '') === id)
+  if (hit === undefined) return false
+  if (disabled) hit.node.set('disabled', true)
+  else hit.node.delete('disabled')
   savePatch(profileDirPath, doc)
   return true
 }
@@ -164,10 +249,19 @@ export function setMcpDisabled(profileDirPath: string, id: string, disabled: boo
 /** Remove one server row. Returns false when missing. */
 export function removeMcp(profileDirPath: string, id: string): boolean {
   const doc = loadPatch(profileDirPath)
-  const item = mcpRows(doc).find(row => row.get('id') === id)
-  if (item === undefined) return false
+  managedInsert(doc)
+  const hit = mcpRowItems(doc).find(({ node }) => String(node.get('id') ?? '') === id)
+  if (hit === undefined || hit.list === undefined) return false
+  hit.list.items.splice(hit.list.items.indexOf(hit.node), 1)
+
+  // An insert entry left with no rows is dead weight; drop it when the
+  // insert list is all it holds.
   const seq = rowSeq(doc)
-  seq.items.splice(seq.items.indexOf(item), 1)
+  const owner = (seq.items ?? []).find(item => insertListOf(item) === hit.list)
+  if (owner !== undefined && hit.list.items.length === 0 && owner.items.length === 1) {
+    seq.items.splice(seq.items.indexOf(owner), 1)
+  }
+
   savePatch(profileDirPath, doc)
   return true
 }

package/src/restart.test.ts

@@ -0,0 +1,52 @@
+import type { IncomingMessage } from 'node:http'
+import { resolve } from 'node:path'
+import { describe, expect, it } from 'vitest'
+import { dshLaunch, restartOwnedByShell, trustedRestartRequest } from './restart.ts'
+
+describe('dshLaunch', () => {
+  it('replays an absolute bin entry with execArgv, runtime args, and cwd beside it', () => {
+    const launch = dshLaunch(
+      ['node', '/repo/apps/cli/src/bin.ts', 'web', '--port', '0'],
+      ['--expose-internals', '--import', 'tsx/esm'],
+    )
+    expect(launch.file).toBe(process.execPath)
+    expect(launch.args).toEqual(['--expose-internals', '--import', 'tsx/esm', resolve('/repo/apps/cli/src/bin.ts'), 'web', '--port', '0'])
+    expect(launch.cwd).toBe(resolve('/repo/apps/cli/src'))
+    expect(launch.viaShell).toBe(false)
+  })
+  it('resolves a relative source entry to an absolute path', () => {
+    const launch = dshLaunch(['node', 'apps/cli/src/bin.js'], [])
+    expect(launch.args[0]).toMatch(/^(?:[A-Za-z]:)?[\\/]/)
+    expect(launch.cwd).toBe(launch.args[0].replace(/[\\/]bin\.js$/, ''))
+  })
+  it('falls back to the bare dsh shim for unknown entries, keeping runtime args', () => {
+    expect(dshLaunch(['node', '/somewhere/server.js', 'web'])).toMatchObject({ file: 'dsh', args: ['web'], viaShell: process.platform === 'win32' })
+    expect(dshLaunch(['node'])).toMatchObject({ file: 'dsh', args: [] })
+  })
+})
+
+const request = (headers: Record<string, string | undefined>, address = '127.0.0.1'): IncomingMessage =>
+  ({ headers, socket: { remoteAddress: address } }) as unknown as IncomingMessage
+
+describe('trustedRestartRequest', () => {
+  it('accepts a direct same-origin loopback request', () => {
+    expect(trustedRestartRequest(request({ origin: 'http://127.0.0.1:8080', host: '127.0.0.1:8080' }))).toBe(true)
+  })
+  it('rejects non-loopback peers and proxy forwarding traces', () => {
+    expect(trustedRestartRequest(request({ origin: 'http://127.0.0.1:8080', host: '127.0.0.1:8080' }, '192.168.1.5'))).toBe(false)
+    expect(trustedRestartRequest(request({ origin: 'http://127.0.0.1:8080', host: '127.0.0.1:8080', 'x-forwarded-for': '1.2.3.4' }))).toBe(false)
+  })
+  it('rejects cross-origin or missing origin/host', () => {
+    expect(trustedRestartRequest(request({ origin: 'http://evil.example', host: '127.0.0.1:8080' }))).toBe(false)
+    expect(trustedRestartRequest(request({ host: '127.0.0.1:8080' }))).toBe(false)
+    expect(trustedRestartRequest(request({ origin: 'http://127.0.0.1:8080' }))).toBe(false)
+  })
+})
+
+describe('restartOwnedByShell', () => {
+  it('is true only under the desktop marker', () => {
+    expect(restartOwnedByShell({ DSH_DESKTOP: '1' })).toBe(true)
+    expect(restartOwnedByShell({ DSH_DESKTOP: '' })).toBe(false)
+    expect(restartOwnedByShell({})).toBe(false)
+  })
+})

package/src/restart.ts

@@ -0,0 +1,94 @@
+/**
+ * Self-restart for standalone `dsh web`: relaunch the exact invocation that
+ * booted this host, then stop this process — so MCP row changes compose
+ * without leaving the UI. The desktop shell owns restarts there
+ * (DSH_DESKTOP=1 refuses this path — a supervised sidecar must never
+ * replace itself, or the supervisor respawns a second process).
+ *
+ * The replacement is spawned directly with windowsHide: CREATE_NO_WINDOW
+ * gives it a hidden console its own console children inherit (no popping
+ * windows), unlike a DETACHED_PROCESS spawn which leaves children to create
+ * visible consoles. No helper process and no powershell wrapper — on at
+ * least one machine a node→node→powershell→node chain was silently blocked
+ * by host software before the inner node could even start, while direct
+ * node→node spawns are the most battle-tested pattern there is.
+ */
+
+import { spawn } from 'node:child_process'
+import { openSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, resolve } from 'node:path'
+import type { IncomingMessage } from 'node:http'
+
+/** The boot invocation to replay: entry from argv, execArgv preserved. */
+export function dshLaunch(argv: readonly string[] = process.argv, execArgv: readonly string[] = process.execArgv): {
+  file: string
+  args: string[]
+  cwd: string | undefined
+  viaShell: boolean
+} {
+  const entry = argv[1]
+  if (entry !== undefined && /[\\/](?:bin\.(?:js|ts)|dsh)$/.test(entry)) {
+    // Source launches (`pnpm dsh`) pass a relative entry that the child would
+    // resolve against its OWN cwd — absolutize, and keep cwd near the entry
+    // so execArgv module hooks (tsx/esm) stay resolvable.
+    const abs = resolve(entry)
+    return { file: process.execPath, args: [...execArgv, abs, ...argv.slice(2)], cwd: dirname(abs), viaShell: false }
+  }
+  // Bare `dsh` on Windows is a .cmd shim only a shell can start.
+  return { file: 'dsh', args: [...argv.slice(2)], cwd: undefined, viaShell: process.platform === 'win32' }
+}
+
+/**
+ * Relaunch this exact dsh invocation, then stop this process. The replacement
+ * boots slowly (module loading) while this process dies within 500 ms, so
+ * port handover needs no delay even for fixed-port launches. Replacement
+ * output is logged under tmpdir for post-mortem.
+ */
+export function scheduleRestart(launch: ReturnType<typeof dshLaunch>): {
+  pid: number
+  replacementPid: number | undefined
+  logOut: string
+  logErr: string
+} {
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19)
+  const logOut = `${tmpdir()}${tmpdir().endsWith('/') ? '' : '\\'}dsh-plugin-capabilities-restart-${stamp}.out.log`
+  const logErr = logOut.replace('.out.log', '.err.log')
+  const child = spawn(launch.file, launch.args, {
+    cwd: launch.cwd,
+    stdio: ['ignore', openSync(logOut, 'a'), openSync(logErr, 'a')],
+    env: process.env,
+    shell: launch.viaShell,
+    windowsHide: true,
+  })
+  child.unref()
+  setTimeout(() => process.kill(process.pid, 'SIGTERM'), 500)
+  return { pid: process.pid, replacementPid: child.pid, logOut, logErr }
+}
+
+/**
+ * A restart request is process control: only a direct same-origin loopback
+ * request qualifies. Any forwarding trace means the loopback peer is a
+ * proxy, not the user's browser.
+ */
+export function trustedRestartRequest(request: IncomingMessage, socketAddress?: string): boolean {
+  const address = socketAddress ?? (request.socket.remoteAddress ?? '')
+  if (address !== '127.0.0.1' && address !== '::1' && address !== '::ffff:127.0.0.1') return false
+  if (request.headers.forwarded !== undefined
+    || request.headers['x-forwarded-for'] !== undefined
+    || request.headers['x-real-ip'] !== undefined) return false
+  const origin = request.headers.origin
+  const host = request.headers.host
+  if (origin === undefined || host === undefined) return false
+  try {
+    const parsed = new URL(origin)
+    return (parsed.protocol === 'http:' || parsed.protocol === 'https:') && parsed.host === host
+  } catch {
+    return false
+  }
+}
+
+/** Restart ownership: the desktop shell supervises the sidecar and restarts it. */
+export function restartOwnedByShell(env: NodeJS.ProcessEnv = process.env): boolean {
+  return env.DSH_DESKTOP === '1'
+}

package/src/routes.ts

@@ -3,6 +3,7 @@
 import type { IncomingMessage, ServerResponse } from 'node:http'
 import { scanAllMcp } from './agents.ts'
 import { readJsonBody, sameOrigin, sendJson } from './http.ts'
+import { dshLaunch, restartOwnedByShell, scheduleRestart, trustedRestartRequest } from './restart.ts'
 import { deleteSkill, validateSkillInput, writeSkill, type SkillInput } from './skills.ts'
 import { listMcp, removeMcp, setMcpDisabled, upsertMcp, validateMcpInput, type McpInput } from './mcp.ts'
 import type { CapabilitiesHost } from './types.ts'
@@ -279,6 +280,29 @@ export function mountCapabilitiesRoutes(host: CapabilitiesHost, config: { profil
         }
       },
     }),
+
+    host.webServer.register({
+      kind: 'exact',
+      path: '/dsh-plugin-capabilities/restart',
+      handler: (request: IncomingMessage, response: ServerResponse) => {
+        if (request.method !== 'POST') {
+          response.writeHead(405, { allow: 'POST' })
+          response.end()
+          return
+        }
+        // 进程控制：仅直接的同源回环请求；桌面模式下重启归壳层所有。
+        if (!trustedRestartRequest(request)) {
+          sendJson(response, 403, { error: 'untrusted origin' })
+          return
+        }
+        if (restartOwnedByShell()) {
+          sendJson(response, 409, { error: 'restart is owned by the desktop shell' })
+          return
+        }
+        const { pid, replacementPid, logOut } = scheduleRestart(dshLaunch())
+        sendJson(response, 200, { ok: true, pid, replacementPid, logOut })
+      },
+    }),
   ]
 
   return () => { for (const dispose of disposers) dispose() }