@zerwiz/ymir 0.1.34 → 0.1.35

package/apps/sessrumnir/src/main/council-manager.test.ts

@@ -0,0 +1,167 @@
+import assert from 'node:assert/strict'
+import { test } from 'node:test'
+import {
+  buildConsultantSpawn,
+  runConsultants,
+  runArbiter,
+  type SpawnConsultant,
+} from './council-manager'
+import { COUNCIL_AGENT_IDS, buildConsultantCommand } from '../shared/council-config'
+import type { CouncilAgentId, ConsultantResult } from '../shared/council-config'
+
+function fakeSpawn(map: Record<string, { ok: boolean; output?: string; error?: string; timedOut?: boolean }>): SpawnConsultant {
+  return async (id: CouncilAgentId) => {
+    const r = map[id] ?? { ok: false, error: 'unconfigured' }
+    return { ok: r.ok, output: r.output ?? '', error: r.error, timedOut: r.timedOut }
+  }
+}
+
+// --- buildConsultantSpawn: the wire form handed to spawn() on each platform ---
+
+test('buildConsultantSpawn quotes a spaced shim path for the Windows cmd.exe hop', () => {
+  const spawn = buildConsultantSpawn('claude', String.raw`C:\Program Files\nodejs\claude.cmd`, true)
+  assert.equal(spawn.file, String.raw`"C:\Program Files\nodejs\claude.cmd"`)
+  // Every consultant flag is metacharacter-free, so escaping must leave the
+  // args byte-identical — gratuitous quoting would reach the CLI verbatim.
+  assert.deepEqual(spawn.args, [
+    '-p',
+    '--permission-mode',
+    'plan',
+    '--output-format',
+    'stream-json',
+    '--include-partial-messages',
+    '--verbose',
+  ])
+})
+
+test('buildConsultantSpawn escapes cmd metacharacters in a Windows shim path', () => {
+  const spawn = buildConsultantSpawn('pi', String.raw`C:\Users\Tom & Jerry\100%\pi.cmd`, true)
+  assert.equal(spawn.file, String.raw`"C:\Users\Tom & Jerry\100"^%"\pi.cmd"`)
+  assert.deepEqual(spawn.args, [
+    '-p',
+    '--mode',
+    'json',
+    '--no-session',
+    '--exclude-tools',
+    'bash,edit,write',
+  ])
+})
+
+test('buildConsultantSpawn passes every agent through byte-identically off Windows', () => {
+  for (const id of COUNCIL_AGENT_IDS) {
+    const executable = `/usr/local/bin/my agents/${id}`
+    const command = buildConsultantCommand(id, executable)
+    assert.deepEqual(buildConsultantSpawn(id, executable, false), {
+      file: executable,
+      args: command.args,
+    }, id)
+  }
+})
+
+test('arbiter mode: contributed and errored are labeled', async () => {
+  const results = await runConsultants(
+    { request: 'r', members: ['claude', 'codex'], cwd: '/tmp', timeoutSeconds: 1, consensusMode: 'arbiter' },
+    { spawnConsultant: fakeSpawn({ claude: { ok: true, output: 'PLAN A' }, codex: { ok: false, error: 'boom' } }) },
+  )
+  const claude = results.find((r) => r.id === 'claude')!
+  const codex = results.find((r) => r.id === 'codex')!
+  assert.equal(claude.status, 'contributed')
+  assert.equal(claude.plan, 'PLAN A')
+  assert.equal(codex.status, 'errored')
+  assert.equal(codex.error, 'boom')
+})
+
+test('timed-out spawn maps to timed-out status', async () => {
+  const results = await runConsultants(
+    { request: 'r', members: ['claude'], cwd: '/tmp', timeoutSeconds: 1, consensusMode: 'arbiter' },
+    { spawnConsultant: fakeSpawn({ claude: { ok: false, timedOut: true } }) },
+  )
+  assert.equal(results[0].status, 'timed-out')
+})
+
+test('debate mode performs a second spawn round per member', async () => {
+  const calls: Array<{ id: CouncilAgentId; round: number }> = []
+  const spawn: SpawnConsultant = async (id, _prompt, _cwd, _ms) => {
+    const round = calls.filter((c) => c.id === id).length + 1
+    calls.push({ id, round })
+    return { ok: true, output: `PLAN ${id} r${round}` }
+  }
+  const results = await runConsultants(
+    { request: 'r', members: ['claude', 'codex'], cwd: '/tmp', timeoutSeconds: 1, consensusMode: 'debate' },
+    { spawnConsultant: spawn },
+  )
+  assert.equal(calls.length, 4)
+  assert.ok(results.find((r) => r.id === 'claude')!.plan!.includes('r2'))
+})
+
+test('onProgress receives streamed chunks tagged by consultant', async () => {
+  const events: Array<{ id: CouncilAgentId; chunk: string }> = []
+  const spawn: SpawnConsultant = async (id, _prompt, _cwd, _ms, onChunk) => {
+    onChunk?.(`${id}-chunk`)
+    return { ok: true, output: `PLAN ${id}` }
+  }
+  await runConsultants(
+    { request: 'r', members: ['claude', 'codex'], cwd: '/tmp', timeoutSeconds: 1, consensusMode: 'arbiter' },
+    { spawnConsultant: spawn, onProgress: (id, chunk) => events.push({ id, chunk }) },
+  )
+  assert.ok(events.some((e) => e.id === 'claude' && e.chunk === 'claude-chunk'))
+  assert.ok(events.some((e) => e.id === 'codex' && e.chunk === 'codex-chunk'))
+})
+
+test('runArbiter merges via a read-only Pi spawn carrying the consultant plans', async () => {
+  const seen: { id: CouncilAgentId; prompt: string } = { id: 'claude', prompt: '' }
+  const spawn: SpawnConsultant = async (id, prompt) => {
+    seen.id = id
+    seen.prompt = prompt
+    return { ok: true, output: 'MERGED PLAN' }
+  }
+  const results: ConsultantResult[] = [
+    { id: 'claude', status: 'contributed', plan: 'CLAUDE PLAN' },
+    { id: 'codex', status: 'contributed', plan: 'CODEX PLAN' },
+  ]
+  const outcome = await runArbiter(
+    { kind: 'merge', request: 'build it', results },
+    '/tmp',
+    1,
+    { spawnConsultant: spawn },
+  )
+  assert.equal(outcome.ok, true)
+  assert.equal(outcome.output, 'MERGED PLAN')
+  // The arbiter is always Pi (the read-only builder), and the untrusted plans
+  // are embedded into its prompt.
+  assert.equal(seen.id, 'pi')
+  assert.ok(seen.prompt.includes('CLAUDE PLAN'))
+  assert.ok(seen.prompt.includes('CODEX PLAN'))
+})
+
+test('runArbiter revise embeds the prior plan and feedback', async () => {
+  let captured = ''
+  const spawn: SpawnConsultant = async (_id, prompt) => {
+    captured = prompt
+    return { ok: true, output: 'REVISED PLAN' }
+  }
+  const outcome = await runArbiter(
+    { kind: 'revise', request: 'build it', plan: 'PRIOR PLAN', feedback: 'use Postgres' },
+    '/tmp',
+    1,
+    { spawnConsultant: spawn },
+  )
+  assert.equal(outcome.output, 'REVISED PLAN')
+  assert.ok(captured.includes('PRIOR PLAN'))
+  assert.ok(captured.includes('use Postgres'))
+})
+
+test('runArbiter forwards streamed chunks to onProgress', async () => {
+  const chunks: string[] = []
+  const spawn: SpawnConsultant = async (_id, _prompt, _cwd, _ms, onChunk) => {
+    onChunk?.('partial plan')
+    return { ok: true, output: 'DONE' }
+  }
+  await runArbiter(
+    { kind: 'merge', request: 'r', results: [] },
+    '/tmp',
+    1,
+    { spawnConsultant: spawn, onProgress: (chunk) => chunks.push(chunk) },
+  )
+  assert.deepEqual(chunks, ['partial plan'])
+})

package/apps/sessrumnir/src/main/council-manager.ts

@@ -0,0 +1,265 @@
+import { spawn } from 'child_process'
+import { StringDecoder } from 'string_decoder'
+import type { CouncilAgentId, ConsensusMode, ConsultantResult, CouncilPiEngine } from '../shared/council-config'
+import {
+  buildConsultantPrompt,
+  buildConsensusPrompt,
+  buildArbiterRevisionPrompt,
+  buildDebatePrompt,
+  buildConsultantCommand,
+  parseClaudeStreamLine,
+  parseCodexStreamLine,
+  parsePiStreamLine,
+} from '../shared/council-config'
+import { detectAgents } from './agent-detection'
+import { escapeCmdSpawn } from './cmd-escape'
+import { getPiCli } from './pi-rpc-manager'
+import { t } from '../shared/i18n'
+
+const IS_WINDOWS = process.platform === 'win32'
+const MS_PER_SECOND = 1000
+const FORCE_KILL_TIMEOUT_MS = 3000
+
+export interface SpawnOutcome {
+  ok: boolean
+  output: string
+  error?: string
+  timedOut?: boolean
+}
+
+/** Called with each readable text chunk as a consultant produces output. */
+export type ConsultantChunkHandler = (chunk: string) => void
+
+/** Injectable spawn so orchestration is testable without real CLIs. */
+export type SpawnConsultant = (
+  id: CouncilAgentId,
+  prompt: string,
+  cwd: string,
+  timeoutMs: number,
+  onChunk?: ConsultantChunkHandler,
+) => Promise<SpawnOutcome>
+
+export interface RunConsultantsParams {
+  request: string
+  members: CouncilAgentId[]
+  cwd: string
+  timeoutSeconds: number
+  consensusMode: ConsensusMode
+}
+
+export interface ConsultantDeps {
+  spawnConsultant: SpawnConsultant
+  /** Notified with live output chunks per consultant, for streaming to the UI. */
+  onProgress?: (id: CouncilAgentId, chunk: string) => void
+}
+
+const MIN_DEBATE_PARTICIPANTS = 2
+
+/** Map a spawn outcome to a labeled consultant result. */
+function toResult(id: CouncilAgentId, outcome: SpawnOutcome): ConsultantResult {
+  if (outcome.timedOut) return { id, status: 'timed-out' }
+  if (!outcome.ok) return { id, status: 'errored', error: outcome.error ?? t('errors.council.unknownError') }
+  return { id, status: 'contributed', plan: outcome.output.trim() }
+}
+
+/**
+ * Run the consultant fan-out. Arbiter mode = one round. Debate mode = a second
+ * round where each contributing member revises given the others' plans.
+ */
+export async function runConsultants(
+  params: RunConsultantsParams,
+  deps: ConsultantDeps,
+): Promise<ConsultantResult[]> {
+  const timeoutMs = params.timeoutSeconds * MS_PER_SECOND
+  const prompt = buildConsultantPrompt(params.request)
+
+  const forward = (id: CouncilAgentId): ConsultantChunkHandler => (chunk) => deps.onProgress?.(id, chunk)
+
+  const round1 = await Promise.all(
+    params.members.map(async (id) =>
+      toResult(id, await deps.spawnConsultant(id, prompt, params.cwd, timeoutMs, forward(id))),
+    ),
+  )
+
+  if (params.consensusMode !== 'debate') return round1
+
+  const contributed = round1.filter((r) => r.status === 'contributed')
+  if (contributed.length < MIN_DEBATE_PARTICIPANTS) return round1
+
+  const round2 = await Promise.all(
+    round1.map(async (r) => {
+      if (r.status !== 'contributed') return r
+      const others = contributed.filter((o) => o.id !== r.id)
+      const debatePrompt = buildDebatePrompt(params.request, r.id, others)
+      return toResult(r.id, await deps.spawnConsultant(r.id, debatePrompt, params.cwd, timeoutMs, forward(r.id)))
+    }),
+  )
+  return round2
+}
+
+/**
+ * Structured input for the arbiter step. `merge` combines contributed plans;
+ * `revise` reworks an already-produced consensus plan given user feedback.
+ */
+export type ArbiterRequest =
+  | { kind: 'merge'; request: string; results: ConsultantResult[] }
+  | { kind: 'revise'; request: string; plan: string; feedback: string }
+
+export interface ArbiterDeps {
+  spawnConsultant: SpawnConsultant
+  /** Notified with live output chunks from the arbiter, for streaming to the UI. */
+  onProgress?: ConsultantChunkHandler
+}
+
+/**
+ * Run the arbiter (Pi) as an isolated, read-only subprocess to merge or revise
+ * the consensus plan. It runs read-only (via buildConsultantCommand('pi', …),
+ * which excludes edit/write tools) precisely because consultant plans are
+ * untrusted input: a poisoned plan cannot drive tool use here. Only the returned
+ * plan text is later handed to the writable implementation session.
+ */
+export async function runArbiter(
+  input: ArbiterRequest,
+  cwd: string,
+  timeoutSeconds: number,
+  deps: ArbiterDeps,
+): Promise<SpawnOutcome> {
+  const prompt =
+    input.kind === 'merge'
+      ? buildConsensusPrompt(input.request, input.results)
+      : buildArbiterRevisionPrompt(input.request, input.plan, input.feedback)
+  const timeoutMs = timeoutSeconds * MS_PER_SECOND
+  return deps.spawnConsultant('pi', prompt, cwd, timeoutMs, deps.onProgress)
+}
+
+/**
+ * The exact program and argv handed to spawn() for one consultant.
+ *
+ * The prompt is delivered over stdin, never as a CLI argument. On Windows the
+ * args pass through cmd.exe (shell:true is required to launch the `.cmd`
+ * shims), so untrusted plan text on the command line would be open to
+ * shell-metacharacter injection. All three CLIs read the prompt from stdin.
+ * Node performs no quoting with shell:true, so the executable path (which may
+ * contain spaces or cmd metacharacters via the user profile directory) and the
+ * flags are escaped for the cmd.exe traversal on Windows.
+ */
+export function buildConsultantSpawn(
+  id: CouncilAgentId,
+  executable: string,
+  isWindows: boolean,
+  engine: CouncilPiEngine = 'pi',
+): { file: string; args: string[] } {
+  const command = buildConsultantCommand(id, executable, engine)
+  return escapeCmdSpawn(isWindows, command.file, command.args)
+}
+
+/** Default spawn: run the consultant CLI, stream output, enforce timeout. */
+export const defaultSpawnConsultant: SpawnConsultant = (id, prompt, cwd, timeoutMs, onChunk) =>
+  new Promise<SpawnOutcome>((resolve) => {
+    const piCli = id === 'pi' ? getPiCli() : null
+    const { file, args } = buildConsultantSpawn(
+      id,
+      resolveExecutable(id),
+      IS_WINDOWS,
+      piCli?.kind === 'omp' ? 'omp' : 'pi',
+    )
+    const child = spawn(file, args, {
+      cwd,
+      shell: IS_WINDOWS,
+      windowsHide: true,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    })
+    // Ignore EPIPE if the child exits before consuming stdin; write then close
+    // so the CLI sees a complete prompt and does not block waiting for more.
+    child.stdin?.on('error', () => {})
+    child.stdin?.end(prompt)
+    const outDecoder = new StringDecoder('utf8')
+    const errDecoder = new StringDecoder('utf8')
+    let stdout = ''
+    let stderr = ''
+    let settled = false
+
+    // Both CLIs emit JSONL: Claude via --output-format stream-json, Codex via
+    // --json. We parse each line into readable text — streaming live via onChunk
+    // and accumulating the plan separately from activity/reasoning noise.
+    const isClaude = id === 'claude'
+    let lineBuffer = ''
+    let planText = ''
+    let claudeFinal: string | undefined
+
+    const applyLine = (line: string): void => {
+      if (isClaude) {
+        const { delta, final } = parseClaudeStreamLine(line)
+        if (delta) {
+          planText += delta
+          onChunk?.(delta)
+        }
+        if (typeof final === 'string') claudeFinal = final
+      } else {
+        // Pi streams thinking as token deltas (append raw); Codex emits whole
+        // reasoning items (separate with a newline).
+        const isPi = id === 'pi'
+        const { plan, display } = isPi ? parsePiStreamLine(line) : parseCodexStreamLine(line)
+        if (typeof plan === 'string') {
+          planText += plan
+          onChunk?.(plan)
+        } else if (typeof display === 'string') {
+          // Reasoning/activity: show live but keep it out of the final plan.
+          onChunk?.(isPi ? display : display + '\n')
+        }
+      }
+    }
+
+    const consume = (text: string): void => {
+      lineBuffer += text
+      let nl: number
+      while ((nl = lineBuffer.indexOf('\n')) !== -1) {
+        applyLine(lineBuffer.slice(0, nl))
+        lineBuffer = lineBuffer.slice(nl + 1)
+      }
+    }
+
+    const finish = (outcome: SpawnOutcome): void => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      resolve(outcome)
+    }
+
+    const timer = setTimeout(() => {
+      child.kill('SIGTERM')
+      setTimeout(() => child.kill('SIGKILL'), FORCE_KILL_TIMEOUT_MS)
+      finish({ ok: false, output: planText, timedOut: true })
+    }, timeoutMs)
+
+    child.stdout?.on('data', (d: Buffer) => {
+      const text = outDecoder.write(d)
+      stdout += text
+      consume(text)
+    })
+    child.stderr?.on('data', (d: Buffer) => { stderr += errDecoder.write(d) })
+    child.on('error', (err) => finish({ ok: false, output: stdout, error: err.message }))
+    child.on('close', (code) => {
+      if (lineBuffer) applyLine(lineBuffer)
+      if (code === 0) {
+        // Prefer the parsed plan; fall back to raw stdout if parsing yielded nothing.
+        const output = (claudeFinal ?? planText) || stdout
+        finish({ ok: true, output })
+      } else {
+        // Some CLIs (e.g. Claude on an auth failure) print the real reason to
+        // stdout, not stderr. Surface stdout as the error when stderr is empty so
+        // the consultant card shows something actionable instead of "exit code N".
+        finish({ ok: false, output: stdout, error: stderr.trim() || stdout.trim() || `exit code ${code}` })
+      }
+    })
+  })
+
+// Resolve the executable path from agent detection; falls back to the bare id.
+function resolveExecutable(id: CouncilAgentId): string {
+  if (id === 'pi') {
+    const configured = getPiCli()
+    if (configured.found) return configured.script
+  }
+  const found = detectAgents().find((a) => a.id === id)
+  return found?.path ?? id
+}

package/apps/sessrumnir/src/main/diagnostics-report.test.ts

@@ -0,0 +1,140 @@
+import assert from 'node:assert/strict'
+import { test } from 'node:test'
+import {
+  classifyProviderKey,
+  countPathEntries,
+  extractVersionLine,
+  reportModelsReadFailure,
+  reportPiStartFailure,
+  summarizeProviders,
+} from './diagnostics-report'
+import { describePiStartFailure, PI_FALLBACK_BINARY_POSIX, type PiStartFailure } from './pi-binary-resolution'
+import type { ModelsConfig } from '../shared/ipc-contracts'
+import { PSEUDO_LANGUAGE, SOURCE_LANGUAGE } from '../shared/i18n/languages'
+
+test('classifyProviderKey covers literal, env, shell, and missing keys', () => {
+  const env = { OPENAI_KEY: 'sk-real', EMPTY_KEY: '' }
+  assert.deepEqual(classifyProviderKey('sk-abc123', env), { keyState: 'literal' })
+  assert.deepEqual(classifyProviderKey('$OPENAI_KEY', env), { keyState: 'env-set', envVar: 'OPENAI_KEY' })
+  assert.deepEqual(classifyProviderKey('$MISSING_KEY', env), { keyState: 'env-missing', envVar: 'MISSING_KEY' })
+  assert.deepEqual(classifyProviderKey('$EMPTY_KEY', env), { keyState: 'env-missing', envVar: 'EMPTY_KEY' })
+  assert.deepEqual(classifyProviderKey('!op read secret', env), { keyState: 'shell' })
+  assert.deepEqual(classifyProviderKey(undefined, env), { keyState: 'none' })
+  assert.deepEqual(classifyProviderKey('   ', env), { keyState: 'none' })
+  assert.deepEqual(classifyProviderKey(42, env), { keyState: 'none' })
+})
+
+test('summarizeProviders counts models and classifies each provider', () => {
+  const config: ModelsConfig = {
+    providers: {
+      openai: { apiKey: '$OPENAI_KEY', models: [{ id: 'gpt-5' }, { id: 'gpt-5-mini' }] },
+      local: { baseUrl: 'http://localhost:11434' },
+    },
+  }
+  const rows = summarizeProviders(config, { OPENAI_KEY: 'x' })
+  assert.deepEqual(rows, [
+    { name: 'openai', modelCount: 2, keyState: 'env-set', envVar: 'OPENAI_KEY' },
+    { name: 'local', modelCount: 0, keyState: 'none' },
+  ])
+})
+
+test('summarizeProviders tolerates null and non-object provider entries', () => {
+  const config = {
+    providers: { broken: null, alsoBroken: 'oops', ok: { apiKey: 'sk-x' } },
+  } as unknown as ModelsConfig
+  assert.deepEqual(summarizeProviders(config, {}), [
+    { name: 'broken', modelCount: 0, keyState: 'none' },
+    { name: 'alsoBroken', modelCount: 0, keyState: 'none' },
+    { name: 'ok', modelCount: 0, keyState: 'literal' },
+  ])
+})
+
+test('extractVersionLine takes the first non-empty line', () => {
+  assert.equal(extractVersionLine('0.31.0\n'), '0.31.0')
+  assert.equal(extractVersionLine('\n  pi 0.31.0 \nextra noise'), 'pi 0.31.0')
+  assert.equal(extractVersionLine('   '), null)
+  assert.equal(extractVersionLine(''), null)
+})
+
+test('reportModelsReadFailure withholds parse detail that can quote file content', () => {
+  assert.equal(
+    reportModelsReadFailure('models.json', {
+      kind: 'invalid-syntax',
+      format: 'json',
+      detail: 'Unexpected token s, ..."apiKey": sk-live-ab"...',
+    }),
+    'models.json is not valid JSON',
+  )
+  assert.equal(
+    reportModelsReadFailure('models.yml', {
+      kind: 'invalid-syntax',
+      format: 'yaml',
+      detail: 'Nested mappings are not allowed at line 3:\n\n    apiKey: sk-live-abcdef: oops\n            ^',
+    }),
+    'models.yml is not valid YAML',
+  )
+})
+
+test('reportModelsReadFailure keeps safe detail', () => {
+  assert.equal(
+    reportModelsReadFailure('models.json', { kind: 'missing-providers' }),
+    'models.json is not a valid models config (missing "providers")',
+  )
+  assert.equal(
+    reportModelsReadFailure('models.json', { kind: 'unreadable', detail: 'EACCES: permission denied' }),
+    'Could not read models.json: EACCES: permission denied',
+  )
+})
+
+test('reportModelsReadFailure does not depend on the interface language', async () => {
+  const { i18n } = await import('../shared/i18n')
+  await i18n.changeLanguage(PSEUDO_LANGUAGE)
+  try {
+    assert.equal(
+      reportModelsReadFailure('models.json', { kind: 'invalid-syntax', format: 'json', detail: 'apiKey: sk-live' }),
+      'models.json is not valid JSON',
+    )
+  } finally {
+    await i18n.changeLanguage(SOURCE_LANGUAGE)
+  }
+})
+
+test('reportPiStartFailure stays English under the pseudo-language', async () => {
+  const { i18n, t } = await import('../shared/i18n')
+  const notFound: PiStartFailure = {
+    kind: 'pi-not-found',
+    resolution: {
+      script: PI_FALLBACK_BINARY_POSIX,
+      useNode: false,
+      needsShell: false,
+      source: 'fallback',
+      found: false,
+      rejectedOverride: null,
+      pathEnv: '',
+    },
+  }
+  const node = '/usr/bin/node'
+  const nodeMissing: PiStartFailure = { kind: 'node-not-found', node }
+  await i18n.changeLanguage(PSEUDO_LANGUAGE)
+  try {
+    const notFoundReport = reportPiStartFailure(notFound) ?? ''
+    assert.match(notFoundReport, /^Pi binary not found\. /)
+    assert.match(notFoundReport, /Settings > Agent Configuration > Agent Installation\.$/)
+    assert.equal(
+      reportPiStartFailure(nodeMissing),
+      `Node binary not found at resolved path:\n  ${node}\n\nPi's .js entry point requires Node. ` +
+        'Install Node from https://nodejs.org or set the NODE env var to your Node binary path.',
+    )
+    // The UI rendering of the same failure is in the interface language.
+    assert.notEqual(describePiStartFailure(nodeMissing, t), reportPiStartFailure(nodeMissing))
+  } finally {
+    await i18n.changeLanguage(SOURCE_LANGUAGE)
+  }
+  assert.equal(reportPiStartFailure(null), null)
+})
+
+test('countPathEntries splits on the platform delimiter and drops blanks', () => {
+  assert.equal(countPathEntries('/usr/bin:/usr/local/bin::/opt/bin', false), 3)
+  assert.equal(countPathEntries('C:\\Windows;C:\\Tools;', true), 2)
+  assert.equal(countPathEntries('', false), 0)
+})

package/apps/sessrumnir/src/main/diagnostics-report.ts

@@ -0,0 +1,91 @@
+import type { DiagnosticsProviderInfo, ModelsConfig, ModelsReadFailure, ProviderKeyState } from '../shared/ipc-contracts'
+import { describePiStartFailure, type PiStartFailure } from './pi-binary-resolution'
+import { tEnglish, type Translate } from '../shared/i18n'
+
+/**
+ * Pure diagnostics-report helpers, Electron-free so they are unit-testable
+ * (tray-decision.ts pattern). collectDiagnostics in diagnostics.ts does the
+ * I/O and assembles these results.
+ */
+
+/** Classify a provider's apiKey field without ever evaluating secrets. */
+export function classifyProviderKey(
+  apiKey: unknown,
+  env: NodeJS.ProcessEnv,
+): { keyState: ProviderKeyState; envVar?: string } {
+  if (typeof apiKey !== 'string' || apiKey.trim() === '') return { keyState: 'none' }
+  if (apiKey.startsWith('$')) {
+    const envVar = apiKey.slice(1)
+    const value = env[envVar]
+    return {
+      keyState: value !== undefined && value !== '' ? 'env-set' : 'env-missing',
+      envVar,
+    }
+  }
+  if (apiKey.startsWith('!')) return { keyState: 'shell' }
+  return { keyState: 'literal' }
+}
+
+/** Flatten a models config into per-provider diagnostics rows. */
+export function summarizeProviders(
+  config: ModelsConfig,
+  env: NodeJS.ProcessEnv,
+): DiagnosticsProviderInfo[] {
+  return Object.entries(config.providers).map(([name, provider]) => {
+    // The file-level validation only checks the providers RECORD; a hand-
+    // edited entry value can be null or a non-object and must not take the
+    // whole report down.
+    const shape = typeof provider === 'object' && provider !== null ? provider : {}
+    const { keyState, envVar } = classifyProviderKey(shape.apiKey, env)
+    const info: DiagnosticsProviderInfo = {
+      name,
+      modelCount: Array.isArray(shape.models) ? shape.models.length : 0,
+      keyState,
+    }
+    if (envVar !== undefined) info.envVar = envVar
+    return info
+  })
+}
+
+/** First line of `pi --version` output, or null when there is none. */
+export function extractVersionLine(output: string): string | null {
+  const line = output.trim().split('\n')[0]?.trim()
+  return line ? line : null
+}
+
+/** Count entries on a platform-delimited PATH string. */
+export function countPathEntries(pathEnv: string, isWindows: boolean): number {
+  if (!pathEnv) return 0
+  return pathEnv.split(isWindows ? ';' : ':').filter(Boolean).length
+}
+
+/**
+ * The models-file failure line for the shareable report. The report is always
+ * English (ruling R15) and is built from the failure code, never from display
+ * text — rendered with the fixed-English translator using the same keys as
+ * `describeModelsReadFailure`'s interface-language text. Parse detail is left
+ * out: V8's JSON.parse errors quote the source around the bad token, and the
+ * YAML parser prints the offending line with a caret — either can include
+ * literal apiKey material.
+ */
+export function reportModelsReadFailure(
+  fileName: string,
+  failure: ModelsReadFailure,
+  t: Translate = tEnglish,
+): string {
+  switch (failure.kind) {
+    case 'invalid-syntax':
+      return failure.format === 'json'
+        ? t('models.readFailure.invalidJsonNoDetail', { file: fileName })
+        : t('models.readFailure.invalidYamlNoDetail', { file: fileName })
+    case 'missing-providers':
+      return t('models.readFailure.missingProviders', { file: fileName })
+    case 'unreadable':
+      return t('models.readFailure.unreadable', { file: fileName, detail: failure.detail })
+  }
+}
+
+/** Why Pi cannot start, for the shareable report: always English. */
+export function reportPiStartFailure(failure: PiStartFailure | null): string | null {
+  return failure && describePiStartFailure(failure, tEnglish)
+}