@xingular/harness 0.1.4 → 0.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xingular/harness",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "type": "module",
   "description": "Xingular Harness — a Pi agent harness with multi-account sign-in, a compiled system prompt, a memory lifecycle (Wiki), tools, MCP, and skills",
   "repository": {

package/src/accounts/accounts.test.ts

@@ -200,7 +200,7 @@ test('existing account config moves into the shared folder, newest wins', async
   // acc2's settings are newer than the shared copy acc1 just moved in, so they win.
   const second = ensureHome(dir, { id: 'acc2' })
   expect(readFileSync(join(sharedDir(dir), 'settings.json'), 'utf8')).toBe('{"from":"acc2"}')
-  expect(readdirSync(sharedDir(dir)).some((name) => name.startsWith('settings.json.agentx-backup-'))).toBe(true)
+  expect(readdirSync(sharedDir(dir)).some((name) => name.startsWith('settings.json.xagent-backup-'))).toBe(true)
   expect(lstatSync(join(second, 'settings.json')).isSymbolicLink()).toBe(true)
 })
 

package/src/accounts/env.test.ts

@@ -7,7 +7,7 @@ import { configDir, ensureSharedDir, linkSharedEntries, sharedDir, type EntryLin
 
 const temp = () => mkdtempSync(join(tmpdir(), 'harness-env-'))
 const refused = (code = 'EPERM') => Object.assign(new Error(`${code}: operation not permitted, symlink`), { code })
-const backups = (folder: string) => readdirSync(folder).filter((name) => name.includes('agentx-backup'))
+const backups = (folder: string) => readdirSync(folder).filter((name) => name.includes('xagent-backup') || name.includes('agentx-backup'))
 
 // A Windows account without the symlink privilege: file symlinks are refused, junctions and hard links work.
 const windowsLike: EntryLinker = {

package/src/accounts/env.ts

@@ -107,7 +107,7 @@ const modified = (path: string): number => {
 
 /** Moves a real file or folder aside so the shared link can take its place; returns where it went. */
 function backUp(path: string): string {
-  const backup = join(dirname(path), `${basename(path)}.agentx-backup-${Math.floor(Date.now() / 1000)}`)
+  const backup = join(dirname(path), `${basename(path)}.xagent-backup-${Math.floor(Date.now() / 1000)}`)
   renameSync(path, backup)
   return backup
 }

package/src/core/path.test.ts

@@ -0,0 +1,14 @@
+import { describe, expect, it } from 'vitest'
+
+import { prependSearchPath } from './path'
+
+describe('search paths', () => {
+  it('uses Windows separators and keeps the inherited PATH key casing', () => {
+    expect(prependSearchPath('C:\\Harness\\bin', 'C:\\Windows\\System32;C:\\Node', { Path: 'C:\\Windows\\System32;C:\\Node' }, 'win32'))
+      .toEqual({ Path: 'C:\\Harness\\bin;C:\\Windows\\System32;C:\\Node' })
+  })
+
+  it('uses the platform default key when the environment has no PATH entry', () => {
+    expect(prependSearchPath('/harness/bin', '/usr/bin', {}, 'linux')).toEqual({ PATH: '/harness/bin:/usr/bin' })
+  })
+})

package/src/core/path.ts

@@ -1,33 +1,57 @@
-// Where executables are found. A desktop application starts with a minimal PATH, so the login
-// shell's PATH is resolved once and used for everything the harness launches.
+// Where executables are found. POSIX desktop apps may start with a minimal PATH, so the login
+// shell's PATH is resolved once. Windows keeps the inherited PATH and its native separator.
 import { execFileSync } from 'node:child_process'
 import { accessSync, constants, statSync } from 'node:fs'
 import { homedir } from 'node:os'
-import { delimiter, isAbsolute, join } from 'node:path'
+import { delimiter, extname, isAbsolute, join } from 'node:path'
 
-let resolved: string | null = null
+let resolved: { platform: NodeJS.Platform; inherited: string; path: string } | null = null
 
 export function searchPath(): string {
-  if (resolved !== null) return resolved
+  const platform = process.platform
+  const pathKey = pathVariableName(process.env)
+  const inherited = process.env[pathKey] ?? ''
+  if (resolved?.platform === platform && resolved.inherited === inherited) return resolved.path
+  const separator = pathSeparator(platform)
   const entries: string[] = []
-  try {
-    const output = execFileSync(process.env.SHELL || '/bin/zsh', ['-ilc', 'printf %s "$PATH"'], { encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'] })
-    // Interactive shells may print banners; the PATH is the last line.
-    entries.push(...(output.split('\n').filter(Boolean).at(-1) ?? '').split(delimiter))
-  } catch {
-    // The inherited PATH and the usual folders still apply.
+  if (platform !== 'win32') {
+    try {
+      const output = execFileSync(process.env.SHELL || '/bin/zsh', ['-ilc', 'printf %s "$PATH"'], { encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'] })
+      // Interactive shells may print banners; the PATH is the last line.
+      entries.push(...(output.split('\n').filter(Boolean).at(-1) ?? '').split(separator))
+    } catch {
+      // The inherited PATH and the usual folders still apply.
+    }
+  }
+  entries.push(...inherited.split(separator))
+  if (platform !== 'win32') {
+    const home = homedir()
+    if (home) entries.push(...['.local/bin', '.bun/bin', '.npm-global/bin', '.cargo/bin'].map((folder) => join(home, folder)))
+    entries.push('/opt/homebrew/bin', '/usr/local/bin', '/usr/bin', '/bin')
   }
-  entries.push(...(process.env.PATH ?? '').split(delimiter))
-  const home = homedir()
-  if (home) entries.push(...['.local/bin', '.bun/bin', '.npm-global/bin', '.cargo/bin'].map((folder) => join(home, folder)))
-  entries.push('/opt/homebrew/bin', '/usr/local/bin', '/usr/bin', '/bin')
-  resolved = [...new Set(entries.filter(Boolean))].join(delimiter)
-  return resolved
+  const path = [...new Set(entries.filter(Boolean))].join(separator)
+  resolved = { platform, inherited, path }
+  return path
+}
+
+/** The inherited PATH key, preserving Windows' existing capitalization. */
+export function pathVariableName(environment: NodeJS.ProcessEnv): string {
+  return Object.keys(environment).find((name) => name.toLowerCase() === 'path') ?? 'PATH'
+}
+
+/** A child environment with a directory prepended using the selected platform's PATH rules. */
+export function prependSearchPath(directory: string, existing: string, environment: NodeJS.ProcessEnv = process.env, platform: NodeJS.Platform = process.platform): Record<string, string> {
+  const values = [directory, existing].filter(Boolean)
+  return { [pathVariableName(environment)]: values.join(pathSeparator(platform)) }
+}
+
+function pathSeparator(platform: NodeJS.Platform): string {
+  return platform === 'win32' ? ';' : delimiter
 }
 
 function isExecutable(path: string): boolean {
   try {
-    accessSync(path, constants.X_OK)
+    accessSync(path, process.platform === 'win32' ? constants.F_OK : constants.X_OK)
     return statSync(path).isFile()
   } catch {
     return false
@@ -36,10 +60,20 @@ function isExecutable(path: string): boolean {
 
 /** The executable `name` resolves to: itself when absolute, else the first match on the search path. */
 export function findBinary(name: string): string | null {
-  if (isAbsolute(name)) return isExecutable(name) ? name : null
-  for (const directory of searchPath().split(delimiter)) {
-    const candidate = join(directory, name)
-    if (isExecutable(candidate)) return candidate
+  const platform = process.platform
+  const suffixes = platform === 'win32' && !extname(name)
+    ? (process.env.PATHEXT || '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean)
+    : []
+  const names = [name, ...suffixes.map((suffix) => `${name}${suffix}`)]
+  if (isAbsolute(name)) {
+    for (const candidate of names) if (isExecutable(candidate)) return candidate
+    return null
+  }
+  for (const directory of searchPath().split(pathSeparator(platform))) {
+    for (const candidateName of names) {
+      const candidate = join(directory, candidateName)
+      if (isExecutable(candidate)) return candidate
+    }
   }
   return null
 }

package/src/mcp/connections.ts

@@ -7,7 +7,7 @@ import { secretKey, type SecretStore } from '../accounts/secrets'
 import type { Bus } from '../core/bus'
 import { HarnessError, invalid, notFound } from '../core/errors'
 import { newId, readJson, safeId, writeJson } from '../core/fs'
-import { findBinary, searchPath } from '../core/path'
+import { findBinary, pathVariableName, searchPath } from '../core/path'
 import { isDir } from '../memory/store'
 import type { RunEvent } from '../sessions/contracts'
 import * as attachments from '../plugins/attachments'
@@ -450,7 +450,7 @@ export class Connections {
     }
     let command = findBinary(connection.command) ?? (isAbsolute(connection.command) ? connection.command : null)
     if (!command) throw new HarnessError('mcp_unavailable', 'MCP executable was not found. Select its absolute path.')
-    const env: Record<string, string> = { PATH: searchPath() }
+    const env: Record<string, string> = { [pathVariableName(process.env)]: searchPath() }
     for (const key of ['HOME', 'TMPDIR', 'LANG']) if (process.env[key]) env[key] = process.env[key]!
     for (const key of connection.envKeys) {
       const value = await this.secret(connection.id, key)

package/src/mcp/manager.ts

@@ -62,7 +62,7 @@ export class McpManager {
   }
 
   private async connectStdio(config: StdioConfig) {
-    const client = new Client({ name: 'agent-x', version: '0.1.0' })
+    const client = new Client({ name: 'xagent', version: '0.1.0' })
     const transport = new StdioClientTransport({ command: config.command, args: config.args, cwd: config.cwd ?? undefined, env: config.env, stderr: 'pipe' })
     try {
       await client.connect(transport, { timeout: 30000 })
@@ -82,7 +82,7 @@ export class McpManager {
     const options = { authProvider, requestInit: { headers: config.headers } }
     // Servers that predate Streamable HTTP only answer on SSE.
     for (const Transport of [StreamableHTTPClientTransport, SSEClientTransport]) {
-      const client = new Client({ name: 'agent-x', version: '0.1.0' })
+      const client = new Client({ name: 'xagent', version: '0.1.0' })
       const transport = new Transport(new URL(config.url), options)
       try {
         await client.connect(transport, { timeout: 30000 })

package/src/memory/blocks.ts

@@ -367,13 +367,13 @@ export function undoLast(wiki: string, blockId: string): Block {
 }
 
 /**
- * The memory-blocks section of a compiled prompt. `cli` names the `agentx-wiki` commands in
+ * The memory-blocks section of a compiled prompt. `cli` names the `xagent-wiki` commands in
  * place of the tools, for sessions that have the command and not the tools.
  */
 export function render(blocks: readonly Block[], caller: Caller, cli: boolean): string {
   if (!blocks.length) return ''
   const how = cli
-    ? '`agentx-wiki block append <label> <text>`, `block replace <label> --old <text> --new <text>`, or `block rethink <label> <text>`'
+    ? '`xagent-wiki block append <label> <text>`, `block replace <label> --old <text> --new <text>`, or `block rethink <label> <text>`'
     : 'memory_append, memory_replace, or memory_rethink'
   return `## Memory blocks\n\nThese blocks are your memory that is always in view, and they persist across conversations. When you learn something worth keeping, edit a block you may change with ${how}. Keep each block within its limit.\n${renderItems(blocks, caller)}`
 }

package/src/memory/caller.ts

@@ -21,7 +21,7 @@ export interface CallerContext {
   briefProjectIds?: string[] | null
   /** `Chat` for an agent's own conversation, `Code` for a session in a project. */
   actor?: string | null
-  /** `cli` when the caller reaches the Wiki through the `agentx-wiki` command. */
+  /** `cli` when the caller reaches the Wiki through the `xagent-wiki` command. */
   surface?: string | null
 }
 

package/src/memory/dispatch.ts

@@ -1,5 +1,5 @@
 // One entry point for every memory, recall, and Wiki call a session makes, whichever way it
-// reaches the harness (a Pi tool, the `agentx-wiki` command, the bundled MCP server).
+// reaches the harness (a Pi tool, the `xagent-wiki` command, the bundled MCP server).
 import type { Bus } from '../core/bus'
 import type { HarnessEnv } from '../core/env'
 import { HarnessError } from '../core/errors'

package/src/memory/facts.ts

@@ -26,7 +26,7 @@ export interface MemoryFront {
   id: string
   title: string
   kind: string
-  /** `/` for everything, or a project namespace such as `/projects/agent-x`. */
+  /** `/` for everything, or a project namespace such as `/projects/xagent`. */
   namespace: string
   sourceIds: string[]
   confidence: string

package/src/memory/store.ts

@@ -93,7 +93,7 @@ export function ensureProjectNamespace(root: string, slug: string, name: string)
 
 // ---- Locations ----------------------------------------------------------------
 
-/** A page's Wiki path (`/projects/agent-x/architecture`) and namespace (`/projects/agent-x`). */
+/** A page's Wiki path (`/projects/xagent/architecture`) and namespace (`/projects/xagent`). */
 export interface Location {
   path: string
   namespace: string

package/src/prompt/compile.test.ts

@@ -97,8 +97,8 @@ test('a session gets blocks, rules, skills, knowledge and tools', () => {
   for (const expected of ['<block label="user"', '<block label="project/xingular-agent"', 'Always run the tests.', 'review (skills/review)', '/projects/xingular-agent/decisions — Decisions', 'Use pnpm', 'App tools and connected apps: Use get_capabilities.']) expect(text).toContain(expected)
   expect(text).not.toContain('Astro')
   const cli = render(env, compile(env, { ...session('p1'), surface: 'cli' }))
-  expect(cli).toContain('agentx-wiki search')
-  expect(cli).toContain('agentx-wiki block append')
+  expect(cli).toContain('xagent-wiki search')
+  expect(cli).toContain('xagent-wiki block append')
 })
 
 test('long rules shorten only the rules section', () => {

package/src/prompt/compile.ts

@@ -321,7 +321,7 @@ export function toolGroups(context: CallerContext, launch: Launch): OrderedGroup
       tools: MEMORY_GROUP,
       order: GROUP_ORDER.Memory,
       guidance: cli
-        ? 'Memory: `agentx-wiki block append <label> <text>`, `block replace <label> --old <text> --new <text>`, and `block rethink <label> <text>` edit your memory blocks. `agentx-wiki facts [query]` recalls saved facts. `agentx-wiki history <query>` searches earlier runs and `agentx-wiki history-read <run id>` returns one.'
+        ? 'Memory: `xagent-wiki block append <label> <text>`, `block replace <label> --old <text> --new <text>`, and `block rethink <label> <text>` edit your memory blocks. `xagent-wiki facts [query]` recalls saved facts. `xagent-wiki history <query>` searches earlier runs and `xagent-wiki history-read <run id>` returns one.'
         : 'Memory: memory_append, memory_replace, and memory_rethink edit your memory blocks; memory_facts recalls saved facts. history_search finds what was said and done in earlier conversations and runs, including a chat that was cleared; history_read returns one run.'
     },
     {
@@ -329,7 +329,7 @@ export function toolGroups(context: CallerContext, launch: Launch): OrderedGroup
       tools: KNOWLEDGE_GROUP,
       order: GROUP_ORDER.Knowledge,
       guidance: cli
-        ? 'Knowledge: `agentx-wiki search <query>`, `read <id or path>`, `list [namespace]`, `skill [name]`, and `propose <json>` to record durable knowledge. Cite what you use as [id@revision].'
+        ? 'Knowledge: `xagent-wiki search <query>`, `read <id or path>`, `list [namespace]`, `skill [name]`, and `propose <json>` to record durable knowledge. Cite what you use as [id@revision].'
         : 'Knowledge: wiki_search, wiki_read, and wiki_list read the Wiki; skill_load loads a skill\'s steps; wiki_propose records durable knowledge, quoting its evidence (the Wiki validates it and may send it to the Inbox). Cite what you use as [id@revision].'
     },
     {

package/src/sessions/contracts.ts

@@ -43,6 +43,15 @@ const contextSnapshotPayload = z.object({
   contextUpdateTruncated: z.boolean().optional(),
   toolsTruncated: z.boolean().optional()
 })
+/** Generic reference to content a provider stores outside the run-event stream. */
+export const toolAttachmentRefSchema = z.object({
+  id: z.string().min(1).max(300),
+  name: z.string().min(1).max(500),
+  mimeType: z.string().min(1).max(100)
+}).strict()
+export const toolAttachmentRefsSchema = z.array(toolAttachmentRefSchema).max(16)
+export type ToolAttachmentRef = z.infer<typeof toolAttachmentRefSchema>
+
 const toolPayload = z.object({
   toolCallId: z.string(),
   name: z.string(),
@@ -54,7 +63,9 @@ const toolPayload = z.object({
   ok: z.boolean().optional(),
   /** On `tool.completed`: how long the call ran, and the size of what it returned to the model. */
   durationMs: z.number().optional(),
-  resultChars: z.number().optional()
+  resultChars: z.number().optional(),
+  /** Opaque attachment references. Content stays outside the run event stream. */
+  attachments: toolAttachmentRefsSchema.optional()
 })
 const retryStartedPayload = z.object({ attempt: z.number(), maxAttempts: z.number(), delayMs: z.number(), error: z.string().max(1_000).optional() })
 const retryEndedPayload = z.object({ attempt: z.number(), success: z.boolean(), error: z.string().max(1_000).optional() })

package/src/sessions/runner.ts

@@ -11,7 +11,7 @@ import type { Loading, Registered } from '../plugins/plugins'
 import { CONTEXT_MESSAGE_TYPE, CONTEXT_SNAPSHOT_KEY, type ContextUpdate } from '../prompt/compile'
 import type { RegistryResources } from '../skills/registry'
 import type { ToolSpec } from '../tools/types'
-import type { UsageRequest } from './contracts'
+import { toolAttachmentRefsSchema, type UsageRequest } from './contracts'
 import { completedReasoningSummary, REASONING_SUMMARY_APIS, requestConciseReasoningSummary } from './reasoningSummaries'
 import { extensionUi, type ExtensionHost } from './extensionUi'
 import { observeResources, registrationHash } from '../plugins/runtime'
@@ -162,6 +162,14 @@ function evidenceText(value: unknown): string | null {
   }
 }
 
+/** Pi keeps provider-only metadata in `details`; only a bounded, generic reference enters the event. */
+function toolAttachmentRefs(result: unknown) {
+  const details = (result as { details?: unknown } | null | undefined)?.details
+  const refs = details && typeof details === 'object' ? (details as { attachments?: unknown }).attachments : undefined
+  const parsed = toolAttachmentRefsSchema.safeParse(refs)
+  return parsed.success && parsed.data.length ? parsed.data : undefined
+}
+
 function boundedSchema(value: unknown, budget: { remaining: number }, depth = 0): { value: unknown; truncated: boolean } {
   if (budget.remaining <= 0 || depth > 12) return { value: '[truncated]', truncated: true }
   if (typeof value === 'string') {
@@ -355,12 +363,14 @@ export async function runTurn(run: ActiveRun, session: PiSessionLike, params: Tu
         const resultChars = resultSize(tool.result)
         const output = evidenceText(tool.result)
         const boundedOutput = output === null ? null : limitedText(output)
+        const attachments = toolAttachmentRefs(tool.result)
         run.emit('tool.completed', {
           toolCallId: tool.toolCallId,
           name: tool.toolName,
           ok: !tool.isError,
           ...(started === undefined ? {} : { durationMs: Date.now() - started }),
           ...(resultChars === null ? {} : { resultChars }),
+          ...(attachments ? { attachments } : {}),
           ...(boundedOutput ? { output: boundedOutput.text, ...(boundedOutput.truncated ? { outputTruncated: true } : {}) } : {})
         })
         break
@@ -442,7 +452,7 @@ export async function loadResources(pi: typeof import('@earendil-works/pi-coding
     agentDir: params.account.configDir,
     // Inline extensions load after the ones on disk, and the gate after all of them, so it sees
     // what every plugin made of a call.
-    extensionFactories: [...(params.inline ?? []).map((extension) => ({ name: extension.name, factory: extension.factory as never, hidden: true })), { name: 'agent-x-approvals', factory: gate as never, hidden: true }],
+    extensionFactories: [...(params.inline ?? []).map((extension) => ({ name: extension.name, factory: extension.factory as never, hidden: true })), { name: 'xagent-approvals', factory: gate as never, hidden: true }],
     additionalSkillPaths: [...(params.resources?.skillPaths ?? []), ...(loading?.skillPaths ?? [])],
     additionalPromptTemplatePaths: [...(params.resources?.promptPaths ?? []), ...(loading?.promptPaths ?? [])],
     // The compiler writes one prompt; nothing else is appended here.
@@ -511,7 +521,10 @@ export const piSessionFactory: SessionFactory = async ({ params, allow, gate, to
           const result = await spec.execute(input as Record<string, unknown>)
           const output = typeof result === 'string' ? { text: result } : result
           if (output.image && !supportsImageInput) throw new HarnessError('image_input_unsupported', 'This model cannot inspect images. Choose a model that supports image input.')
-          return { content: [{ type: 'text', text: output.text }, ...(output.image ? [{ type: 'image', data: output.image.data, mimeType: output.image.mimeType }] : [])] as never, details: {} }
+          return {
+            content: [{ type: 'text', text: output.text }, ...(output.image ? [{ type: 'image', data: output.image.data, mimeType: output.image.mimeType }] : [])] as never,
+            details: output.attachments?.length ? { attachments: output.attachments } : {}
+          }
         }
       })
     )

package/src/sessions/sessions.test.ts

@@ -215,6 +215,27 @@ describe('session turns on Pi', () => {
     expect(completed.output.length).toBeLessThanOrEqual(24_000)
   })
 
+  it('records generic tool attachment references without storing their content bytes', async () => {
+    const { events, run } = setup(async ({ gate }) => fakeSession(async (emit) => {
+      emit({ type: 'tool_execution_end', toolCallId: 'image-1', toolName: 'capture', isError: false, result: {
+        content: [{ type: 'text', text: 'Captured screen.' }, { type: 'image', data: 'model-image-bytes' }],
+        details: { attachments: [{ id: 'attachment-1', name: 'Screen capture', mimeType: 'image/jpeg' }] }
+      } })
+      emit({ type: 'tool_execution_end', toolCallId: 'image-2', toolName: 'capture', isError: false, result: {
+        content: [{ type: 'text', text: 'Invalid attachment metadata was ignored.' }],
+        details: { attachments: [{ id: 'attachment-2', name: 'Capture', mimeType: 'image/jpeg', data: 'must-not-persist' }] }
+      } })
+    }, gate))
+
+    await run('attachments-run')
+    await tick()
+    const completed = events.filter((event) => event.type === 'tool.completed').map((event) => event.payload as Record<string, unknown>)
+    expect(completed[0]?.attachments).toEqual([{ id: 'attachment-1', name: 'Screen capture', mimeType: 'image/jpeg' }])
+    expect(completed[1]).not.toHaveProperty('attachments')
+    expect(JSON.stringify(events)).not.toContain('model-image-bytes')
+    expect(JSON.stringify(events)).not.toContain('must-not-persist')
+  })
+
   it('records bounded retry and compaction events without exposing thinking text', async () => {
     const { events, run } = setup(async ({ gate }) =>
       fakeSession(async (emit) => {

package/src/terminal/cli.ts

@@ -1,10 +1,10 @@
-// `agentx-wiki` and `agentx-mcp`: the harness's memory, Wiki, and connected apps as commands,
+// `xagent-wiki` and `xagent-mcp`: the harness's memory, Wiki, and connected apps as commands,
 // for a `pi` terminal session's shell. Each command maps onto one call to the session socket.
 import type { WikiCall } from '../tools/definitions'
 import { connectionFromEnv, socketCall } from './client'
 
-export const WIKI_COMMAND = 'agentx-wiki'
-export const APPS_COMMAND = 'agentx-mcp'
+export const WIKI_COMMAND = 'xagent-wiki'
+export const APPS_COMMAND = 'xagent-mcp'
 
 export const USAGE = `Usage: ${WIKI_COMMAND} <command> [arguments]
 
@@ -109,7 +109,7 @@ async function readStdin(): Promise<string> {
 
 const errorText = (error: unknown): string => (error instanceof Error ? error.message : String(error))
 
-/** Runs `agentx-wiki <argv>`; returns the exit code. */
+/** Runs `xagent-wiki <argv>`; returns the exit code. */
 export async function runWikiCli(argv: string[]): Promise<number> {
   const command = parseCli(argv)
   if (command.kind === 'help') {
@@ -130,7 +130,7 @@ export async function runWikiCli(argv: string[]): Promise<number> {
   }
 }
 
-/** Runs `agentx-mcp <argv>`; returns the exit code. */
+/** Runs `xagent-mcp <argv>`; returns the exit code. */
 export async function runAppsCli(argv: string[]): Promise<number> {
   const [command, name, args] = argv
   if (command !== 'list' && !(command === 'call' && name)) {

package/src/terminal/client.ts

@@ -1,5 +1,5 @@
-// How a process outside the harness (the `pi` command's extension, the `agentx-wiki` and
-// `agentx-mcp` commands) reaches it: one newline-delimited JSON request and reply per
+// How a process outside the harness (the `pi` command's extension, the `xagent-wiki` and
+// `xagent-mcp` commands) reaches it: one newline-delimited JSON request and reply per
 // connection to the session socket, authorized by the token the harness put in its environment.
 import { createConnection } from 'node:net'
 

package/src/terminal/launch.test.ts

@@ -0,0 +1,34 @@
+import { spawnSync } from 'node:child_process'
+import { describe, expect, it } from 'vitest'
+
+import { bundledPiCli, resolvePiCommand, terminalCommandFiles } from './launch'
+
+describe('terminal launch commands', () => {
+  it('runs the pinned Pi CLI with the active Node runtime on Windows', () => {
+    const launch = resolvePiCommand({ platform: 'win32', node: 'C:\\Program Files\\nodejs\\node.exe' })
+
+    expect(launch.program).toBe('C:\\Program Files\\nodejs\\node.exe')
+    expect(launch.argsPrefix[0]).toMatch(/[\\/]node_modules[\\/]@earendil-works[\\/]pi-coding-agent[\\/]dist[\\/]bundle[\\/]cli\.js$/)
+  })
+
+  it('runs the package CLI through Node for a no-model help smoke', () => {
+    const result = spawnSync(process.execPath, [bundledPiCli(), '--help'], { encoding: 'utf8', timeout: 20_000 })
+
+    expect(result.error).toBeUndefined()
+    expect(result.status).toBe(0)
+    expect(`${result.stdout}${result.stderr}`).toMatch(/usage|options|pi/i)
+  })
+
+  it('keeps an explicitly configured executable even on Windows', () => {
+    expect(resolvePiCommand({ platform: 'win32', node: 'node.exe', programOverride: () => 'C:\\Tools\\pi.exe' }))
+      .toEqual({ program: 'C:\\Tools\\pi.exe', argsPrefix: [] })
+  })
+
+  it('provides Git Bash and native Windows launchers for each Harness command', () => {
+    expect(terminalCommandFiles('win32', 'C:\\Program Files\\nodejs\\node.exe', 'C:\\Harness\\cli.js', 'xagent-wiki', 'wiki'))
+      .toEqual([
+        { name: 'xagent-wiki', content: "#!/bin/sh\nexec '/c/Program Files/nodejs/node.exe' '/c/Harness/cli.js' wiki \"$@\"\n" },
+        { name: 'xagent-wiki.cmd', content: '@echo off\r\n"%XINGULAR_HARNESS_NODE%" "%XINGULAR_HARNESS_CLI%" wiki %*\r\nexit /b %ERRORLEVEL%\r\n' }
+      ])
+  })
+})

package/src/terminal/launch.ts

@@ -0,0 +1,88 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { join, resolve } from 'node:path'
+
+import { HarnessError } from '../core/errors'
+import { findBinary } from '../core/path'
+
+const PI_PACKAGE = '@earendil-works/pi-coding-agent'
+
+export interface PiCommand {
+  program: string
+  argsPrefix: string[]
+}
+
+/** Resolve the Pi package's declared command instead of depending on its POSIX npm shim. */
+export function bundledPiCli(): string {
+  const require = createRequire(import.meta.url)
+  for (const nodeModules of require.resolve.paths(PI_PACKAGE) ?? []) {
+    const directory = join(nodeModules, ...PI_PACKAGE.split('/'))
+    const manifestPath = join(directory, 'package.json')
+    if (!existsSync(manifestPath)) continue
+    try {
+      const manifest = JSON.parse(readFileSync(manifestPath, 'utf8')) as {
+        name?: unknown
+        bin?: unknown
+      }
+      if (manifest.name === PI_PACKAGE) {
+        const executable = typeof manifest.bin === 'string'
+          ? manifest.bin
+          : manifest.bin && typeof manifest.bin === 'object' && typeof (manifest.bin as Record<string, unknown>).pi === 'string'
+            ? (manifest.bin as Record<string, string>).pi
+            : null
+        if (!executable) throw new Error('the package does not declare its pi command')
+        const cli = resolve(directory, executable)
+        if (!existsSync(cli)) throw new Error(`the declared command does not exist at ${cli}`)
+        return cli
+      }
+    } catch {
+      continue
+    }
+  }
+
+  throw new HarnessError('harness_unavailable', `The bundled ${PI_PACKAGE} package does not expose a usable pi command. Reinstall the Harness package and try again.`)
+}
+
+export function resolvePiCommand(options: {
+  platform: NodeJS.Platform
+  node: string
+  programOverride?: () => string | null
+}): PiCommand {
+  if (options.programOverride) {
+    const program = options.programOverride()
+    if (!program) throw new HarnessError('harness_unavailable', 'The Pi CLI was not found on PATH.')
+    return { program, argsPrefix: [] }
+  }
+  if (options.platform === 'win32') return { program: options.node, argsPrefix: [bundledPiCli()] }
+  const program = findBinary('pi')
+  if (!program) throw new HarnessError('harness_unavailable', 'The Pi CLI was not found on PATH.')
+  return { program, argsPrefix: [] }
+}
+
+function bashPath(path: string): string {
+  const drive = /^([a-z]):[\\/](.*)$/i.exec(path)
+  if (drive) return `/${drive[1].toLowerCase()}/${drive[2].replaceAll('\\', '/')}`
+  if (path.startsWith('\\\\')) return `//${path.slice(2).replaceAll('\\', '/')}`
+  return path
+}
+
+function shellQuote(value: string): string {
+  return `'${value.replaceAll("'", "'\\''")}'`
+}
+
+/** Files Pi's Git Bash shell and native Windows shells use to call Harness subcommands. */
+export function terminalCommandFiles(platform: NodeJS.Platform, node: string, cli: string, name: string, mode: string): Array<{ name: string; content: string }> {
+  const shellNode = platform === 'win32' ? bashPath(node) : node
+  const shellCli = platform === 'win32' ? bashPath(cli) : cli
+  const files = [{
+    name,
+    content: `#!/bin/sh\nexec ${shellQuote(shellNode)} ${shellQuote(shellCli)} ${mode} "$@"\n`
+  }]
+  if (platform === 'win32') {
+    files.push({
+      name: `${name}.cmd`,
+      content: `@echo off\r\n"%XINGULAR_HARNESS_NODE%" "%XINGULAR_HARNESS_CLI%" ${mode} %*\r\nexit /b %ERRORLEVEL%\r\n`
+    })
+  }
+  return files
+}

package/src/terminal/socket.ts

@@ -1,5 +1,5 @@
 // The session socket: how a process the harness did not start in-process (the `pi` command in
-// a terminal, with its extension and the `agentx-wiki` / `agentx-mcp` commands) reaches the
+// a terminal, with its extension and the `xagent-wiki` / `xagent-mcp` commands) reaches the
 // session it belongs to. Owner-only Unix socket (a named pipe on Windows), newline-delimited JSON,
 // one request per connection. Each terminal session holds a random token bound to its caller, its
 // connected-apps grant, and its controller; the token stops working when the terminal ends.

package/src/terminal/standalone.test.ts

@@ -117,4 +117,14 @@ describe('standalone terminal startup', () => {
     expect(existsSync(socketPath(harness.stateDir))).toBe(false)
     expect(harness.terminals.has('failed')).toBe(false)
   })
+
+  it('explains a missing Pi executable in terms of the terminal launch', async () => {
+    const home = temporaryDirectory('harness-standalone-enoent-')
+    const cwd = temporaryDirectory('harness-cwd-enoent-')
+    const error = Object.assign(new Error('spawn /opt/pi/bin/pi ENOENT'), { code: 'ENOENT' })
+    const spawn = fakeSpawn(() => undefined, { error })
+
+    await expect(runStandaloneTerminal([], { home, cwd, stdinIsTTY: true, stdoutIsTTY: true, createSessionId: () => 'missing-pi', createHarness: harnessFactory, spawn }))
+      .rejects.toThrow(/Could not start Pi terminal.*Pi executable.*\/opt\/pi\/bin\/pi/)
+  })
 })

package/src/terminal/standalone.ts

@@ -73,6 +73,16 @@ function exitCode(code: number | null, signal: NodeJS.Signals | null): number {
   return 1
 }
 
+function spawnError(error: Error, launch: TerminalLaunch): Error {
+  const code = (error as NodeJS.ErrnoException).code
+  if (code !== 'ENOENT' && code !== 'EACCES' && code !== 'EPERM') return error
+  if (launch.program === process.execPath || launch.env.XINGULAR_HARNESS_NODE === launch.program) {
+    return new Error(`Could not start the Pi terminal because Node could not run "${launch.args[0] ?? 'the bundled Pi CLI'}" (${code}). Verify Node and the bundled Pi package are installed.`, { cause: error })
+  }
+  const problem = code === 'ENOENT' ? 'was not found' : `could not start (${code})`
+  return new Error(`Could not start Pi terminal. Pi executable "${launch.program}" ${problem}; verify it is installed and executable or check the configured terminal executable.`, { cause: error })
+}
+
 function spawnPi(launch: TerminalLaunch, cwd: string, spawn = nodeSpawn): Promise<number> {
   return new Promise((resolveExit, reject) => {
     const child = spawn(launch.program, launch.args, {
@@ -103,7 +113,7 @@ function spawnPi(launch: TerminalLaunch, cwd: string, spawn = nodeSpawn): Promis
     process.on('SIGINT', onInterrupt)
     process.on('SIGTERM', onTerminate)
     process.on('SIGHUP', onHangup)
-    child.once('error', (error) => finish(() => reject(error)))
+    child.once('error', (error) => finish(() => reject(spawnError(error, launch))))
     child.once('exit', (code, signal) => finish(() => resolveExit(exitCode(code, signal))))
   })
 }