@brainjar/cli 0.5.1 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brainjar/cli",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "Shape how your AI thinks — composable soul, persona, and rules for AI agents",
   "type": "module",
   "license": "MIT",

package/src/api-types.ts

@@ -63,7 +63,7 @@ export interface ApiEffectiveState {
   rules: string[]
 }
 
-/** State override at a single scope, returned by GET /api/v1/state/override. */
+/** State override at a single scope. */
 export interface ApiStateOverride {
   soul_slug?: string | null
   persona_slug?: string | null
@@ -72,6 +72,12 @@ export interface ApiStateOverride {
   rules_to_remove?: string[]
 }
 
+/** Envelope returned by GET /api/v1/state/override. */
+export interface ApiStateOverrideResponse {
+  override: ApiStateOverride | null
+  scope: { id: string; scope_type: string; reference_id: string; parent_scope_id?: string } | null
+}
+
 /** Body for PUT /api/v1/state — partial update. */
 export interface ApiStateMutation {
   soul_slug?: string | null

package/src/client.ts

@@ -19,7 +19,8 @@ export interface ClientOptions {
 export interface RequestOptions {
   timeout?: number
   headers?: Record<string, string>
-  project?: string
+  /** Pass a project name to scope to that project, null to suppress auto-detection, or undefined for auto-detect. */
+  project?: string | null
 }
 
 export interface BrainjarClient {
@@ -40,7 +41,8 @@ const ERROR_MAP: Record<number, { code: ErrorCode; hint?: string }> = {
   503: { code: ErrorCode.SERVER_UNAVAILABLE, hint: 'Server is not ready. Try again in a moment.' },
 }
 
-async function detectProject(explicit?: string): Promise<string | null> {
+async function detectProject(explicit?: string | null): Promise<string | null> {
+  if (explicit === null) return null // explicitly suppress auto-detection
   if (explicit) return explicit
   try {
     await access(getLocalDir())
@@ -72,7 +74,8 @@ export async function createClient(options?: ClientOptions): Promise<BrainjarCli
       ...(reqOpts?.headers ?? {}),
     }
 
-    const project = await detectProject(reqOpts?.project ?? options?.project)
+    const explicitProject = reqOpts && 'project' in reqOpts ? reqOpts.project : options?.project
+    const project = await detectProject(explicitProject)
     if (project) headers['X-Brainjar-Project'] = project
     if (session) headers['X-Brainjar-Session'] = session
 

package/src/commands/brain.ts

@@ -160,7 +160,26 @@ export const brain = Cli.create('brain', {
     },
   })
   .command('drop', {
-    description: 'Delete a brain',
+    description: 'Deactivate the current brain — clears soul, persona, and rules',
+    options: z.object({
+      project: z.boolean().default(false).describe('Remove project brain override or deactivate workspace brain'),
+    }),
+    async run(c) {
+      const api = await getApi()
+
+      const mutationOpts = c.options.project
+        ? { project: basename(process.cwd()) }
+        : undefined
+      await putState(api, { soul_slug: '', persona_slug: '', rule_slugs: [] }, mutationOpts)
+
+      await sync({ api })
+      if (c.options.project) await sync({ api, project: true })
+
+      return { deactivated: true, project: c.options.project }
+    },
+  })
+  .command('delete', {
+    description: 'Delete a brain permanently',
     args: z.object({
       name: z.string().describe('Brain name to delete'),
     }),
@@ -177,6 +196,6 @@ export const brain = Cli.create('brain', {
         throw e
       }
 
-      return { dropped: name }
+      return { deleted: name }
     },
   })

package/src/commands/persona.ts

@@ -3,7 +3,7 @@ import { basename } from 'node:path'
 
 const { IncurError } = Errors
 import { ErrorCode, createError } from '../errors.js'
-import { normalizeSlug, getEffectiveState, putState } from '../state.js'
+import { normalizeSlug, getEffectiveState, getStateOverride, putState } from '../state.js'
 import { sync } from '../sync.js'
 import { getApi } from '../client.js'
 import type { ApiPersona, ApiPersonaList, ApiRuleList } from '../api-types.js'
@@ -17,6 +17,7 @@ export const persona = Cli.create('persona', {
       name: z.string().describe('Persona name'),
     }),
     options: z.object({
+      content: z.string().optional().describe('Persona content (if omitted, creates with a starter template you can edit)'),
       description: z.string().optional().describe('One-line description of the persona'),
       rules: z.array(z.string()).optional().describe('Rules to bundle with this persona'),
     }),
@@ -50,24 +51,29 @@ export const persona = Cli.create('persona', {
 
       const effectiveRules = rulesList
 
-      const lines: string[] = []
-      lines.push(`# ${name}`)
-      lines.push('')
-      if (c.options.description) {
-        lines.push(c.options.description)
+      let content: string
+      if (c.options.content) {
+        content = c.options.content.trim()
+      } else {
+        const lines: string[] = []
+        lines.push(`# ${name}`)
+        lines.push('')
+        if (c.options.description) {
+          lines.push(c.options.description)
+        }
+        lines.push('')
+        lines.push('## Direct mode')
+        lines.push('- ')
+        lines.push('')
+        lines.push('## Subagent mode')
+        lines.push('- ')
+        lines.push('')
+        lines.push('## Always')
+        lines.push('- ')
+        lines.push('')
+        content = lines.join('\n')
       }
-      lines.push('')
-      lines.push('## Direct mode')
-      lines.push('- ')
-      lines.push('')
-      lines.push('## Subagent mode')
-      lines.push('- ')
-      lines.push('')
-      lines.push('## Always')
-      lines.push('- ')
-      lines.push('')
 
-      const content = lines.join('\n')
       await api.put<ApiPersona>(`/api/v1/personas/${name}`, {
         content,
         bundled_rules: effectiveRules,
@@ -87,11 +93,12 @@ export const persona = Cli.create('persona', {
     },
   })
   .command('update', {
-    description: 'Update a persona\'s content (reads from stdin)',
+    description: 'Update a persona\'s content (reads from stdin or --content)',
     args: z.object({
       name: z.string().describe('Persona name'),
     }),
     options: z.object({
+      content: z.string().optional().describe('Persona content (reads from stdin if omitted)'),
       rules: z.array(z.string()).optional().describe('Update bundled rules'),
     }),
     async run(c) {
@@ -109,11 +116,14 @@ export const persona = Cli.create('persona', {
         throw e
       }
 
-      const chunks: Uint8Array[] = []
-      for await (const chunk of Bun.stdin.stream()) {
-        chunks.push(chunk)
+      let content = c.options.content?.trim()
+      if (!content) {
+        const chunks: Uint8Array[] = []
+        for await (const chunk of Bun.stdin.stream()) {
+          chunks.push(chunk)
+        }
+        content = Buffer.concat(chunks).toString().trim()
       }
-      const content = Buffer.concat(chunks).toString().trim()
 
       // Validate rules if provided
       const rulesList = c.options.rules
@@ -181,7 +191,7 @@ export const persona = Cli.create('persona', {
       }
 
       if (c.options.project) {
-        const state = await api.get<import('../api-types.js').ApiStateOverride>('/api/v1/state/override', {
+        const state = await getStateOverride(api, {
           project: basename(process.cwd()),
         })
         if (state.persona_slug === undefined) return { active: false, scope: 'project', note: 'No project persona override (cascades from workspace)' }
@@ -245,6 +255,31 @@ export const persona = Cli.create('persona', {
       return result
     },
   })
+  .command('delete', {
+    description: 'Delete a persona permanently',
+    args: z.object({
+      name: z.string().describe('Persona name to delete'),
+    }),
+    async run(c) {
+      const name = normalizeSlug(c.args.name, 'persona name')
+      const api = await getApi()
+
+      try {
+        await api.delete(`/api/v1/personas/${name}`)
+      } catch (e) {
+        if (e instanceof IncurError && e.code === ErrorCode.NOT_FOUND) {
+          throw createError(ErrorCode.PERSONA_NOT_FOUND, { params: [name] })
+        }
+        throw e
+      }
+
+      // If this persona was active, sync to reflect removal
+      const state = await getEffectiveState(api)
+      if (state.persona === name) await sync({ api })
+
+      return { deleted: name }
+    },
+  })
   .command('drop', {
     description: 'Deactivate the current persona',
     options: z.object({
@@ -256,7 +291,7 @@ export const persona = Cli.create('persona', {
       const mutationOpts = c.options.project
         ? { project: basename(process.cwd()) }
         : undefined
-      await putState(api, { persona_slug: null }, mutationOpts)
+      await putState(api, { persona_slug: '' }, mutationOpts)
 
       await sync({ api })
       if (c.options.project) await sync({ api, project: true })

package/src/commands/rules.ts

@@ -3,7 +3,7 @@ import { basename } from 'node:path'
 
 const { IncurError } = Errors
 import { ErrorCode, createError } from '../errors.js'
-import { normalizeSlug, getEffectiveState, putState } from '../state.js'
+import { normalizeSlug, getEffectiveState, getStateOverride, putState } from '../state.js'
 import { sync } from '../sync.js'
 import { getApi } from '../client.js'
 import type { ApiRule, ApiRuleList } from '../api-types.js'
@@ -17,6 +17,7 @@ export const rules = Cli.create('rules', {
       name: z.string().describe('Rule name'),
     }),
     options: z.object({
+      content: z.string().optional().describe('Rule content (if omitted, creates with a starter template you can edit)'),
       description: z.string().optional().describe('One-line description of the rule'),
     }),
     async run(c) {
@@ -32,15 +33,20 @@ export const rules = Cli.create('rules', {
         if (e instanceof IncurError && e.code !== ErrorCode.NOT_FOUND) throw e
       }
 
-      const scaffold = [
-        `# ${name}`,
-        '',
-        c.options.description ?? 'Describe what this rule enforces and why.',
-        '',
-        '## Constraints',
-        '- ',
-        '',
-      ].join('\n')
+      let scaffold: string
+      if (c.options.content) {
+        scaffold = c.options.content.trim()
+      } else {
+        scaffold = [
+          `# ${name}`,
+          '',
+          c.options.description ?? 'Describe what this rule enforces and why.',
+          '',
+          '## Constraints',
+          '- ',
+          '',
+        ].join('\n')
+      }
 
       await api.put<ApiRule>(`/api/v1/rules/${name}`, {
         entries: [{ name: `${name}.md`, content: scaffold }],
@@ -59,10 +65,13 @@ export const rules = Cli.create('rules', {
     },
   })
   .command('update', {
-    description: 'Update a rule\'s content (reads from stdin)',
+    description: 'Update a rule\'s content (reads from stdin or --content)',
     args: z.object({
       name: z.string().describe('Rule name'),
     }),
+    options: z.object({
+      content: z.string().optional().describe('Rule content (reads from stdin if omitted)'),
+    }),
     async run(c) {
       const name = normalizeSlug(c.args.name, 'rule name')
       const api = await getApi()
@@ -77,11 +86,14 @@ export const rules = Cli.create('rules', {
         throw e
       }
 
-      const chunks: Uint8Array[] = []
-      for await (const chunk of Bun.stdin.stream()) {
-        chunks.push(chunk)
+      let content = c.options.content?.trim()
+      if (!content) {
+        const chunks: Uint8Array[] = []
+        for await (const chunk of Bun.stdin.stream()) {
+          chunks.push(chunk)
+        }
+        content = Buffer.concat(chunks).toString().trim()
       }
-      const content = Buffer.concat(chunks).toString().trim()
 
       if (!content) {
         throw createError(ErrorCode.MISSING_ARG, {
@@ -112,7 +124,7 @@ export const rules = Cli.create('rules', {
       const availableSlugs = available.rules.map(r => r.slug)
 
       if (c.options.project) {
-        const override = await api.get<import('../api-types.js').ApiStateOverride>('/api/v1/state/override', {
+        const override = await getStateOverride(api, {
           project: basename(process.cwd()),
         })
         return {
@@ -182,13 +194,38 @@ export const rules = Cli.create('rules', {
       return { activated: name, project: c.options.project }
     },
   })
-  .command('remove', {
+  .command('delete', {
+    description: 'Delete a rule permanently',
+    args: z.object({
+      name: z.string().describe('Rule name to delete'),
+    }),
+    async run(c) {
+      const name = normalizeSlug(c.args.name, 'rule name')
+      const api = await getApi()
+
+      try {
+        await api.delete(`/api/v1/rules/${name}`)
+      } catch (e) {
+        if (e instanceof IncurError && e.code === ErrorCode.NOT_FOUND) {
+          throw createError(ErrorCode.RULE_NOT_FOUND, { params: [name] })
+        }
+        throw e
+      }
+
+      // If this rule was active, sync to reflect removal
+      const state = await getEffectiveState(api)
+      if (state.rules.includes(name)) await sync({ api })
+
+      return { deleted: name }
+    },
+  })
+  .command('drop', {
     description: 'Deactivate a rule',
     args: z.object({
-      name: z.string().describe('Rule name to remove'),
+      name: z.string().describe('Rule name to deactivate'),
     }),
     options: z.object({
-      project: z.boolean().default(false).describe('Remove rule at project scope'),
+      project: z.boolean().default(false).describe('Deactivate rule at project scope'),
     }),
     async run(c) {
       const name = normalizeSlug(c.args.name, 'rule name')

package/src/commands/soul.ts

@@ -3,7 +3,7 @@ import { basename } from 'node:path'
 
 const { IncurError } = Errors
 import { ErrorCode, createError } from '../errors.js'
-import { normalizeSlug, getEffectiveState, putState } from '../state.js'
+import { normalizeSlug, getEffectiveState, getStateOverride, putState } from '../state.js'
 import { sync } from '../sync.js'
 import { getApi } from '../client.js'
 import type { ApiSoul, ApiSoulList } from '../api-types.js'
@@ -17,6 +17,7 @@ export const soul = Cli.create('soul', {
       name: z.string().describe('Soul name'),
     }),
     options: z.object({
+      content: z.string().optional().describe('Soul content (if omitted, creates with a starter template you can edit)'),
       description: z.string().optional().describe('One-line description of the soul'),
     }),
     async run(c) {
@@ -32,24 +33,29 @@ export const soul = Cli.create('soul', {
         if (e instanceof IncurError && e.code !== ErrorCode.NOT_FOUND) throw e
       }
 
-      const lines: string[] = []
-      lines.push(`# ${name}`)
-      lines.push('')
-      if (c.options.description) {
-        lines.push(c.options.description)
+      let content: string
+      if (c.options.content) {
+        content = c.options.content.trim()
+      } else {
+        const lines: string[] = []
+        lines.push(`# ${name}`)
         lines.push('')
+        if (c.options.description) {
+          lines.push(c.options.description)
+          lines.push('')
+        }
+        lines.push('## Voice')
+        lines.push('- ')
+        lines.push('')
+        lines.push('## Character')
+        lines.push('- ')
+        lines.push('')
+        lines.push('## Standards')
+        lines.push('- ')
+        lines.push('')
+        content = lines.join('\n')
       }
-      lines.push('## Voice')
-      lines.push('- ')
-      lines.push('')
-      lines.push('## Character')
-      lines.push('- ')
-      lines.push('')
-      lines.push('## Standards')
-      lines.push('- ')
-      lines.push('')
-
-      const content = lines.join('\n')
+
       await api.put<ApiSoul>(`/api/v1/souls/${name}`, { content })
 
       if (c.agent || c.formatExplicit) {
@@ -65,10 +71,13 @@ export const soul = Cli.create('soul', {
     },
   })
   .command('update', {
-    description: 'Update a soul\'s content (reads from stdin)',
+    description: 'Update a soul\'s content (reads from stdin or --content)',
     args: z.object({
       name: z.string().describe('Soul name'),
     }),
+    options: z.object({
+      content: z.string().optional().describe('Soul content (reads from stdin if omitted)'),
+    }),
     async run(c) {
       const name = normalizeSlug(c.args.name, 'soul name')
       const api = await getApi()
@@ -83,11 +92,14 @@ export const soul = Cli.create('soul', {
         throw e
       }
 
-      const chunks: Uint8Array[] = []
-      for await (const chunk of Bun.stdin.stream()) {
-        chunks.push(chunk)
+      let content = c.options.content?.trim()
+      if (!content) {
+        const chunks: Uint8Array[] = []
+        for await (const chunk of Bun.stdin.stream()) {
+          chunks.push(chunk)
+        }
+        content = Buffer.concat(chunks).toString().trim()
       }
-      const content = Buffer.concat(chunks).toString().trim()
 
       if (!content) {
         throw createError(ErrorCode.MISSING_ARG, {
@@ -145,7 +157,7 @@ export const soul = Cli.create('soul', {
       }
 
       if (c.options.project) {
-        const state = await api.get<import('../api-types.js').ApiStateOverride>('/api/v1/state/override', {
+        const state = await getStateOverride(api, {
           project: basename(process.cwd()),
         })
         if (state.soul_slug === undefined) return { active: false, scope: 'project', note: 'No project soul override (cascades from workspace)' }
@@ -201,6 +213,31 @@ export const soul = Cli.create('soul', {
       return { activated: name, project: c.options.project }
     },
   })
+  .command('delete', {
+    description: 'Delete a soul permanently',
+    args: z.object({
+      name: z.string().describe('Soul name to delete'),
+    }),
+    async run(c) {
+      const name = normalizeSlug(c.args.name, 'soul name')
+      const api = await getApi()
+
+      try {
+        await api.delete(`/api/v1/souls/${name}`)
+      } catch (e) {
+        if (e instanceof IncurError && e.code === ErrorCode.NOT_FOUND) {
+          throw createError(ErrorCode.SOUL_NOT_FOUND, { params: [name] })
+        }
+        throw e
+      }
+
+      // If this soul was active, sync to reflect removal
+      const state = await getEffectiveState(api)
+      if (state.soul === name) await sync({ api })
+
+      return { deleted: name }
+    },
+  })
   .command('drop', {
     description: 'Deactivate the current soul',
     options: z.object({
@@ -212,7 +249,7 @@ export const soul = Cli.create('soul', {
       const mutationOpts = c.options.project
         ? { project: basename(process.cwd()) }
         : undefined
-      await putState(api, { soul_slug: null }, mutationOpts)
+      await putState(api, { soul_slug: '' }, mutationOpts)
 
       await sync({ api })
       if (c.options.project) await sync({ api, project: true })

package/src/commands/status.ts

@@ -1,9 +1,8 @@
 import { Cli, z } from 'incur'
 import { basename } from 'node:path'
-import { getEffectiveState } from '../state.js'
+import { getEffectiveState, getStateOverride } from '../state.js'
 import { sync } from '../sync.js'
 import { getApi } from '../client.js'
-import type { ApiStateOverride } from '../api-types.js'
 
 export const status = Cli.create('status', {
   description: 'Show active brain configuration',
@@ -35,11 +34,11 @@ export const status = Cli.create('status', {
 
     // --workspace: show only workspace-level override
     if (c.options.workspace) {
-      const override = await api.get<ApiStateOverride>('/api/v1/state/override')
+      const override = await getStateOverride(api, { project: null })
       const result: Record<string, unknown> = {
         soul: override.soul_slug ?? null,
         persona: override.persona_slug ?? null,
-        rules: override.rule_slugs ?? [],
+        rules: override.rules_to_add ?? [],
       }
       if (synced) result.synced = synced
       return result
@@ -47,7 +46,7 @@ export const status = Cli.create('status', {
 
     // --project: show only project-level overrides
     if (c.options.project) {
-      const override = await api.get<ApiStateOverride>('/api/v1/state/override', {
+      const override = await getStateOverride(api, {
         project: basename(process.cwd()),
       })
       const result: Record<string, unknown> = {}

package/src/daemon.ts

@@ -1,6 +1,6 @@
 import { spawn, execFileSync } from 'node:child_process'
 import { createHash } from 'node:crypto'
-import { readFile, writeFile, rm, access, open, chmod, mkdir } from 'node:fs/promises'
+import { readFile, writeFile, rm, access, open, chmod, mkdir, constants } from 'node:fs/promises'
 import { dirname, join } from 'node:path'
 import { tmpdir } from 'node:os'
 import { Errors } from 'incur'
@@ -8,6 +8,7 @@ import { readConfig, activeContext, localContext } from './config.js'
 import { ErrorCode, createError } from './errors.js'
 
 export const DIST_BASE = 'https://get.brainjar.sh/brainjar-server'
+export const SEMVER_RE = /^v?\d+\.\d+\.\d+(-[a-zA-Z0-9]+(\.[a-zA-Z0-9]+)*)?(\+[a-zA-Z0-9.]+)?$/
 
 /**
  * Compare two semver strings. Returns -1, 0, or 1.
@@ -30,7 +31,7 @@ const { IncurError } = Errors
  * Minimum server version this CLI is compatible with.
  * Bump when the CLI depends on server features/API changes.
  */
-export const MIN_SERVER_VERSION = '0.2.2'
+export const MIN_SERVER_VERSION = '0.2.4'
 
 export interface HealthStatus {
   healthy: boolean
@@ -156,7 +157,13 @@ export async function fetchLatestVersion(distBase: string = DIST_BASE): Promise<
       hint: 'Check your network connection or try again later.',
     })
   }
-  return (await response.text()).trim()
+  const version = (await response.text()).trim()
+  if (!SEMVER_RE.test(version)) {
+    throw createError(ErrorCode.VALIDATION_ERROR, {
+      message: `Invalid server version string from distribution: "${version}"`,
+    })
+  }
+  return version
 }
 
 /**
@@ -268,6 +275,12 @@ export async function upgradeServer(): Promise<{ version: string; alreadyLatest:
     return { version, alreadyLatest: true }
   }
 
+  // Stop server before replacing binary to avoid ETXTBSY on Linux
+  const pid = await readPid(localContext(config).pid_file)
+  if (pid !== null && isAlive(pid)) {
+    await stop()
+  }
+
   const versionBase = `${DIST_BASE}/${version}`
   await downloadAndVerify(binPath, versionBase)
   await setInstalledServerVersion(version)
@@ -397,9 +410,25 @@ export async function readLogFile(options?: { lines?: number }): Promise<string>
   }
 }
 
+/**
+ * Try to acquire an exclusive lock file. Returns a release function on success, null if already locked.
+ */
+async function tryLock(lockFile: string): Promise<(() => Promise<void>) | null> {
+  try {
+    const fd = await open(lockFile, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY)
+    await fd.write(String(process.pid))
+    await fd.close()
+    return async () => { await rm(lockFile, { force: true }) }
+  } catch (e) {
+    if ((e as NodeJS.ErrnoException).code === 'EEXIST') return null
+    throw e
+  }
+}
+
 /**
  * Ensure the server is running and healthy.
  * Called by commands before making API calls.
+ * Uses a file lock to prevent parallel CLI invocations from spawning multiple server processes.
  */
 export async function ensureRunning(): Promise<void> {
   const config = await readConfig()
@@ -420,20 +449,31 @@ export async function ensureRunning(): Promise<void> {
     })
   }
 
-  // Local mode: auto-start
-  await cleanStalePid(local.pid_file)
+  // Local mode: auto-start with file lock to prevent races
+  const lockFile = `${local.pid_file}.lock`
+  const release = await tryLock(lockFile)
 
-  try {
-    await start()
-  } catch (e) {
-    if (e instanceof IncurError) throw e
-    throw createError(ErrorCode.SERVER_START_FAILED, {
-      message: 'Failed to start brainjar server.',
-      hint: `Check ${local.log_file}`,
-    })
+  if (release) {
+    // We hold the lock — we're responsible for starting
+    try {
+      await cleanStalePid(local.pid_file)
+
+      try {
+        await start()
+      } catch (e) {
+        if (e instanceof IncurError) throw e
+        throw createError(ErrorCode.SERVER_START_FAILED, {
+          message: 'Failed to start brainjar server.',
+          hint: `Check ${local.log_file}`,
+        })
+      }
+    } finally {
+      await release()
+    }
   }
 
   // Poll until healthy (200ms intervals, 10s timeout)
+  // Both the lock holder and waiters converge here
   const deadline = Date.now() + 10_000
   while (Date.now() < deadline) {
     await new Promise(r => setTimeout(r, 200))

package/src/pack.ts

@@ -1,5 +1,5 @@
 import { readFile, readdir, writeFile, access, mkdir, stat } from 'node:fs/promises'
-import { join, dirname } from 'node:path'
+import { join, dirname, basename } from 'node:path'
 import { parse as parseYaml, stringify as stringifyYaml } from 'yaml'
 import { Errors } from 'incur'
 import { ErrorCode, createError } from './errors.js'
@@ -127,7 +127,13 @@ export async function exportPack(brainName: string, options: ExportOptions = {})
       const ruleDir = join(packDir, 'rules', ruleSlug)
       await mkdir(ruleDir, { recursive: true })
       for (const entry of rule.entries) {
-        await writeFile(join(ruleDir, entry.name), entry.content)
+        const safeName = basename(entry.name)
+        if (!safeName || safeName !== entry.name) {
+          throw createError(ErrorCode.PACK_INVALID_MANIFEST, {
+            message: `Rule entry name contains invalid path: "${entry.name}"`,
+          })
+        }
+        await writeFile(join(ruleDir, safeName), entry.content)
       }
     }
   }

package/src/state.ts

@@ -1,5 +1,5 @@
-import type { BrainjarClient } from './client.js'
-import type { ApiEffectiveState, ApiStateMutation } from './api-types.js'
+import type { BrainjarClient, RequestOptions } from './client.js'
+import type { ApiEffectiveState, ApiStateMutation, ApiStateOverride, ApiStateOverrideResponse } from './api-types.js'
 
 const SLUG_RE = /^[a-zA-Z0-9_-]+$/
 
@@ -15,8 +15,14 @@ export function normalizeSlug(value: string, label: string): string {
 }
 
 /** Fetch the fully resolved effective state from the server. */
-export async function getEffectiveState(api: BrainjarClient): Promise<ApiEffectiveState> {
-  return api.get<ApiEffectiveState>('/api/v1/state')
+export async function getEffectiveState(api: BrainjarClient, options?: RequestOptions): Promise<ApiEffectiveState> {
+  return api.get<ApiEffectiveState>('/api/v1/state', options)
+}
+
+/** Fetch the raw override at a specific scope, unwrapping the server envelope. */
+export async function getStateOverride(api: BrainjarClient, options?: RequestOptions): Promise<ApiStateOverride> {
+  const resp = await api.get<ApiStateOverrideResponse>('/api/v1/state/override', options)
+  return resp.override ?? {}
 }
 
 /** Mutate state on the server. Pass options.project to scope the mutation to a project. */

package/src/sync.ts

@@ -1,4 +1,5 @@
 import { readFile, writeFile, copyFile, mkdir } from 'node:fs/promises'
+import { basename } from 'node:path'
 import { type Backend, getBackendConfig } from './paths.js'
 import { getEffectiveState } from './state.js'
 import { getApi, type BrainjarClient } from './client.js'
@@ -72,7 +73,7 @@ export async function sync(options?: SyncOptions) {
   const opts = options ?? {}
   const api = opts.api ?? await getApi()
 
-  const state = await getEffectiveState(api)
+  const state = await getEffectiveState(api, opts.project ? { project: basename(process.cwd()) } : undefined)
   const backend: Backend = opts.backend ?? 'claude'
   const config = getBackendConfig(backend, { local: opts.project })
 

package/src/upgrade.ts

@@ -2,14 +2,22 @@ import { execFile } from 'node:child_process'
 import {
   healthCheck,
   start,
-  stop,
   status as daemonStatus,
   upgradeServer,
+  SEMVER_RE,
 } from './daemon.js'
 import { checkForUpdates } from './version-check.js'
 import { ErrorCode, createError } from './errors.js'
 import pkg from '../package.json'
 
+function validateVersion(v: string, label: string): void {
+  if (!SEMVER_RE.test(v)) {
+    throw createError(ErrorCode.VALIDATION_ERROR, {
+      message: `Invalid ${label} version string: "${v}"`,
+    })
+  }
+}
+
 export interface ComponentResult {
   upgraded: boolean
   from: string
@@ -59,6 +67,7 @@ export async function upgradeCli(): Promise<ComponentResult> {
   }
 
   const latestVersion = updates.cli.latest
+  validateVersion(latestVersion, 'CLI')
   const pm = detectPackageManager()
 
   try {
@@ -88,14 +97,10 @@ export async function upgradeServerBinary(): Promise<ServerResult> {
   const { getInstalledServerVersion } = await import('./version-check.js')
   const installedVersion = (await getInstalledServerVersion()) ?? 'unknown'
 
-  // Stop server if running before replacing binary
+  // upgradeServer() stops the server internally before replacing the binary
   const s = await daemonStatus()
   const wasRunning = s.running
 
-  if (wasRunning) {
-    await stop()
-  }
-
   const result = await upgradeServer()
 
   if (result.alreadyLatest) {