@miphamai/cli 0.81.6 → 0.81.8

package/README.md

@@ -1,6 +1,6 @@
-# Mipham Code v0.5.9
+# Mipham Code v0.81.7
 
-**Multi-model open-core intelligent coding terminal** — 9 AI providers, 66 commands, 16 tools, 14 skills + marketplace, self-update. AI-assisted code generation, security auditing, MCP protocol, and extensible skills — in a single CLI.
+**Multi-model open-core intelligent coding terminal** — 12 AI providers, 137 commands, 31 tools, 28 skills + marketplace, self-update. AI-assisted code generation, security auditing, MCP protocol, and extensible skills — in a single CLI.
 
 Built by [One Mipham Corporation](https://onemipham.com) (北京华安麦逄科技有限公司) | Brand: MiphamAI
 
@@ -15,13 +15,13 @@ Requirements: **Bun 1.2+** (recommended) or **Node.js 22+**
 
 ## Features
 
-- **9 AI Providers** — Anthropic Claude · OpenAI GPT · DeepSeek · Kimi (Moonshot) · Google Gemini · Doubao 豆包 · Tencent Hunyuan 混元 · Qwen 通义千问 · MiphamAI
-- **66 Slash Commands** — Interactive command picker (↑↓ Enter Esc), intuitive command interface, zero re-learning
-- **16 Built-in Tools** — File ops, shell execution, agent dispatch, MCP integration, web search
-- **14 Skills + Marketplace** — 11 standard + 3 Mipham-exclusive skills. `/browse-skills` `/install-skill` community marketplace
+- **12 AI Providers** — Anthropic Claude · OpenAI GPT · DeepSeek · Kimi (Moonshot) · Google Gemini · Doubao 豆包 · Tencent Hunyuan 混元 · Qwen 通义千问 · MiniMax（国内 / 国际）· Ollama（本地）· MiphamAI
+- **137 Slash Commands** — Interactive command picker (↑↓ Enter Esc), intuitive command interface, zero re-learning
+- **31 Built-in Tools** — File ops, shell execution, agent dispatch, MCP integration, web search
+- **28 Skills + Marketplace** — 22 standard + 6 Mipham-exclusive skills. `/browse-skills` `/install-skill` community marketplace
 - **Self-Update** — `mipham update` / `/upgrade` — one command to check, backup config, upgrade, restore. API keys preserved
 - **Smart Recommendations** — `/recommend` analyzes your project, suggests skills, providers, and config
-- **One-Click Config** — `/init` generates config.yml with all 9 providers pre-populated (just replace API keys)
+- **One-Click Config** — `/init` generates config.yml with the providers pre-populated (just replace API keys)
 - **MCP Protocol** — Full JSON-RPC 2.0 stdio transport for external server integration
 - **Security Hardened** — Path sandbox · SSRF protection · Bash blacklist · Permission gating · Parameter validation · command injection prevention · API key redaction
 - **Config Resilience** — YAML error recovery, deep merge providers, auto-backup (5 copies), corruption auto-restore
@@ -34,7 +34,7 @@ Requirements: **Bun 1.2+** (recommended) or **Node.js 22+**
 mipham
 
 # First run auto-initializes config. Or:
-/init     # Generate ~/.mipham/config.yml with 9 providers pre-configured
+/init     # Generate ~/.mipham/config.yml with providers pre-configured
 
 # Set API keys (env vars or config.yml)
 export DEEPSEEK_API_KEY="sk-..."
@@ -73,7 +73,7 @@ Press **Ctrl+P** for model picker · **Shift+Tab** to cycle permission mode · *
 - [Website (International)](https://mipham.ai/mipham-code)
 - [国内站](https://onemipham.com/mipham-code)
 - [GitHub](https://github.com/One-Mipham/mipham-code)
-- [Product Specification](https://github.com/One-Mipham/mipham-code/blob/main/PRODUCT.md)
+- [Product Specification (v1.0.0, 2026-06-10 snapshot)](https://github.com/One-Mipham/mipham-code/blob/main/PRODUCT.md) — frozen, not current
 - [npm](https://www.npmjs.com/package/@miphamai/cli)
 
 ## License

package/bin/daemon.ts

@@ -1,40 +1,15 @@
 #!/usr/bin/env bun
 
 /**
- * Mipham Code Daemon — standalone background process.
- * Spawned by `mipham daemon start`.
+ * Mipham Code Daemon — standalone source-mode entry.
+ *
+ * The compiled binary reaches the same code through the hidden `__daemon`
+ * branch in bin/mipham.ts. Both call runDaemonProcess() so there is exactly
+ * one implementation of the daemon process body.
  *
  * Usage: bun run bin/daemon.ts [--port PORT] [--bind HOST]
  */
 
-import { startDaemon } from '../src/daemon/index'
-
-const args = process.argv.slice(2)
-
-// Parse --port and --bind from CLI args (passed by mipham CLI)
-for (let i = 0; i < args.length; i++) {
-  if (args[i] === '--port' && args[i + 1]) {
-    process.env.MIPHAM_PORT = args[i + 1]!
-  }
-  if (args[i] === '--bind' && args[i + 1]) {
-    process.env.MIPHAM_BIND = args[i + 1]!
-  }
-}
-
-const { port } = await startDaemon()
-
-console.log(`Daemon running on http://127.0.0.1:${port}`)
-console.log(`PID: ${process.pid}`)
-
-// Keep process alive
-process.on('SIGTERM', async () => {
-  const { stopDaemon } = await import('../src/daemon/index')
-  await stopDaemon(true)
-  process.exit(0)
-})
+import { runDaemonProcess } from '../src/daemon/launch'
 
-process.on('SIGINT', async () => {
-  const { stopDaemon } = await import('../src/daemon/index')
-  await stopDaemon(true)
-  process.exit(0)
-})
+await runDaemonProcess()

package/bin/mipham.ts

@@ -6,6 +6,8 @@
 
 export {} // ensure module scope (prevents global name collisions)
 
+import { DAEMON_ENTRY, userArgs } from '../src/daemon/launch'
+
 async function runWorkflowCLI(): Promise<boolean> {
   const args = process.argv.slice(2)
   if (args[0] !== 'workflow') return false
@@ -324,8 +326,6 @@ async function runDaemonCLI(): Promise<boolean> {
 
   const subcmd = args[1]
 
-  const { spawn } = await import('node:child_process')
-
   if (subcmd === 'start') {
     const { getDaemonStatus } = await import('../src/daemon/index')
     const status = getDaemonStatus()
@@ -335,23 +335,13 @@ async function runDaemonCLI(): Promise<boolean> {
     }
 
     console.log('Starting daemon...')
-    const daemonScript = new URL('./daemon.ts', import.meta.url).pathname
-    const child = spawn('bun', ['run', daemonScript], {
-      detached: true,
-      stdio: 'ignore',
-      env: { ...process.env },
-    })
-    child.unref()
-
-    // Wait briefly for daemon to write PID/port files
-    await new Promise((resolve) => setTimeout(resolve, 1000))
-
-    const newStatus = getDaemonStatus()
-    if (newStatus) {
-      console.log(`Daemon started (PID: ${newStatus.pid}, Port: ${newStatus.port})`)
-    } else {
-      console.log('Daemon started (PID unknown — check `mipham daemon status`)')
+    const { startDetachedDaemon } = await import('../src/daemon/launch')
+    const launch = await startDetachedDaemon()
+    if (!launch.ok) {
+      console.error(`Failed to start daemon: ${launch.reason}`)
+      process.exit(1)
     }
+    console.log(`Daemon started (PID: ${launch.pid}, Port: ${launch.port})`)
     process.exit(0)
   }
 
@@ -387,6 +377,7 @@ async function runDaemonCLI(): Promise<boolean> {
 
   if (subcmd === 'restart') {
     const { getDaemonStatus } = await import('../src/daemon/index')
+    const { startDetachedDaemon, waitForDaemonExit } = await import('../src/daemon/launch')
     const status = getDaemonStatus()
     if (status) {
       try {
@@ -394,18 +385,28 @@ async function runDaemonCLI(): Promise<boolean> {
       } catch {
         // Process may have already exited
       }
-      await new Promise((resolve) => setTimeout(resolve, 500))
+      // A fixed sleep here is a guess, and the guess is load-bearing:
+      // startDetachedDaemon() opens by probing getStatus(), so a pid file the old
+      // daemon has not unlinked yet reads as "already running" — restart would
+      // then report success for a start it never performed. Wait for the old
+      // daemon to be *gone*; if it never goes, refuse instead of starting blind.
+      const waitStarted = Date.now()
+      const gone = await waitForDaemonExit()
+      if (!gone) {
+        const waitedMs = Date.now() - waitStarted
+        console.error(
+          `Refusing to restart: old daemon (PID: ${status.pid}) is still running after ${waitedMs}ms`,
+        )
+        process.exit(1)
+      }
     }
 
-    const daemonScript = new URL('./daemon.ts', import.meta.url).pathname
-    const child = spawn('bun', ['run', daemonScript], {
-      detached: true,
-      stdio: 'ignore',
-      env: { ...process.env },
-    })
-    child.unref()
-    await new Promise((resolve) => setTimeout(resolve, 1000))
-    console.log('Daemon restarted.')
+    const launch = await startDetachedDaemon()
+    if (!launch.ok) {
+      console.error(`Failed to restart daemon: ${launch.reason}`)
+      process.exit(1)
+    }
+    console.log(`Daemon restarted (PID: ${launch.pid}, Port: ${launch.port})`)
     process.exit(0)
   }
 
@@ -1095,6 +1096,19 @@ async function runInitCLI(): Promise<boolean> {
 }
 
 async function main() {
+  // ── Hidden daemon entry ────────────────────────────────────────────────
+  // `daemon start` re-execs this same program with `__daemon` (see
+  // src/daemon/launch.ts). This must come first: everything below assumes an
+  // interactive TTY — the stty block would run against a detached child whose
+  // stdio is the daemon log. The sentinel is stripped here because the two
+  // entry points have different argv shapes (see runDaemonProcess).
+  const argv = userArgs(process.argv)
+  if (argv[0] === DAEMON_ENTRY) {
+    const { runDaemonProcess } = await import('../src/daemon/launch')
+    await runDaemonProcess(argv.slice(1))
+    return
+  }
+
   // ── Deleted-cwd guard ──────────────────────────────────────────────────
   // `process.cwd()` throws ENOENT when the directory the process was launched
   // from no longer exists (e.g. a removed git worktree). Print a clear message
@@ -1309,4 +1323,4 @@ Docs: https://onemipham.com/mipham-code
   }
 }
 
-main()
+void main()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miphamai/cli",
-  "version": "0.81.6",
+  "version": "0.81.8",
   "description": "Mipham Code — Multi-model open-core intelligent coding terminal by MiphamAI",
   "keywords": [
     "ai",
@@ -40,7 +40,8 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "knip": "knip --production --no-progress --no-exit-code",
-    "coverage": "vitest run --coverage --coverage.provider=v8 --coverage.include='src/**/*.{ts,tsx}' --coverage.reporter=text-summary --coverage.reporter=json-summary"
+    "coverage": "vitest run --coverage",
+    "mutate": "stryker run"
   },
   "dependencies": {
     "@larksuiteoapi/node-sdk": "^1.73.0",
@@ -53,6 +54,8 @@
   },
   "devDependencies": {
     "@mipham/shared": "workspace:*",
+    "@stryker-mutator/core": "10.0.0",
+    "@stryker-mutator/vitest-runner": "10.0.0",
     "@types/bun": "^1.4.2",
     "@types/node": "^22.19.19",
     "@types/react": "^19.3.0",

package/skills/standard/mipham-code-setup.SKILL.md

@@ -286,10 +286,10 @@ providers:
 
 ### 5.1 — Built-in Skills
 
-Mipham Code ships with 17 built-in skills loaded automatically:
+Mipham Code ships with 28 built-in skills loaded automatically:
 
-- **Standard (14)**: code-review, compassionate-communication, doc-generator, github-ops, memory, mipham-code-setup, security-review, self-review, superpower, systematic-debugging, tdd, test-driven-development, web-access, web-search
-- **Mipham (3)**: om-artifact, om-model-optimize, om-security
+- **Standard (22)**: code-review, codebase-design, compassionate-communication, debug-loop, doc-generator, domain-modeling, github-ops, grill-with-docs, implement, memory, mipham-code-setup, research, safe-coding, security-review, self-review, superpower, tdd, to-spec, triage, trim-process-prose, web-access, web-search
+- **Mipham (6)**: doc-sync, om-artifact, om-model-optimize, om-security, save-to-wiki, self-audit
 
 ### 5.2 — Community Skills
 

package/src/agent/sub-agent.ts

@@ -10,6 +10,7 @@ import type { PermissionSystem } from '../core/permission'
 import { AgentExperience } from './agent-experience'
 import { PatternAnalyzer } from './pattern-analyzer.js'
 import { getWorkspaceTrust } from '../core/workspace-trust'
+import { recordToolCall } from '../telemetry/index'
 import type { ExperienceRuleEngine } from '../core/rule-engine.js'
 
 // Singleton instances (created lazily)
@@ -85,7 +86,7 @@ export class SubAgent {
       // Register completion callback for hook firing
       bgRegistry.onComplete(taskId, (task) => {
         if (this.hookEngine) {
-          this.hookEngine.executeSubagentStop(
+          void this.hookEngine.executeSubagentStop(
             agentType,
             description,
             taskId,
@@ -397,6 +398,15 @@ export class SubAgent {
             throw new DOMException('Aborted', 'AbortError')
           }
 
+          // Counted here, at dispatch, mirroring `Engine.executeTool`'s entry
+          // increment — this loop bypasses `executeTool` entirely and
+          // reimplements the hook/permission steps itself, so without this line
+          // every tool call made inside a sub-agent (and therefore inside a
+          // workflow, which derives sub-agents) is invisible to the metrics
+          // registry. Same failure shape as the two "one of two paths wired"
+          // bugs this repo has already recorded.
+          recordToolCall(tu.name)
+
           const tool = this.toolRegistry.get(tu.name)
           if (!tool) {
             currentMessages.push({
@@ -490,6 +500,7 @@ export class SubAgent {
                   content: displayResult.success
                     ? displayResult.content
                     : displayResult.error || displayResult.content,
+                  ...(displayResult.success ? {} : { is_error: true }),
                 },
               ],
             })

package/src/artifacts/manifest.ts

@@ -1,47 +1,95 @@
-import {
-  readFileSync,
-  writeFileSync,
-  existsSync,
-  mkdirSync,
-  renameSync,
-  copyFileSync,
-  unlinkSync,
-} from 'node:fs'
+import { readFileSync, existsSync, mkdirSync, renameSync, copyFileSync, unlinkSync } from 'node:fs'
 import { join } from 'node:path'
+import { atomicWriteFileSync } from '../shared/atomic-write'
 import type { ArtifactManifest, ArtifactEntry } from '../shared/types'
 
+function emptyManifest(): ArtifactManifest {
+  return { version: 1, artifacts: [] }
+}
+
 /**
  * Read the artifact manifest from disk, or return an empty one if it doesn't exist.
+ *
+ * An unreadable index also yields an empty manifest — the callers here only *show*
+ * artifacts (gallery, `/artifact list`), and showing none beats throwing at them.
+ * Writers must not go through this path: see `readManifestForUpdate`.
  */
 export function readManifest(dir: string): ArtifactManifest {
   const path = join(dir, 'index.json')
   if (!existsSync(path)) {
-    return { version: 1, artifacts: [] }
+    return emptyManifest()
   }
   try {
     return JSON.parse(readFileSync(path, 'utf-8'))
   } catch {
-    return { version: 1, artifacts: [] }
+    return emptyManifest()
+  }
+}
+
+/**
+ * Read the manifest for a caller that is about to write it back.
+ *
+ * The difference from `readManifest` is what happens when the file exists but does
+ * not parse: a writer must not treat that as "empty", because writing back an
+ * empty manifest replaces every other artifact's entry with nothing — the files
+ * stay on disk, but the gallery and `/artifact list` lose them. So the unreadable
+ * file is renamed aside (bytes kept, recoverable by hand) and reported, and the
+ * caller decides what to tell the user.
+ */
+function readManifestForUpdate(dir: string): {
+  manifest: ArtifactManifest
+  quarantined?: string
+} {
+  const path = join(dir, 'index.json')
+  if (!existsSync(path)) return { manifest: emptyManifest() }
+  try {
+    return { manifest: JSON.parse(readFileSync(path, 'utf-8')) }
+  } catch {
+    const quarantined = `${path}.corrupt-${new Date().toISOString().replace(/[:.]/g, '-')}`
+    // If this rename fails we let it throw: the alternative is overwriting the
+    // only copy of the index with a manifest built from nothing.
+    renameSync(path, quarantined)
+    return { manifest: emptyManifest(), quarantined }
   }
 }
 
 /**
  * Write the manifest to disk, creating parent directories as needed.
+ *
+ * Atomic: a crash mid-write used to leave a truncated `index.json`, which is
+ * exactly the corruption `readManifestForUpdate` then has to quarantine.
  */
 export function writeManifest(dir: string, manifest: ArtifactManifest): void {
   mkdirSync(dir, { recursive: true })
-  writeFileSync(join(dir, 'index.json'), JSON.stringify(manifest, null, 2), 'utf-8')
+  atomicWriteFileSync(join(dir, 'index.json'), JSON.stringify(manifest, null, 2), {
+    mode: 0o644,
+  })
 }
 
 /**
  * Add an entry to the manifest and persist it.
- * If an entry with the same name already exists, it is replaced.
+ *
+ * An entry is identified by `name` **and** `sessionId`, matching how the tool
+ * looks one up: the manifest is a single global `index.json` holding every
+ * session's artifacts, so keying on the name alone made two sessions publishing
+ * the same name overwrite each other's entry — the loser's file stayed on disk
+ * but vanished from the index.
+ *
+ * Returns the written manifest plus, when the previous index was unreadable, the
+ * path its bytes were moved to — the caller is expected to say so rather than
+ * let an artifact appear to publish cleanly over a lost index.
  */
-export function addToManifest(dir: string, entry: ArtifactEntry, port?: number): ArtifactManifest {
-  const manifest = readManifest(dir)
+export function addToManifest(
+  dir: string,
+  entry: ArtifactEntry,
+  port?: number,
+): { manifest: ArtifactManifest; quarantined?: string } {
+  const { manifest, quarantined } = readManifestForUpdate(dir)
   if (port !== undefined) manifest.port = port
 
-  const idx = manifest.artifacts.findIndex((a) => a.name === entry.name)
+  const idx = manifest.artifacts.findIndex(
+    (a) => a.name === entry.name && a.sessionId === entry.sessionId,
+  )
   if (idx >= 0) {
     manifest.artifacts[idx] = entry
   } else {
@@ -49,7 +97,7 @@ export function addToManifest(dir: string, entry: ArtifactEntry, port?: number):
   }
 
   writeManifest(dir, manifest)
-  return manifest
+  return { manifest, quarantined }
 }
 
 /**
@@ -64,31 +112,39 @@ export function getSessionArtifacts(dir: string, sessionId: string): ArtifactEnt
  * Archive an existing artifact file by renaming it with a version tag.
  * e.g. dashboard.html → dashboard.v1.html, dashboard.v1.html → dashboard.v2.html.
  *
- * Returns the version tag assigned to the archived file.
+ * Returns the version tag assigned to the archived file, or `undefined` when
+ * there was nothing to archive — in which case the manifest is left untouched.
+ *
+ * 「没归档就什么都不记」是刻意的：源文件找不到时照样推进版本号、往 `versions` 里
+ * 塞一个标签，等于在 manifest 里留一版磁盘上并不存在的版本。走到那条路并不难
+ * —— 条目按 name 找、文件按 `<session>/<name><ext>` 找，把同一个名字从 html 改
+ * 成 svg 就错开了。宁可少记一版，也不能记一版假的。
  */
-export function archiveVersion(dir: string, entry: ArtifactEntry): string {
-  const manifest = readManifest(dir)
-  const versionCount = (entry.versionCount || 1) + 1
+export function archiveVersion(dir: string, entry: ArtifactEntry): string | undefined {
   const ext = entry.type === 'svg' ? '.svg' : '.html'
-  const versionTag = `v${versionCount}`
-
-  // Rename the current file to a versioned copy
   const baseName = entry.name
   const currentPath = join(dir, entry.sessionId, `${baseName}${ext}`)
+
+  if (!existsSync(currentPath)) return undefined
+
+  const versionCount = (entry.versionCount || 1) + 1
+  const versionTag = `v${versionCount}`
   const archivedPath = join(dir, entry.sessionId, `${baseName}.${versionTag}${ext}`)
 
-  if (existsSync(currentPath)) {
-    try {
-      renameSync(currentPath, archivedPath)
-    } catch {
-      // If rename fails (e.g. cross-device), copy instead
-      copyFileSync(currentPath, archivedPath)
-      unlinkSync(currentPath)
-    }
+  try {
+    renameSync(currentPath, archivedPath)
+  } catch {
+    // If rename fails (e.g. cross-device), copy instead
+    copyFileSync(currentPath, archivedPath)
+    unlinkSync(currentPath)
   }
 
-  // Update manifest entry
-  const artifact = manifest.artifacts.find((a) => a.name === entry.name)
+  // Update manifest entry — keyed on name *and* session, like every other
+  // lookup here: a same-named artifact in another session is a different one.
+  const manifest = readManifest(dir)
+  const artifact = manifest.artifacts.find(
+    (a) => a.name === entry.name && a.sessionId === entry.sessionId,
+  )
   if (artifact) {
     const versions = artifact.versions || ['v1']
     versions.push(versionTag)

package/src/artifacts/paths.ts

@@ -0,0 +1,19 @@
+import { join } from 'node:path'
+import { ARTIFACTS_DIR, MIPHAM_DIR } from '../shared/constants'
+
+/**
+ * The one place that decides *where on disk an artifact lives*.
+ *
+ * Three sites need to agree on this: the Artifact tool (writes the file and the
+ * manifest), the ArtifactServer (serves files and builds the gallery from the
+ * manifest rooted here), and `/artifact list` (reads the manifest). Each of them
+ * computing the path itself is what produced the original bug: the tool wrote
+ * `<cwd>/artifacts/...` while the server served `<cwd>/.mipham/artifacts/...`,
+ * so the URL the tool reported was a guaranteed 404 — the two halves never met.
+ *
+ * Keeping them joined here means a change moves all three together; the guard
+ * test asserts the *behaviour* (the reported URL resolves), not the literal.
+ */
+export function artifactsRoot(cwd: string): string {
+  return join(cwd, MIPHAM_DIR, ARTIFACTS_DIR)
+}

package/src/artifacts/server.ts

@@ -1,9 +1,9 @@
 import { createServer, type Server } from 'node:http'
-import { createReadStream, existsSync, statSync } from 'node:fs'
+import type { Socket } from 'node:net'
+import { createReadStream, existsSync, readFileSync, statSync } from 'node:fs'
 import { join, normalize, extname } from 'node:path'
 import { ARTIFACT_ALLOWED_EXTENSIONS } from '../shared/constants'
 import { readManifest } from './manifest'
-import { ArtifactVersioning } from './versioning'
 import type { ArtifactEntry } from '../shared/types'
 import { getMetrics } from '../core/metrics'
 
@@ -29,12 +29,11 @@ export class ArtifactServer {
   private started = false
   private sseClients: SseClient[] = []
   private sseIdCounter = 0
-  private versioning: ArtifactVersioning
+  private sockets = new Set<Socket>()
 
   constructor(artifactsDir: string, preferredPort: number) {
     this.artifactsDir = artifactsDir
     this.port = preferredPort
-    this.versioning = new ArtifactVersioning(artifactsDir)
   }
 
   /** Notify all connected SSE clients to reload. Called after artifact changes. */
@@ -82,6 +81,12 @@ export class ArtifactServer {
       this.server = null
       this.started = false
     }
+
+    // `close()` only stops *accepting* — sockets already established (a browser's
+    // keep-alive, an SSE stream) stay open and keep being served, so a "stopped"
+    // server answers on the old port until the client hangs up. Destroy them.
+    for (const socket of this.sockets) socket.destroy()
+    this.sockets.clear()
   }
 
   getPort(): number {
@@ -114,6 +119,10 @@ export class ArtifactServer {
       const srv = createServer((req, res) => {
         this.handleRequest(req, res)
       })
+      srv.on('connection', (socket) => {
+        this.sockets.add(socket)
+        socket.on('close', () => this.sockets.delete(socket))
+      })
       srv.on('error', reject)
       srv.listen(port, () => {
         this.server = srv
@@ -216,8 +225,31 @@ export class ArtifactServer {
     })
   }
 
-  /** Per-artifact SSE stream: pushes content updates to connected browsers every 500ms. */
+  /**
+   * Per-artifact SSE stream: pushes the artifact's content to connected browsers
+   * every 500ms, so a page can follow an artifact the AI rewrites in place.
+   *
+   * Resolves the file through `resolveFile` — the same coordinate the gallery
+   * links to and the same traversal guard the static path uses — and 404s when no
+   * artifact carries that name, instead of holding a stream open on a file that
+   * does not exist.
+   */
   private handleNameSse(name: string, res: any): void {
+    const entry = readManifest(this.artifactsDir).artifacts.find((a) => a.name === name)
+    if (!entry) {
+      res.writeHead(404, { 'Content-Type': 'text/plain' })
+      res.end(`No artifact named "${name}"`)
+      return
+    }
+
+    const ext = entry.type === 'svg' ? '.svg' : '.html'
+    const { filePath, error, status } = this.resolveFile(`/${entry.sessionId}/${entry.name}${ext}`)
+    if (error) {
+      res.writeHead(status || 404, { 'Content-Type': 'text/plain' })
+      res.end(error)
+      return
+    }
+
     res.writeHead(200, {
       'Content-Type': 'text/event-stream',
       'Cache-Control': 'no-cache',
@@ -225,10 +257,18 @@ export class ArtifactServer {
       'Access-Control-Allow-Origin': '*',
     })
 
+    let last: string | null = null
     const interval = setInterval(() => {
-      const content = this.versioning.getVersion(name)
-      if (content) {
-        res.write(`data: ${JSON.stringify({ type: 'update', name, content })}\n\n`)
+      try {
+        const content = readFileSync(filePath, 'utf-8')
+        // Only on change: without this the stream re-sends the whole file every
+        // 500ms per client for as long as the tab stays open.
+        if (content !== last) {
+          last = content
+          res.write(`data: ${JSON.stringify({ type: 'update', name, content })}\n\n`)
+        }
+      } catch {
+        // Momentarily absent (archiving renames it) — skip this tick, try the next.
       }
     }, 500)