@agimon-ai/po 0.0.0-alpha.2 → 0.0.0-alpha.21

package/dist/src/composition/syncService/localBuilds.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"localBuilds.mjs","names":[],"sources":["../../../../src/composition/syncService/localBuilds.ts"],"sourcesContent":["import { type ChildProcess, spawn, spawnSync } from 'node:child_process';\nimport crypto from 'node:crypto';\nimport fs from 'node:fs';\nimport path from 'node:path';\n\nimport { writeFileAtomic } from '@agimon-ai/po-core/runtimeJson';\n\n/**\n * Builds the packages sync roots name by local path, so the web, native and MCP builds read\n * current output. Each package builds at most once per sync, in dependency order within the\n * local set, with the package manager its nearest lockfile names. Install never runs.\n */\n\nconst LOCAL_SOURCE_DIRECTORY = 'src';\nconst PACKAGE_MANIFEST = 'package.json';\nconst NODE_MODULES = 'node_modules';\nconst LOCAL_BUILDS_FILE = path.join('build', 'local-builds.json');\nconst BUILD_SCRIPT = 'build';\nconst STDERR_TAIL_LINES = 20;\n/** Bytes of stderr kept per build while it runs; older output is dropped as it arrives. */\nconst STDERR_TAIL_BYTES = 64 * 1024;\n/**\n * A local build that runs longer than this is stopped and reported as failed. Sync holds its\n * lock while a build runs, so a hung build must not hold it forever.\n */\nexport const LOCAL_BUILD_TIMEOUT_MS = 10 * 60 * 1000;\n/** How long a build's stderr may stay open after it exits, held by a process it left running. */\nconst STDERR_CLOSE_GRACE_MS = 1000;\nconst MILLISECONDS_PER_SECOND = 1000;\nconst LOGIN_SHELL_TIMEOUT_MS = 10_000;\nconst DEFAULT_PACKAGE_MANAGER = 'npm';\nconst NO_SUCH_PROCESS = 'ESRCH';\n/** Checked nearest-first in each folder; the first lockfile found names the package manager. */\nconst LOCKFILES: readonly (readonly [string, string])[] = [\n  ['pnpm-lock.yaml', 'pnpm'],\n  ['bun.lock', 'bun'],\n  ['bun.lockb', 'bun'],\n  ['yarn.lock', 'yarn'],\n  ['package-lock.json', 'npm'],\n];\n/** Variables a Po session or another harness exports; a package build must not see them. */\nconst HARNESS_PREFIXES = ['PO_', 'PI_', 'CLAUDE_', 'CODEX_'];\nconst HARNESS_VARIABLES = new Set(['CLAUDECODE', 'MCP_UI_VIEWER', 'npm_config_user_agent']);\nconst DEPENDENCY_FIELDS = ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies'];\n\nexport interface LocalPackage {\n  /** The selector as a root's configuration names it. */\n  selector: string;\n  directory: string;\n}\n\nexport type LocalBuildOutcome =\n  | { status: 'built' | 'cached' }\n  | { status: 'failed'; reason: string; stderr?: string[] };\n\nexport interface LocalBuildInput {\n  globalRoot: string;\n  environment: NodeJS.ProcessEnv;\n  directories: readonly string[];\n  /** Receives each command line as it starts. */\n  onCommand: (command: string) => void;\n  onNotice: (message: string) => void;\n  /** Overrides `LOCAL_BUILD_TIMEOUT_MS`. */\n  timeoutMs?: number;\n}\n\ninterface Manifest {\n  name?: string;\n  main?: unknown;\n  module?: unknown;\n  exports?: unknown;\n  scripts?: Record<string, unknown>;\n  [field: string]: unknown;\n}\n\nfunction sourceFiles(directory: string): string[] {\n  let entries: fs.Dirent[];\n  try {\n    entries = fs.readdirSync(directory, { withFileTypes: true });\n  } catch {\n    // A package without a source folder has only its manifest to stamp.\n    return [];\n  }\n  return entries.flatMap((entry) => {\n    const full = path.join(directory, entry.name);\n    if (entry.isDirectory()) return entry.name === NODE_MODULES ? [] : sourceFiles(full);\n    return entry.isFile() ? [full] : [];\n  });\n}\n\n/**\n * The build stamp of a local package: an mtime and size signature over its `package.json`\n * and every file under `src/`.\n * ponytail: it misses edits to dependencies outside the package; a content hash is the upgrade.\n */\nexport function localBuildStamp(packageDirectory: string): string {\n  const files = [\n    path.join(packageDirectory, PACKAGE_MANIFEST),\n    ...sourceFiles(path.join(packageDirectory, LOCAL_SOURCE_DIRECTORY)),\n  ];\n  const hash = crypto.createHash('sha256');\n  for (const file of files.sort()) {\n    const relative = path.relative(packageDirectory, file);\n    try {\n      const stat = fs.statSync(file);\n      hash.update(`${relative}\\0${String(stat.size)}\\0${String(stat.mtimeMs)}\\n`);\n    } catch {\n      // Recorded as missing, so the stamp moves when the file appears.\n      hash.update(`${relative}\\0missing\\n`);\n    }\n  }\n  return hash.digest('hex');\n}\n\nexport function localBuildsPath(globalRoot: string): string {\n  return path.join(globalRoot, LOCAL_BUILDS_FILE);\n}\n\nfunction readStamps(globalRoot: string): Record<string, string> {\n  try {\n    const parsed = JSON.parse(fs.readFileSync(localBuildsPath(globalRoot), 'utf8')) as unknown;\n    return typeof parsed === 'object' && parsed !== null ? (parsed as Record<string, string>) : {};\n  } catch {\n    // Missing or unreadable: every package builds once.\n    return {};\n  }\n}\n\nfunction readManifest(directory: string): Manifest | undefined {\n  try {\n    return JSON.parse(fs.readFileSync(path.join(directory, PACKAGE_MANIFEST), 'utf8')) as Manifest;\n  } catch {\n    return undefined;\n  }\n}\n\n/** The package manager the nearest lockfile names, walking up from the package. */\nexport function packageManagerFor(directory: string): string {\n  let current = path.resolve(directory);\n  for (;;) {\n    for (const [lockfile, manager] of LOCKFILES) if (fs.existsSync(path.join(current, lockfile))) return manager;\n    const parent = path.dirname(current);\n    if (parent === current) return DEFAULT_PACKAGE_MANAGER;\n    current = parent;\n  }\n}\n\nfunction findOnPath(binary: string, searchPath: string | undefined): string | undefined {\n  for (const directory of (searchPath ?? '').split(path.delimiter).filter(Boolean)) {\n    const candidate = path.join(directory, binary);\n    try {\n      fs.accessSync(candidate, fs.constants.X_OK);\n      if (fs.statSync(candidate).isFile()) return candidate;\n    } catch {\n      // Not in this folder.\n    }\n  }\n  return undefined;\n}\n\n/**\n * The login shell's PATH. Desktop apps launched from Finder get a minimal PATH (inferred,\n * not checked here), so a package manager installed through a shell profile is missing.\n */\nfunction loginShellPath(environment: NodeJS.ProcessEnv): string | undefined {\n  const shell = environment.SHELL ?? '/bin/zsh';\n  const result = spawnSync(shell, ['-ilc', 'printf %s \"$PATH\"'], {\n    encoding: 'utf8',\n    timeout: LOGIN_SHELL_TIMEOUT_MS,\n  });\n  return result.status === 0 && result.stdout.trim() !== '' ? result.stdout.trim() : undefined;\n}\n\n/** The build environment: the caller's minus every `PO_*` and harness variable. */\nexport function buildEnvironment(environment: NodeJS.ProcessEnv): NodeJS.ProcessEnv {\n  return Object.fromEntries(\n    Object.entries(environment).filter(\n      ([name]) => !HARNESS_VARIABLES.has(name) && !HARNESS_PREFIXES.some((prefix) => name.startsWith(prefix)),\n    ),\n  );\n}\n\nfunction entryPaths(value: unknown): string[] {\n  if (typeof value === 'string') return [value];\n  if (Array.isArray(value)) return value.flatMap(entryPaths);\n  if (typeof value === 'object' && value !== null) return Object.values(value).flatMap(entryPaths);\n  return [];\n}\n\n/** Whether every file `main`, `module` and `exports` name exists; false when they name none. */\nfunction builtEntriesPresent(directory: string, manifest: Manifest): boolean {\n  const entries = [manifest.main, manifest.module, manifest.exports]\n    .flatMap(entryPaths)\n    .filter((entry) => !entry.includes('*'));\n  return entries.length > 0 && entries.every((entry) => fs.existsSync(path.resolve(directory, entry)));\n}\n\n/** The directories ordered so each local package builds after the local packages it depends on. */\nfunction dependencyOrder(directories: readonly string[], manifests: Map<string, Manifest | undefined>): string[] {\n  const byName = new Map<string, string>();\n  for (const directory of directories) {\n    const name = manifests.get(directory)?.name;\n    if (name !== undefined) byName.set(name, directory);\n  }\n  const ordered: string[] = [];\n  const visiting = new Set<string>();\n  const visit = (directory: string): void => {\n    if (ordered.includes(directory) || visiting.has(directory)) return;\n    visiting.add(directory);\n    const manifest = manifests.get(directory);\n    for (const field of DEPENDENCY_FIELDS) {\n      const dependencies = manifest?.[field];\n      if (typeof dependencies !== 'object' || dependencies === null) continue;\n      for (const name of Object.keys(dependencies)) {\n        const dependency = byName.get(name);\n        if (dependency !== undefined) visit(dependency);\n      }\n    }\n    visiting.delete(directory);\n    ordered.push(directory);\n  };\n  for (const directory of directories) visit(directory);\n  return ordered;\n}\n\nfunction stderrTail(stderr: string): string[] {\n  return stderr.trimEnd().split('\\n').filter(Boolean).slice(-STDERR_TAIL_LINES);\n}\n\ninterface BuildRun {\n  status: number | null;\n  signal: NodeJS.Signals | null;\n  error?: Error;\n  timedOut: boolean;\n  /** It exited while a process it started still held stderr open; that process was stopped. */\n  leftRunning: boolean;\n  /** The last `STDERR_TAIL_BYTES` of stderr. */\n  stderr: string;\n}\n\n/** Signals that end this process; a build in its own process group would not receive them. */\nconst FORWARDED_SIGNALS: readonly NodeJS.Signals[] = ['SIGINT', 'SIGTERM', 'SIGHUP'];\nconst SEPARATE_PROCESS_GROUPS = process.platform !== 'win32';\n\n/**\n * Kills the build and everything it started. The build leads its own process group, so the\n * package manager's tsc or vite children die with it.\n * ponytail: Windows has no process groups here, so only the package manager is killed there;\n * `taskkill /T /F` is the upgrade if Windows builds must stop their children too.\n */\nfunction killBuild(child: ChildProcess): void {\n  if (!SEPARATE_PROCESS_GROUPS || child.pid === undefined) {\n    child.kill('SIGKILL');\n    return;\n  }\n  try {\n    process.kill(-child.pid, 'SIGKILL');\n  } catch (error) {\n    // ESRCH: every process of the group has exited already, which is the goal. Anything else\n    // (EPERM) falls back to the package manager alone rather than crash inside a timer.\n    if ((error as NodeJS.ErrnoException).code !== NO_SUCH_PROCESS) child.kill('SIGKILL');\n  }\n}\n\n/**\n * Runs one build script without buffering its output: stdout is discarded and only the stderr\n * tail is kept. A build still running after `timeoutMs` is killed with every process it started\n * and reported as timed out. A build that exits while something it started still holds stderr\n * open has that process group killed when the grace ends, so nothing writes after it returns.\n */\nfunction runBuildScript(\n  binary: string,\n  directory: string,\n  environment: NodeJS.ProcessEnv,\n  timeoutMs: number,\n): Promise<BuildRun> {\n  return new Promise((resolve) => {\n    let tail = Buffer.alloc(0);\n    let timedOut = false;\n    let leftRunning = false;\n    let settled = false;\n    let grace: NodeJS.Timeout | undefined;\n    // Its own process group, so a kill reaches its children. Still awaited: never unref'd.\n    const child = spawn(binary, ['run', BUILD_SCRIPT], {\n      cwd: directory,\n      env: environment,\n      stdio: ['ignore', 'ignore', 'pipe'],\n      detached: SEPARATE_PROCESS_GROUPS,\n    });\n    // A detached build no longer gets the terminal's Ctrl+C, so this process passes it on.\n    const forward = (signal: NodeJS.Signals): void => {\n      killBuild(child);\n      if (process.listenerCount(signal) > 1) return;\n      // Only this handler was listening: end as the signal would have without it.\n      process.removeListener(signal, forward);\n      process.kill(process.pid, signal);\n    };\n    if (SEPARATE_PROCESS_GROUPS) for (const signal of FORWARDED_SIGNALS) process.on(signal, forward);\n    const finish = (result: Pick<BuildRun, 'status' | 'signal' | 'error'>): void => {\n      if (settled) return;\n      settled = true;\n      clearTimeout(timer);\n      clearTimeout(grace);\n      for (const signal of FORWARDED_SIGNALS) process.removeListener(signal, forward);\n      child.stderr?.destroy();\n      resolve({ ...result, timedOut, leftRunning, stderr: tail.toString('utf8') });\n    };\n    const timer = setTimeout(() => {\n      timedOut = true;\n      killBuild(child);\n    }, timeoutMs);\n    child.stderr?.on('data', (chunk: Buffer) => {\n      tail = Buffer.concat([tail, chunk]);\n      if (tail.length > STDERR_TAIL_BYTES) tail = tail.subarray(tail.length - STDERR_TAIL_BYTES);\n    });\n    child.on('error', (error) => finish({ status: null, signal: null, error }));\n    child.on('close', (status, signal) => finish({ status, signal }));\n    // A process the build left running can hold stderr open, so 'close' may never come.\n    child.on('exit', (status, signal) => {\n      grace = setTimeout(\n        () => {\n          if (!timedOut) leftRunning = true;\n          killBuild(child);\n          finish({ status, signal });\n        },\n        timedOut ? 0 : STDERR_CLOSE_GRACE_MS,\n      );\n    });\n  });\n}\n\n/**\n * Builds every local package that changed since its last successful build, and returns each\n * directory's outcome. A failure never stops the others.\n */\nexport async function buildLocalPackages(input: LocalBuildInput): Promise<Map<string, LocalBuildOutcome>> {\n  const { globalRoot, environment, onCommand, onNotice } = input;\n  const timeoutMs = input.timeoutMs ?? LOCAL_BUILD_TIMEOUT_MS;\n  const directories = [...new Set(input.directories)];\n  const manifests = new Map(directories.map((directory) => [directory, readManifest(directory)]));\n  const stamps = readStamps(globalRoot);\n  const outcomes = new Map<string, LocalBuildOutcome>();\n  const childEnvironment = buildEnvironment(environment);\n  let searchPath = environment.PATH;\n  let loginPathTried = false;\n  const resolveBinary = (manager: string): string | undefined => {\n    const found = findOnPath(manager, searchPath);\n    if (found !== undefined || loginPathTried || process.platform !== 'darwin') return found;\n    loginPathTried = true;\n    const loginPath = loginShellPath(environment);\n    if (loginPath === undefined) return undefined;\n    searchPath = loginPath;\n    childEnvironment.PATH = loginPath;\n    return findOnPath(manager, searchPath);\n  };\n\n  for (const directory of dependencyOrder(directories, manifests)) {\n    const manifest = manifests.get(directory);\n    if (manifest === undefined) {\n      outcomes.set(directory, { status: 'failed', reason: `'${directory}' has no readable package.json` });\n      continue;\n    }\n    const stamp = localBuildStamp(directory);\n    // ponytail: an unchanged stamp skips the build even when a dependency outside the\n    // package changed; a content hash over the dependency closure is the upgrade.\n    if (stamps[directory] === stamp) {\n      outcomes.set(directory, { status: 'cached' });\n      continue;\n    }\n    if (typeof manifest.scripts?.[BUILD_SCRIPT] !== 'string') {\n      outcomes.set(\n        directory,\n        builtEntriesPresent(directory, manifest)\n          ? { status: 'cached' }\n          : { status: 'failed', reason: 'it has no build script and no built entries' },\n      );\n      continue;\n    }\n    const manager = packageManagerFor(directory);\n    const binary = resolveBinary(manager);\n    if (binary === undefined) {\n      outcomes.set(directory, { status: 'failed', reason: `${manager} is not on PATH` });\n      continue;\n    }\n    const command = `${binary} run ${BUILD_SCRIPT} (in ${directory})`;\n    onCommand(command);\n    onNotice(`building ${manifest.name ?? directory}`);\n    const result = await runBuildScript(binary, directory, childEnvironment, timeoutMs);\n    if (result.status === 0 && !result.timedOut && !result.leftRunning) {\n      // The stamp after the build, as the sync pointer records it: a build that writes into\n      // src/ or package.json must not look changed to the next sync.\n      stamps[directory] = localBuildStamp(directory);\n      writeFileAtomic(localBuildsPath(globalRoot), `${JSON.stringify(stamps, null, 2)}\\n`);\n      outcomes.set(directory, { status: 'built' });\n      continue;\n    }\n    const exit = result.timedOut\n      ? `timed out after ${String(timeoutMs / MILLISECONDS_PER_SECOND)} s`\n      : result.status === 0 && result.leftRunning\n        ? 'it exited but left processes running, which were stopped'\n        : (result.error?.message ?? `exit ${String(result.status ?? result.signal)}`);\n    outcomes.set(directory, {\n      status: 'failed',\n      reason: `${manager} run ${BUILD_SCRIPT} failed (${exit})`,\n      stderr: stderrTail(result.stderr),\n    });\n  }\n  return outcomes;\n}\n"],"mappings":"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"}
+{"version":3,"file":"localBuilds.mjs","names":[],"sources":["../../../../src/composition/syncService/localBuilds.ts"],"sourcesContent":["import { type ChildProcess, spawn, spawnSync } from 'node:child_process';\nimport crypto from 'node:crypto';\nimport fs from 'node:fs';\nimport path from 'node:path';\n\nimport { writeFileAtomic } from '@agimon-ai/po-core/runtimeJson';\nimport { getValidatedTestContext } from '@agimon-ai/po-core/testMode';\n\n/**\n * Builds the packages sync roots name by local path, so the web, native and MCP builds read\n * current output. Each package builds at most once per sync, in dependency order within the\n * local set, with the package manager its nearest lockfile names. Install never runs.\n */\n\nconst LOCAL_SOURCE_DIRECTORY = 'src';\nconst PACKAGE_MANIFEST = 'package.json';\nconst NODE_MODULES = 'node_modules';\nconst LOCAL_BUILDS_FILE = path.join('build', 'local-builds.json');\nconst BUILD_SCRIPT = 'build';\nconst STDERR_TAIL_LINES = 20;\n/** Bytes of stderr kept per build while it runs; older output is dropped as it arrives. */\nconst STDERR_TAIL_BYTES = 64 * 1024;\n/**\n * A local build that runs longer than this is stopped and reported as failed. Sync holds its\n * lock while a build runs, so a hung build must not hold it forever.\n */\nexport const LOCAL_BUILD_TIMEOUT_MS = 10 * 60 * 1000;\n/** How long a build's stderr may stay open after it exits, held by a process it left running. */\nconst STDERR_CLOSE_GRACE_MS = 1000;\nconst MILLISECONDS_PER_SECOND = 1000;\nconst LOGIN_SHELL_TIMEOUT_MS = 10_000;\nconst DEFAULT_PACKAGE_MANAGER = 'npm';\nconst NO_SUCH_PROCESS = 'ESRCH';\n/** Checked nearest-first in each folder; the first lockfile found names the package manager. */\nconst LOCKFILES: readonly (readonly [string, string])[] = [\n  ['pnpm-lock.yaml', 'pnpm'],\n  ['bun.lock', 'bun'],\n  ['bun.lockb', 'bun'],\n  ['yarn.lock', 'yarn'],\n  ['package-lock.json', 'npm'],\n];\n/** Variables a Po session or another harness exports; a package build must not see them. */\nconst HARNESS_PREFIXES = ['PO_', 'PI_', 'CLAUDE_', 'CODEX_'];\nconst HARNESS_VARIABLES = new Set(['CLAUDECODE', 'MCP_UI_VIEWER', 'npm_config_user_agent']);\nconst DEPENDENCY_FIELDS = ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies'];\n\nexport interface LocalPackage {\n  /** The selector as a root's configuration names it. */\n  selector: string;\n  directory: string;\n}\n\nexport type LocalBuildOutcome =\n  | { status: 'built' | 'cached' }\n  | { status: 'failed'; reason: string; stderr?: string[] };\n\nexport interface LocalBuildInput {\n  globalRoot: string;\n  environment: NodeJS.ProcessEnv;\n  directories: readonly string[];\n  /** Receives each command line as it starts. */\n  onCommand: (command: string) => void;\n  onNotice: (message: string) => void;\n  /** Overrides `LOCAL_BUILD_TIMEOUT_MS`. */\n  timeoutMs?: number;\n}\n\ninterface Manifest {\n  name?: string;\n  main?: unknown;\n  module?: unknown;\n  exports?: unknown;\n  scripts?: Record<string, unknown>;\n  [field: string]: unknown;\n}\n\nfunction sourceFiles(directory: string): string[] {\n  let entries: fs.Dirent[];\n  try {\n    entries = fs.readdirSync(directory, { withFileTypes: true });\n  } catch {\n    // A package without a source folder has only its manifest to stamp.\n    return [];\n  }\n  return entries.flatMap((entry) => {\n    const full = path.join(directory, entry.name);\n    if (entry.isDirectory()) return entry.name === NODE_MODULES ? [] : sourceFiles(full);\n    return entry.isFile() ? [full] : [];\n  });\n}\n\n/**\n * The build stamp of a local package: an mtime and size signature over its `package.json`\n * and every file under `src/`.\n * ponytail: it misses edits to dependencies outside the package; a content hash is the upgrade.\n */\nexport function localBuildStamp(packageDirectory: string): string {\n  const files = [\n    path.join(packageDirectory, PACKAGE_MANIFEST),\n    ...sourceFiles(path.join(packageDirectory, LOCAL_SOURCE_DIRECTORY)),\n  ];\n  const hash = crypto.createHash('sha256');\n  for (const file of files.sort()) {\n    const relative = path.relative(packageDirectory, file);\n    try {\n      const stat = fs.statSync(file);\n      hash.update(`${relative}\\0${String(stat.size)}\\0${String(stat.mtimeMs)}\\n`);\n    } catch {\n      // Recorded as missing, so the stamp moves when the file appears.\n      hash.update(`${relative}\\0missing\\n`);\n    }\n  }\n  return hash.digest('hex');\n}\n\nexport function localBuildsPath(globalRoot: string): string {\n  return path.join(globalRoot, LOCAL_BUILDS_FILE);\n}\n\nfunction readStamps(globalRoot: string): Record<string, string> {\n  try {\n    const parsed = JSON.parse(fs.readFileSync(localBuildsPath(globalRoot), 'utf8')) as unknown;\n    return typeof parsed === 'object' && parsed !== null ? (parsed as Record<string, string>) : {};\n  } catch {\n    // Missing or unreadable: every package builds once.\n    return {};\n  }\n}\n\nfunction readManifest(directory: string): Manifest | undefined {\n  try {\n    return JSON.parse(fs.readFileSync(path.join(directory, PACKAGE_MANIFEST), 'utf8')) as Manifest;\n  } catch {\n    return undefined;\n  }\n}\n\n/** The package manager the nearest lockfile names, walking up from the package. */\nexport function packageManagerFor(directory: string): string {\n  let current = path.resolve(directory);\n  for (;;) {\n    for (const [lockfile, manager] of LOCKFILES) if (fs.existsSync(path.join(current, lockfile))) return manager;\n    const parent = path.dirname(current);\n    if (parent === current) return DEFAULT_PACKAGE_MANAGER;\n    current = parent;\n  }\n}\n\nfunction findOnPath(binary: string, searchPath: string | undefined): string | undefined {\n  for (const directory of (searchPath ?? '').split(path.delimiter).filter(Boolean)) {\n    const candidate = path.join(directory, binary);\n    try {\n      fs.accessSync(candidate, fs.constants.X_OK);\n      if (fs.statSync(candidate).isFile()) return candidate;\n    } catch {\n      // Not in this folder.\n    }\n  }\n  return undefined;\n}\n\n/**\n * The login shell's PATH. Desktop apps launched from Finder get a minimal PATH (inferred,\n * not checked here), so a package manager installed through a shell profile is missing.\n */\nfunction loginShellPath(environment: NodeJS.ProcessEnv): string | undefined {\n  const shell = environment.SHELL ?? '/bin/zsh';\n  const result = spawnSync(shell, ['-ilc', 'printf %s \"$PATH\"'], {\n    encoding: 'utf8',\n    timeout: LOGIN_SHELL_TIMEOUT_MS,\n  });\n  return result.status === 0 && result.stdout.trim() !== '' ? result.stdout.trim() : undefined;\n}\n\n/** Strip harness state, then restore only validated test isolation for nested Po commands. */\nexport function buildEnvironment(environment: NodeJS.ProcessEnv): NodeJS.ProcessEnv {\n  const testContext = getValidatedTestContext(environment);\n  return {\n    ...Object.fromEntries(\n      Object.entries(environment).filter(\n        ([name]) => !HARNESS_VARIABLES.has(name) && !HARNESS_PREFIXES.some((prefix) => name.startsWith(prefix)),\n      ),\n    ),\n    ...testContext?.env,\n  };\n}\n\nfunction entryPaths(value: unknown): string[] {\n  if (typeof value === 'string') return [value];\n  if (Array.isArray(value)) return value.flatMap(entryPaths);\n  if (typeof value === 'object' && value !== null) return Object.values(value).flatMap(entryPaths);\n  return [];\n}\n\n/** Whether every file `main`, `module` and `exports` name exists; false when they name none. */\nfunction builtEntriesPresent(directory: string, manifest: Manifest): boolean {\n  const entries = [manifest.main, manifest.module, manifest.exports]\n    .flatMap(entryPaths)\n    .filter((entry) => !entry.includes('*'));\n  return entries.length > 0 && entries.every((entry) => fs.existsSync(path.resolve(directory, entry)));\n}\n\n/** The directories ordered so each local package builds after the local packages it depends on. */\nfunction dependencyOrder(directories: readonly string[], manifests: Map<string, Manifest | undefined>): string[] {\n  const byName = new Map<string, string>();\n  for (const directory of directories) {\n    const name = manifests.get(directory)?.name;\n    if (name !== undefined) byName.set(name, directory);\n  }\n  const ordered: string[] = [];\n  const visiting = new Set<string>();\n  const visit = (directory: string): void => {\n    if (ordered.includes(directory) || visiting.has(directory)) return;\n    visiting.add(directory);\n    const manifest = manifests.get(directory);\n    for (const field of DEPENDENCY_FIELDS) {\n      const dependencies = manifest?.[field];\n      if (typeof dependencies !== 'object' || dependencies === null) continue;\n      for (const name of Object.keys(dependencies)) {\n        const dependency = byName.get(name);\n        if (dependency !== undefined) visit(dependency);\n      }\n    }\n    visiting.delete(directory);\n    ordered.push(directory);\n  };\n  for (const directory of directories) visit(directory);\n  return ordered;\n}\n\nfunction stderrTail(stderr: string): string[] {\n  return stderr.trimEnd().split('\\n').filter(Boolean).slice(-STDERR_TAIL_LINES);\n}\n\ninterface BuildRun {\n  status: number | null;\n  signal: NodeJS.Signals | null;\n  error?: Error;\n  timedOut: boolean;\n  /** It exited while a process it started still held stderr open; that process was stopped. */\n  leftRunning: boolean;\n  /** The last `STDERR_TAIL_BYTES` of stderr. */\n  stderr: string;\n}\n\n/** Signals that end this process; a build in its own process group would not receive them. */\nconst FORWARDED_SIGNALS: readonly NodeJS.Signals[] = ['SIGINT', 'SIGTERM', 'SIGHUP'];\nconst SEPARATE_PROCESS_GROUPS = process.platform !== 'win32';\n\n/**\n * Kills the build and everything it started. The build leads its own process group, so the\n * package manager's tsc or vite children die with it.\n * ponytail: Windows has no process groups here, so only the package manager is killed there;\n * `taskkill /T /F` is the upgrade if Windows builds must stop their children too.\n */\nfunction killBuild(child: ChildProcess): void {\n  if (!SEPARATE_PROCESS_GROUPS || child.pid === undefined) {\n    child.kill('SIGKILL');\n    return;\n  }\n  try {\n    process.kill(-child.pid, 'SIGKILL');\n  } catch (error) {\n    // ESRCH: every process of the group has exited already, which is the goal. Anything else\n    // (EPERM) falls back to the package manager alone rather than crash inside a timer.\n    if ((error as NodeJS.ErrnoException).code !== NO_SUCH_PROCESS) child.kill('SIGKILL');\n  }\n}\n\n/**\n * Runs one build script without buffering its output: stdout is discarded and only the stderr\n * tail is kept. A build still running after `timeoutMs` is killed with every process it started\n * and reported as timed out. A build that exits while something it started still holds stderr\n * open has that process group killed when the grace ends, so nothing writes after it returns.\n */\nfunction runBuildScript(\n  binary: string,\n  directory: string,\n  environment: NodeJS.ProcessEnv,\n  timeoutMs: number,\n): Promise<BuildRun> {\n  return new Promise((resolve) => {\n    let tail = Buffer.alloc(0);\n    let timedOut = false;\n    let leftRunning = false;\n    let settled = false;\n    let grace: NodeJS.Timeout | undefined;\n    // Its own process group, so a kill reaches its children. Still awaited: never unref'd.\n    const child = spawn(binary, ['run', BUILD_SCRIPT], {\n      cwd: directory,\n      env: environment,\n      stdio: ['ignore', 'ignore', 'pipe'],\n      detached: SEPARATE_PROCESS_GROUPS,\n    });\n    // A detached build no longer gets the terminal's Ctrl+C, so this process passes it on.\n    const forward = (signal: NodeJS.Signals): void => {\n      killBuild(child);\n      if (process.listenerCount(signal) > 1) return;\n      // Only this handler was listening: end as the signal would have without it.\n      process.removeListener(signal, forward);\n      process.kill(process.pid, signal);\n    };\n    if (SEPARATE_PROCESS_GROUPS) for (const signal of FORWARDED_SIGNALS) process.on(signal, forward);\n    const finish = (result: Pick<BuildRun, 'status' | 'signal' | 'error'>): void => {\n      if (settled) return;\n      settled = true;\n      clearTimeout(timer);\n      clearTimeout(grace);\n      for (const signal of FORWARDED_SIGNALS) process.removeListener(signal, forward);\n      child.stderr?.destroy();\n      resolve({ ...result, timedOut, leftRunning, stderr: tail.toString('utf8') });\n    };\n    const timer = setTimeout(() => {\n      timedOut = true;\n      killBuild(child);\n    }, timeoutMs);\n    child.stderr?.on('data', (chunk: Buffer) => {\n      tail = Buffer.concat([tail, chunk]);\n      if (tail.length > STDERR_TAIL_BYTES) tail = tail.subarray(tail.length - STDERR_TAIL_BYTES);\n    });\n    child.on('error', (error) => finish({ status: null, signal: null, error }));\n    child.on('close', (status, signal) => finish({ status, signal }));\n    // A process the build left running can hold stderr open, so 'close' may never come.\n    child.on('exit', (status, signal) => {\n      grace = setTimeout(\n        () => {\n          if (!timedOut) leftRunning = true;\n          killBuild(child);\n          finish({ status, signal });\n        },\n        timedOut ? 0 : STDERR_CLOSE_GRACE_MS,\n      );\n    });\n  });\n}\n\n/**\n * Builds every local package that changed since its last successful build, and returns each\n * directory's outcome. A failure never stops the others.\n */\nexport async function buildLocalPackages(input: LocalBuildInput): Promise<Map<string, LocalBuildOutcome>> {\n  const { globalRoot, environment, onCommand, onNotice } = input;\n  const timeoutMs = input.timeoutMs ?? LOCAL_BUILD_TIMEOUT_MS;\n  const directories = [...new Set(input.directories)];\n  const manifests = new Map(directories.map((directory) => [directory, readManifest(directory)]));\n  const stamps = readStamps(globalRoot);\n  const outcomes = new Map<string, LocalBuildOutcome>();\n  const childEnvironment = buildEnvironment(environment);\n  let searchPath = environment.PATH;\n  let loginPathTried = false;\n  const resolveBinary = (manager: string): string | undefined => {\n    const found = findOnPath(manager, searchPath);\n    if (found !== undefined || loginPathTried || process.platform !== 'darwin') return found;\n    loginPathTried = true;\n    const loginPath = loginShellPath(environment);\n    if (loginPath === undefined) return undefined;\n    searchPath = loginPath;\n    childEnvironment.PATH = loginPath;\n    return findOnPath(manager, searchPath);\n  };\n\n  for (const directory of dependencyOrder(directories, manifests)) {\n    const manifest = manifests.get(directory);\n    if (manifest === undefined) {\n      outcomes.set(directory, { status: 'failed', reason: `'${directory}' has no readable package.json` });\n      continue;\n    }\n    const stamp = localBuildStamp(directory);\n    // ponytail: an unchanged stamp skips the build even when a dependency outside the\n    // package changed; a content hash over the dependency closure is the upgrade.\n    if (stamps[directory] === stamp) {\n      outcomes.set(directory, { status: 'cached' });\n      continue;\n    }\n    if (typeof manifest.scripts?.[BUILD_SCRIPT] !== 'string') {\n      outcomes.set(\n        directory,\n        builtEntriesPresent(directory, manifest)\n          ? { status: 'cached' }\n          : { status: 'failed', reason: 'it has no build script and no built entries' },\n      );\n      continue;\n    }\n    const manager = packageManagerFor(directory);\n    const binary = resolveBinary(manager);\n    if (binary === undefined) {\n      outcomes.set(directory, { status: 'failed', reason: `${manager} is not on PATH` });\n      continue;\n    }\n    const command = `${binary} run ${BUILD_SCRIPT} (in ${directory})`;\n    onCommand(command);\n    onNotice(`building ${manifest.name ?? directory}`);\n    const result = await runBuildScript(binary, directory, childEnvironment, timeoutMs);\n    if (result.status === 0 && !result.timedOut && !result.leftRunning) {\n      // The stamp after the build, as the sync pointer records it: a build that writes into\n      // src/ or package.json must not look changed to the next sync.\n      stamps[directory] = localBuildStamp(directory);\n      writeFileAtomic(localBuildsPath(globalRoot), `${JSON.stringify(stamps, null, 2)}\\n`);\n      outcomes.set(directory, { status: 'built' });\n      continue;\n    }\n    const exit = result.timedOut\n      ? `timed out after ${String(timeoutMs / MILLISECONDS_PER_SECOND)} s`\n      : result.status === 0 && result.leftRunning\n        ? 'it exited but left processes running, which were stopped'\n        : (result.error?.message ?? `exit ${String(result.status ?? result.signal)}`);\n    outcomes.set(directory, {\n      status: 'failed',\n      reason: `${manager} run ${BUILD_SCRIPT} failed (${exit})`,\n      stderr: stderrTail(result.stderr),\n    });\n  }\n  return outcomes;\n}\n"],"mappings":"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"}

package/dist/src/extensions/setupDiagnostics.cjs

@@ -1,6 +1,6 @@
 const require_index = require("../cli/commands/doctor/index.cjs");
 let _agimon_ai_po_config_harnessState = require("@agimon-ai/po-config/harnessState");
-let _agimon_ai_po_core_serverFacet = require("@agimon-ai/po-core/serverFacet");
+let _agimon_ai_po_core_serverPlugin = require("@agimon-ai/po-core/serverPlugin");
 let _agimon_ai_po_core_help = require("@agimon-ai/po-core/help");
 let typebox = require("typebox");
 //#region src/extensions/setupDiagnostics.ts
@@ -12,11 +12,11 @@ const guidance = {
 	"profiles.yaml": "po-author-profile"
 };
 function createSetupDiagnosticsTool(readScope, authorize) {
-	return (0, _agimon_ai_po_core_serverFacet.defineTool)({
+	return (0, _agimon_ai_po_core_serverPlugin.defineTool)({
 		name: DIAGNOSE_SETUP_NAME,
 		description: "Check this session's saved configuration, installed packages, and the global web build without changing anything. Returns scoped check results and the relevant setup guidance, never configuration values or credentials.",
 		parameters: typebox.Type.Object({}, { additionalProperties: false }),
-		when: _agimon_ai_po_core_help.DOOM_HELP_WHEN,
+		when: _agimon_ai_po_core_help.PO_HELP_WHEN,
 		executionMode: "serial",
 		async execute(_input, execution) {
 			const signal = authorize(execution.signal);

package/dist/src/extensions/setupDiagnostics.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"setupDiagnostics.cjs","names":["defineTool","Type","HELP_WHEN","projectHarnessEnvironment","collectDoctorReport"],"sources":["../../../src/extensions/setupDiagnostics.ts"],"sourcesContent":["import { projectHarnessEnvironment } from '@agimon-ai/po-config/harnessState';\nimport type { DoomHeadlessSelection } from '@agimon-ai/po-core/headless';\nimport { DOOM_HELP_WHEN as HELP_WHEN } from '@agimon-ai/po-core/help';\nimport { defineTool } from '@agimon-ai/po-core/serverFacet';\nimport { Type } from 'typebox';\n\nimport { collectDoctorReport } from '../cli/commands/doctor';\n\nexport const DIAGNOSE_SETUP_NAME = 'diagnose_setup';\nexport interface SetupDiagnosticScope {\n  repoRoot: string;\n  cwd: string;\n  environment: Readonly<Record<string, string | undefined>>;\n  selection: Pick<DoomHeadlessSelection, 'majorMode' | 'domains' | 'profile'>;\n}\n\nconst guidance: Readonly<Record<string, string>> = {\n  'config.yaml': 'po-author-config',\n  'modes.yaml': 'po-author-major-mode',\n  'domains.yaml': 'po-author-domain',\n  'profiles.yaml': 'po-author-profile',\n};\n\nexport function createSetupDiagnosticsTool(\n  readScope: () => SetupDiagnosticScope,\n  authorize: (signal?: AbortSignal) => AbortSignal,\n) {\n  return defineTool({\n    name: DIAGNOSE_SETUP_NAME,\n    description:\n      \"Check this session's saved configuration, installed packages, and the global web build without changing anything. Returns scoped check results and the relevant setup guidance, never configuration values or credentials.\",\n    parameters: Type.Object({}, { additionalProperties: false }),\n    when: HELP_WHEN,\n    executionMode: 'serial',\n    async execute(_input, execution) {\n      const signal = authorize(execution.signal);\n      const scope = readScope();\n      const environment = projectHarnessEnvironment(\n        {\n          root: scope.repoRoot,\n          majorMode: scope.selection.majorMode,\n          domains: [...scope.selection.domains],\n          profile: scope.selection.profile,\n        },\n        { ...scope.environment },\n      );\n      const report = collectDoctorReport(environment, scope.cwd);\n      signal.throwIfAborted();\n      authorize(execution.signal);\n      const result = {\n        scope: 'current-session',\n        configurationRoot: report.repoRoot,\n        appliedSelection: {\n          majorMode: scope.selection.majorMode,\n          domains: [...scope.selection.domains],\n          profile: scope.selection.profile,\n        },\n        status: report.problems === 0 && report.skipped.length === 0 ? 'checks-passed' : 'issues-found',\n        checks: report.sections.map((section) => ({\n          area: section.label,\n          status: section.problems.length ? 'failed' : 'passed',\n          problemCount: section.problems.length,\n          guidance: guidance[section.label] ?? 'po-use-help',\n        })),\n        skipped: report.skipped,\n        limitations:\n          'These are saved configuration and installation checks, not a network authentication or agent health test. Error text and configuration values are omitted to protect credentials. Inspect a failed area with its package guidance before proposing a repair.',\n      };\n      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], details: result };\n    },\n  });\n}\n"],"mappings":";;;;;;AAQA,MAAa,sBAAsB;AAQnC,MAAM,WAA6C;CACjD,eAAe;CACf,cAAc;CACd,gBAAgB;CAChB,iBAAiB;AACnB;AAEA,SAAgB,2BACd,WACA,WACA;CACA,QAAA,GAAOA,+BAAAA,WAAAA,CAAW;EAChB,MAAM;EACN,aACE;EACF,YAAYC,QAAAA,KAAK,OAAO,CAAC,GAAG,EAAE,sBAAsB,MAAM,CAAC;EAC3D,MAAMC,wBAAAA;EACN,eAAe;EACf,MAAM,QAAQ,QAAQ,WAAW;GAC/B,MAAM,SAAS,UAAU,UAAU,MAAM;GACzC,MAAM,QAAQ,UAAU;GACxB,MAAM,eAAA,GAAcC,kCAAAA,0BAAAA,CAClB;IACE,MAAM,MAAM;IACZ,WAAW,MAAM,UAAU;IAC3B,SAAS,CAAC,GAAG,MAAM,UAAU,OAAO;IACpC,SAAS,MAAM,UAAU;GAC3B,GACA,EAAE,GAAG,MAAM,YAAY,CACzB;GACA,MAAM,SAASC,cAAAA,oBAAoB,aAAa,MAAM,GAAG;GACzD,OAAO,eAAe;GACtB,UAAU,UAAU,MAAM;GAC1B,MAAM,SAAS;IACb,OAAO;IACP,mBAAmB,OAAO;IAC1B,kBAAkB;KAChB,WAAW,MAAM,UAAU;KAC3B,SAAS,CAAC,GAAG,MAAM,UAAU,OAAO;KACpC,SAAS,MAAM,UAAU;IAC3B;IACA,QAAQ,OAAO,aAAa,KAAK,OAAO,QAAQ,WAAW,IAAI,kBAAkB;IACjF,QAAQ,OAAO,SAAS,KAAK,aAAa;KACxC,MAAM,QAAQ;KACd,QAAQ,QAAQ,SAAS,SAAS,WAAW;KAC7C,cAAc,QAAQ,SAAS;KAC/B,UAAU,SAAS,QAAQ,UAAU;IACvC,EAAE;IACF,SAAS,OAAO;IAChB,aACE;GACJ;GACA,OAAO;IAAE,SAAS,CAAC;KAAE,MAAM;KAAQ,MAAM,KAAK,UAAU,QAAQ,MAAM,CAAC;IAAE,CAAC;IAAG,SAAS;GAAO;EAC/F;CACF,CAAC;AACH"}
+{"version":3,"file":"setupDiagnostics.cjs","names":["defineTool","Type","HELP_WHEN","projectHarnessEnvironment","collectDoctorReport"],"sources":["../../../src/extensions/setupDiagnostics.ts"],"sourcesContent":["import { projectHarnessEnvironment } from '@agimon-ai/po-config/harnessState';\nimport type { PoHeadlessSelection } from '@agimon-ai/po-core/headless';\nimport { PO_HELP_WHEN as HELP_WHEN } from '@agimon-ai/po-core/help';\nimport { defineTool } from '@agimon-ai/po-core/serverPlugin';\nimport { Type } from 'typebox';\n\nimport { collectDoctorReport } from '../cli/commands/doctor';\n\nexport const DIAGNOSE_SETUP_NAME = 'diagnose_setup';\nexport interface SetupDiagnosticScope {\n  repoRoot: string;\n  cwd: string;\n  environment: Readonly<Record<string, string | undefined>>;\n  selection: Pick<PoHeadlessSelection, 'majorMode' | 'domains' | 'profile'>;\n}\n\nconst guidance: Readonly<Record<string, string>> = {\n  'config.yaml': 'po-author-config',\n  'modes.yaml': 'po-author-major-mode',\n  'domains.yaml': 'po-author-domain',\n  'profiles.yaml': 'po-author-profile',\n};\n\nexport function createSetupDiagnosticsTool(\n  readScope: () => SetupDiagnosticScope,\n  authorize: (signal?: AbortSignal) => AbortSignal,\n) {\n  return defineTool({\n    name: DIAGNOSE_SETUP_NAME,\n    description:\n      \"Check this session's saved configuration, installed packages, and the global web build without changing anything. Returns scoped check results and the relevant setup guidance, never configuration values or credentials.\",\n    parameters: Type.Object({}, { additionalProperties: false }),\n    when: HELP_WHEN,\n    executionMode: 'serial',\n    async execute(_input, execution) {\n      const signal = authorize(execution.signal);\n      const scope = readScope();\n      const environment = projectHarnessEnvironment(\n        {\n          root: scope.repoRoot,\n          majorMode: scope.selection.majorMode,\n          domains: [...scope.selection.domains],\n          profile: scope.selection.profile,\n        },\n        { ...scope.environment },\n      );\n      const report = collectDoctorReport(environment, scope.cwd);\n      signal.throwIfAborted();\n      authorize(execution.signal);\n      const result = {\n        scope: 'current-session',\n        configurationRoot: report.repoRoot,\n        appliedSelection: {\n          majorMode: scope.selection.majorMode,\n          domains: [...scope.selection.domains],\n          profile: scope.selection.profile,\n        },\n        status: report.problems === 0 && report.skipped.length === 0 ? 'checks-passed' : 'issues-found',\n        checks: report.sections.map((section) => ({\n          area: section.label,\n          status: section.problems.length ? 'failed' : 'passed',\n          problemCount: section.problems.length,\n          guidance: guidance[section.label] ?? 'po-use-help',\n        })),\n        skipped: report.skipped,\n        limitations:\n          'These are saved configuration and installation checks, not a network authentication or agent health test. Error text and configuration values are omitted to protect credentials. Inspect a failed area with its package guidance before proposing a repair.',\n      };\n      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], details: result };\n    },\n  });\n}\n"],"mappings":";;;;;;AAQA,MAAa,sBAAsB;AAQnC,MAAM,WAA6C;CACjD,eAAe;CACf,cAAc;CACd,gBAAgB;CAChB,iBAAiB;AACnB;AAEA,SAAgB,2BACd,WACA,WACA;CACA,QAAA,GAAOA,gCAAAA,WAAAA,CAAW;EAChB,MAAM;EACN,aACE;EACF,YAAYC,QAAAA,KAAK,OAAO,CAAC,GAAG,EAAE,sBAAsB,MAAM,CAAC;EAC3D,MAAMC,wBAAAA;EACN,eAAe;EACf,MAAM,QAAQ,QAAQ,WAAW;GAC/B,MAAM,SAAS,UAAU,UAAU,MAAM;GACzC,MAAM,QAAQ,UAAU;GACxB,MAAM,eAAA,GAAcC,kCAAAA,0BAAAA,CAClB;IACE,MAAM,MAAM;IACZ,WAAW,MAAM,UAAU;IAC3B,SAAS,CAAC,GAAG,MAAM,UAAU,OAAO;IACpC,SAAS,MAAM,UAAU;GAC3B,GACA,EAAE,GAAG,MAAM,YAAY,CACzB;GACA,MAAM,SAASC,cAAAA,oBAAoB,aAAa,MAAM,GAAG;GACzD,OAAO,eAAe;GACtB,UAAU,UAAU,MAAM;GAC1B,MAAM,SAAS;IACb,OAAO;IACP,mBAAmB,OAAO;IAC1B,kBAAkB;KAChB,WAAW,MAAM,UAAU;KAC3B,SAAS,CAAC,GAAG,MAAM,UAAU,OAAO;KACpC,SAAS,MAAM,UAAU;IAC3B;IACA,QAAQ,OAAO,aAAa,KAAK,OAAO,QAAQ,WAAW,IAAI,kBAAkB;IACjF,QAAQ,OAAO,SAAS,KAAK,aAAa;KACxC,MAAM,QAAQ;KACd,QAAQ,QAAQ,SAAS,SAAS,WAAW;KAC7C,cAAc,QAAQ,SAAS;KAC/B,UAAU,SAAS,QAAQ,UAAU;IACvC,EAAE;IACF,SAAS,OAAO;IAChB,aACE;GACJ;GACA,OAAO;IAAE,SAAS,CAAC;KAAE,MAAM;KAAQ,MAAM,KAAK,UAAU,QAAQ,MAAM,CAAC;IAAE,CAAC;IAAG,SAAS;GAAO;EAC/F;CACF,CAAC;AACH"}

package/dist/src/extensions/setupDiagnostics.mjs

@@ -1,7 +1,7 @@
 import { collectDoctorReport } from "../cli/commands/doctor/index.mjs";
 import { projectHarnessEnvironment } from "@agimon-ai/po-config/harnessState";
-import { defineTool } from "@agimon-ai/po-core/serverFacet";
-import { DOOM_HELP_WHEN } from "@agimon-ai/po-core/help";
+import { defineTool } from "@agimon-ai/po-core/serverPlugin";
+import { PO_HELP_WHEN } from "@agimon-ai/po-core/help";
 import { Type } from "typebox";
 //#region src/extensions/setupDiagnostics.ts
 const DIAGNOSE_SETUP_NAME = "diagnose_setup";
@@ -16,7 +16,7 @@ function createSetupDiagnosticsTool(readScope, authorize) {
 		name: DIAGNOSE_SETUP_NAME,
 		description: "Check this session's saved configuration, installed packages, and the global web build without changing anything. Returns scoped check results and the relevant setup guidance, never configuration values or credentials.",
 		parameters: Type.Object({}, { additionalProperties: false }),
-		when: DOOM_HELP_WHEN,
+		when: PO_HELP_WHEN,
 		executionMode: "serial",
 		async execute(_input, execution) {
 			const signal = authorize(execution.signal);

package/dist/src/extensions/setupDiagnostics.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"setupDiagnostics.mjs","names":["HELP_WHEN"],"sources":["../../../src/extensions/setupDiagnostics.ts"],"sourcesContent":["import { projectHarnessEnvironment } from '@agimon-ai/po-config/harnessState';\nimport type { DoomHeadlessSelection } from '@agimon-ai/po-core/headless';\nimport { DOOM_HELP_WHEN as HELP_WHEN } from '@agimon-ai/po-core/help';\nimport { defineTool } from '@agimon-ai/po-core/serverFacet';\nimport { Type } from 'typebox';\n\nimport { collectDoctorReport } from '../cli/commands/doctor';\n\nexport const DIAGNOSE_SETUP_NAME = 'diagnose_setup';\nexport interface SetupDiagnosticScope {\n  repoRoot: string;\n  cwd: string;\n  environment: Readonly<Record<string, string | undefined>>;\n  selection: Pick<DoomHeadlessSelection, 'majorMode' | 'domains' | 'profile'>;\n}\n\nconst guidance: Readonly<Record<string, string>> = {\n  'config.yaml': 'po-author-config',\n  'modes.yaml': 'po-author-major-mode',\n  'domains.yaml': 'po-author-domain',\n  'profiles.yaml': 'po-author-profile',\n};\n\nexport function createSetupDiagnosticsTool(\n  readScope: () => SetupDiagnosticScope,\n  authorize: (signal?: AbortSignal) => AbortSignal,\n) {\n  return defineTool({\n    name: DIAGNOSE_SETUP_NAME,\n    description:\n      \"Check this session's saved configuration, installed packages, and the global web build without changing anything. Returns scoped check results and the relevant setup guidance, never configuration values or credentials.\",\n    parameters: Type.Object({}, { additionalProperties: false }),\n    when: HELP_WHEN,\n    executionMode: 'serial',\n    async execute(_input, execution) {\n      const signal = authorize(execution.signal);\n      const scope = readScope();\n      const environment = projectHarnessEnvironment(\n        {\n          root: scope.repoRoot,\n          majorMode: scope.selection.majorMode,\n          domains: [...scope.selection.domains],\n          profile: scope.selection.profile,\n        },\n        { ...scope.environment },\n      );\n      const report = collectDoctorReport(environment, scope.cwd);\n      signal.throwIfAborted();\n      authorize(execution.signal);\n      const result = {\n        scope: 'current-session',\n        configurationRoot: report.repoRoot,\n        appliedSelection: {\n          majorMode: scope.selection.majorMode,\n          domains: [...scope.selection.domains],\n          profile: scope.selection.profile,\n        },\n        status: report.problems === 0 && report.skipped.length === 0 ? 'checks-passed' : 'issues-found',\n        checks: report.sections.map((section) => ({\n          area: section.label,\n          status: section.problems.length ? 'failed' : 'passed',\n          problemCount: section.problems.length,\n          guidance: guidance[section.label] ?? 'po-use-help',\n        })),\n        skipped: report.skipped,\n        limitations:\n          'These are saved configuration and installation checks, not a network authentication or agent health test. Error text and configuration values are omitted to protect credentials. Inspect a failed area with its package guidance before proposing a repair.',\n      };\n      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], details: result };\n    },\n  });\n}\n"],"mappings":";;;;;;AAQA,MAAa,sBAAsB;AAQnC,MAAM,WAA6C;CACjD,eAAe;CACf,cAAc;CACd,gBAAgB;CAChB,iBAAiB;AACnB;AAEA,SAAgB,2BACd,WACA,WACA;CACA,OAAO,WAAW;EAChB,MAAM;EACN,aACE;EACF,YAAY,KAAK,OAAO,CAAC,GAAG,EAAE,sBAAsB,MAAM,CAAC;EAC3D,MAAMA;EACN,eAAe;EACf,MAAM,QAAQ,QAAQ,WAAW;GAC/B,MAAM,SAAS,UAAU,UAAU,MAAM;GACzC,MAAM,QAAQ,UAAU;GACxB,MAAM,cAAc,0BAClB;IACE,MAAM,MAAM;IACZ,WAAW,MAAM,UAAU;IAC3B,SAAS,CAAC,GAAG,MAAM,UAAU,OAAO;IACpC,SAAS,MAAM,UAAU;GAC3B,GACA,EAAE,GAAG,MAAM,YAAY,CACzB;GACA,MAAM,SAAS,oBAAoB,aAAa,MAAM,GAAG;GACzD,OAAO,eAAe;GACtB,UAAU,UAAU,MAAM;GAC1B,MAAM,SAAS;IACb,OAAO;IACP,mBAAmB,OAAO;IAC1B,kBAAkB;KAChB,WAAW,MAAM,UAAU;KAC3B,SAAS,CAAC,GAAG,MAAM,UAAU,OAAO;KACpC,SAAS,MAAM,UAAU;IAC3B;IACA,QAAQ,OAAO,aAAa,KAAK,OAAO,QAAQ,WAAW,IAAI,kBAAkB;IACjF,QAAQ,OAAO,SAAS,KAAK,aAAa;KACxC,MAAM,QAAQ;KACd,QAAQ,QAAQ,SAAS,SAAS,WAAW;KAC7C,cAAc,QAAQ,SAAS;KAC/B,UAAU,SAAS,QAAQ,UAAU;IACvC,EAAE;IACF,SAAS,OAAO;IAChB,aACE;GACJ;GACA,OAAO;IAAE,SAAS,CAAC;KAAE,MAAM;KAAQ,MAAM,KAAK,UAAU,QAAQ,MAAM,CAAC;IAAE,CAAC;IAAG,SAAS;GAAO;EAC/F;CACF,CAAC;AACH"}
+{"version":3,"file":"setupDiagnostics.mjs","names":["HELP_WHEN"],"sources":["../../../src/extensions/setupDiagnostics.ts"],"sourcesContent":["import { projectHarnessEnvironment } from '@agimon-ai/po-config/harnessState';\nimport type { PoHeadlessSelection } from '@agimon-ai/po-core/headless';\nimport { PO_HELP_WHEN as HELP_WHEN } from '@agimon-ai/po-core/help';\nimport { defineTool } from '@agimon-ai/po-core/serverPlugin';\nimport { Type } from 'typebox';\n\nimport { collectDoctorReport } from '../cli/commands/doctor';\n\nexport const DIAGNOSE_SETUP_NAME = 'diagnose_setup';\nexport interface SetupDiagnosticScope {\n  repoRoot: string;\n  cwd: string;\n  environment: Readonly<Record<string, string | undefined>>;\n  selection: Pick<PoHeadlessSelection, 'majorMode' | 'domains' | 'profile'>;\n}\n\nconst guidance: Readonly<Record<string, string>> = {\n  'config.yaml': 'po-author-config',\n  'modes.yaml': 'po-author-major-mode',\n  'domains.yaml': 'po-author-domain',\n  'profiles.yaml': 'po-author-profile',\n};\n\nexport function createSetupDiagnosticsTool(\n  readScope: () => SetupDiagnosticScope,\n  authorize: (signal?: AbortSignal) => AbortSignal,\n) {\n  return defineTool({\n    name: DIAGNOSE_SETUP_NAME,\n    description:\n      \"Check this session's saved configuration, installed packages, and the global web build without changing anything. Returns scoped check results and the relevant setup guidance, never configuration values or credentials.\",\n    parameters: Type.Object({}, { additionalProperties: false }),\n    when: HELP_WHEN,\n    executionMode: 'serial',\n    async execute(_input, execution) {\n      const signal = authorize(execution.signal);\n      const scope = readScope();\n      const environment = projectHarnessEnvironment(\n        {\n          root: scope.repoRoot,\n          majorMode: scope.selection.majorMode,\n          domains: [...scope.selection.domains],\n          profile: scope.selection.profile,\n        },\n        { ...scope.environment },\n      );\n      const report = collectDoctorReport(environment, scope.cwd);\n      signal.throwIfAborted();\n      authorize(execution.signal);\n      const result = {\n        scope: 'current-session',\n        configurationRoot: report.repoRoot,\n        appliedSelection: {\n          majorMode: scope.selection.majorMode,\n          domains: [...scope.selection.domains],\n          profile: scope.selection.profile,\n        },\n        status: report.problems === 0 && report.skipped.length === 0 ? 'checks-passed' : 'issues-found',\n        checks: report.sections.map((section) => ({\n          area: section.label,\n          status: section.problems.length ? 'failed' : 'passed',\n          problemCount: section.problems.length,\n          guidance: guidance[section.label] ?? 'po-use-help',\n        })),\n        skipped: report.skipped,\n        limitations:\n          'These are saved configuration and installation checks, not a network authentication or agent health test. Error text and configuration values are omitted to protect credentials. Inspect a failed area with its package guidance before proposing a repair.',\n      };\n      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], details: result };\n    },\n  });\n}\n"],"mappings":";;;;;;AAQA,MAAa,sBAAsB;AAQnC,MAAM,WAA6C;CACjD,eAAe;CACf,cAAc;CACd,gBAAgB;CAChB,iBAAiB;AACnB;AAEA,SAAgB,2BACd,WACA,WACA;CACA,OAAO,WAAW;EAChB,MAAM;EACN,aACE;EACF,YAAY,KAAK,OAAO,CAAC,GAAG,EAAE,sBAAsB,MAAM,CAAC;EAC3D,MAAMA;EACN,eAAe;EACf,MAAM,QAAQ,QAAQ,WAAW;GAC/B,MAAM,SAAS,UAAU,UAAU,MAAM;GACzC,MAAM,QAAQ,UAAU;GACxB,MAAM,cAAc,0BAClB;IACE,MAAM,MAAM;IACZ,WAAW,MAAM,UAAU;IAC3B,SAAS,CAAC,GAAG,MAAM,UAAU,OAAO;IACpC,SAAS,MAAM,UAAU;GAC3B,GACA,EAAE,GAAG,MAAM,YAAY,CACzB;GACA,MAAM,SAAS,oBAAoB,aAAa,MAAM,GAAG;GACzD,OAAO,eAAe;GACtB,UAAU,UAAU,MAAM;GAC1B,MAAM,SAAS;IACb,OAAO;IACP,mBAAmB,OAAO;IAC1B,kBAAkB;KAChB,WAAW,MAAM,UAAU;KAC3B,SAAS,CAAC,GAAG,MAAM,UAAU,OAAO;KACpC,SAAS,MAAM,UAAU;IAC3B;IACA,QAAQ,OAAO,aAAa,KAAK,OAAO,QAAQ,WAAW,IAAI,kBAAkB;IACjF,QAAQ,OAAO,SAAS,KAAK,aAAa;KACxC,MAAM,QAAQ;KACd,QAAQ,QAAQ,SAAS,SAAS,WAAW;KAC7C,cAAc,QAAQ,SAAS;KAC/B,UAAU,SAAS,QAAQ,UAAU;IACvC,EAAE;IACF,SAAS,OAAO;IAChB,aACE;GACJ;GACA,OAAO;IAAE,SAAS,CAAC;KAAE,MAAM;KAAQ,MAAM,KAAK,UAAU,QAAQ,MAAM,CAAC;IAAE,CAAC;IAAG,SAAS;GAAO;EAC/F;CACF,CAAC;AACH"}

package/dist/utils.mjs

@@ -1,2 +1 @@
-import { findRepositoryRoot, isRepositoryRoot } from "./src/composition/repository/index.mjs";
-export { findRepositoryRoot, isRepositoryRoot };
+export { findRepositoryRoot, isRepositoryRoot } from "./src/composition/repository/index.mjs";

package/docs/server/api-export.md

@@ -9,7 +9,7 @@ po api-export --out ./api-schema --strict
 po api-export --out ./api-schema --major-mode copilot --strict
 ```
 
-The command composes the global root and the workspace live and reads each selected server facet's built `poServer.contracts.dist` straight from its installed package. Each contract module is imported in a bounded child process; the command never imports a server facet, installs packages, or starts servers. A package without a readable contract is recorded as a coverage gap. Run `po sync` first if the configuration names packages that are not installed yet.
+The command composes the global root and the workspace live and reads each selected server package's built `poServer.contracts.dist` straight from its installed package. Each contract module is imported in a bounded child process; the command never imports a server plugin, installs packages, or starts servers. A package without a readable contract is recorded as a coverage gap. Run `po sync` first if the configuration names packages that are not installed yet.
 
 The export contains:
 
@@ -17,7 +17,7 @@ The export contains:
 - `asyncapi.json`: AsyncAPI 3.0 Pi envelopes, Chord calls, subscriptions and state deltas, session methods and reconstructed state, and selected extension methods and channel payloads. `x-po` identifies scope, service, member, direction through the operation action, and operation kind.
 - `manifest.json`: selected global, workspace and session modes, contract fingerprints (the generation is always `live`), composition fingerprints, package and protocol versions, explicit dynamic values, coverage gaps, and SHA-256 hashes of both documents.
 
-The global and workspace scopes use their own default major modes. `--major-mode` changes only the session composition. Local WebSockets carry framed CBOR; remote WebSockets carry sealed envelopes around those bytes. Channel operations describe decoded payloads, not JSON WebSocket frames. The selected package's `service` and `member` identify plugin calls carried through `po.plugin.v1.invoke`.
+The global and workspace scopes use their own default major modes. `--major-mode` changes only the session composition. Local WebSockets carry Chord JSON text frames; remote WebSockets carry sealed envelopes around those frames. Channel operations describe decoded payloads. The selected package's `service` and `member` identify plugin calls carried through `po.hub.invoke`.
 
 Export with `--strict` in CI. An incomplete export is still written for review, but the command exits with status 1. Missing third-party declarations do not prevent normal sync. Dynamic tool, provider and author-capability values are listed explicitly; exporting a schema does not freeze runtime capabilities or prove a client compatible.
 
@@ -74,7 +74,7 @@ export default defineApiContract({
 });
 ```
 
-Source schemas use JSON Schema draft-07, including TypeBox output. The exporter namespaces local references and translates tuple keywords for OpenAPI 3.1. Use self-contained local references, without `$id` or remote references. An API-free facet should declare empty `http` and `sockets` arrays. Use `gaps` for known missing declarations; never use an unconstrained schema to hide missing coverage.
+Source schemas use JSON Schema draft-07, including TypeBox output. The exporter namespaces local references and translates tuple keywords for OpenAPI 3.1. Use self-contained local references, without `$id` or remote references. An API-free server plugin should declare empty `http` and `sockets` arrays. Use `gaps` for known missing declarations; never use an unconstrained schema to hide missing coverage.
 
 The exporter is a separate `api-export` command, not a `sync` flag. For a local distribution build:
 

package/docs/server/api.md

@@ -1,6 +1,6 @@
 # Session APIs
 
-Session APIs let a Po package add HTTP behavior beside the direct headless runtime it extends. A package facet is imported from the package's built `poServer.dist` entry, registered in `po-server`, and called in process. The public client route is `/api/workspaces/<workspace-id>/sessions/<session-id>/plugins/<base-path>/...`.
+Session APIs let a Po package add HTTP behavior beside the direct headless runtime it extends. A package's server plugin is imported from the package's built `poServer.dist` entry, installed in `po-server`, and called in process. The public client route is `/api/workspaces/<workspace-id>/sessions/<session-id>/plugins/<base-path>/...`.
 
 This guide also covers the package's TypeScript exports for Node.js callers that want to compose the same in-process services.
 
@@ -26,7 +26,7 @@ package.json poServer declaration
  /api/workspaces/<workspace-id>/sessions/<id>/plugins/<base-path>/...
 ```
 
-The server resolves facet candidates from the same live composition that selects the session runtime. This ensures:
+The server resolves server package candidates from the same live composition that selects the session runtime. This ensures:
 
 - the API implementation follows the same repository, mode, and package selection as the session runtime;
 - each built entry resolves inside its own package and is imported through a URL that changes with the package content; and
@@ -36,7 +36,7 @@ The server starts each handler once, routes requests by a fixed base path, and c
 
 ## Declare a session API
 
-A package declares one `poServer` facet in `package.json`:
+A package declares its server plugin in one `poServer` block in `package.json`:
 
 ```json
 {
@@ -48,18 +48,18 @@ A package declares one `poServer` facet in `package.json`:
 }
 ```
 
-Publish a default-exported `DoomServerFacet` through that entry. In its `apply`, use `requireDoomServerHost(context).registerApi(api)` and return a disposer that calls the registration's `dispose()`. Declare the host service in `inject` and check scope before registering. The API implementation owns its base path.
+Publish a default-exported `PoServerPlugin`, an object with a `name` and an `apply`, through that entry. In its `apply`, use `requirePoServerHost(context).registerApi(api)` and return a disposer that calls the registration's `dispose()`. Declare the host service in `inject` and check scope before registering. The API implementation owns its base path.
 
-Paths are package-relative and cannot escape the package. The server records the built module path and the modes and layers that selected the package, and uses that ownership for admission. See the [complete facet example](../../../../clients/po-web/docs/package-apis.md#declare-an-api).
+Paths are package-relative and cannot escape the package. The server records the built module path and the modes and layers that selected the package, and uses that ownership for admission. See the [complete plugin example](../../../../clients/po-web/docs/package-apis.md#declare-an-api).
 
 ## Implement the handler
 
-Each API registered by a facet implements this lifecycle:
+Each API registered by a server plugin implements this lifecycle:
 
 ```ts
-interface DoomApi {
+interface PoApi {
   basePath: string;
-  start(context: DoomApiContext): {
+  start(context: PoApiContext): {
     fetch(request: Request): Response | Promise<Response>;
     close(): void;
   };
@@ -68,7 +68,7 @@ interface DoomApi {
 
 `start()` creates session-owned resources once. `fetch()` handles requests relative to the package mount. `close()` must release timers, watchers, streams, and other resources created during startup.
 
-Keep the API adapter reusable and have the facet import it. The facet's disposer closes the registration.
+Keep the API adapter reusable and have the server plugin import it. The plugin's disposer closes the registration.
 
 ## Selecting the API composition
 
@@ -76,7 +76,7 @@ The session root's configuration is the only composition source. The server read
 
 Rebuild the package after changing a server-side API. The next new session imports the new build; running sessions keep the module they loaded.
 
-A composition that selects no API is a valid no-API state. In that case package API requests return `404`; the server still provides the typed session protocol. A required eligible facet failure prevents readiness. An optional facet failure is reported and does not remove unrelated APIs.
+A composition that selects no API is a valid no-API state. In that case package API requests return `404`; the server still provides the typed session protocol. A required eligible package failure prevents readiness. An optional package failure is reported and does not remove unrelated APIs.
 
 ## Routing and isolation
 
@@ -111,23 +111,24 @@ Package APIs are executable trusted code. They can access the session's authorit
 
 The core package publishes the in-process building blocks through `@agimon-ai/po/server`:
 
-| Export                              | Responsibility                                                   |
-| ----------------------------------- | ---------------------------------------------------------------- |
-| `createHeadlessSessionManager`      | Own direct session hosts and dispose them                        |
-| `createHeadlessHub`                 | Aggregate sessions, channels, and package API dispatch           |
-| `serveHeadlessServer`               | Expose HTTP and authenticated `/api/ws` WebSocket routes         |
-| `createAgentSessionRuntime`         | Project a direct runtime into typed session state and operations |
-| `createAgentServerService`          | Adapt one typed session service to the Pi protocol host          |
-| `createRpcTranscript`               | Reduce runtime events into the authoritative transcript          |
-| `createHeadlessChildSessionService` | Provide explicitly requested child-session capabilities          |
+| Export                              | Responsibility                                                    |
+| ----------------------------------- | ----------------------------------------------------------------- |
+| `createHeadlessSessionManager`      | Own direct session hosts and dispose them                         |
+| `createHeadlessHub`                 | Aggregate sessions, channels, and package API dispatch            |
+| `serveHeadlessServer`               | Expose HTTP and authenticated `/api/ws` WebSocket routes          |
+| `createAgentSessionRuntime`         | Project a direct runtime into typed session state and operations  |
+| `serveAgentSessions`                | Serve `po.session` on a Chord host from resolved session runtimes |
+| `createHeadlessChildSessionService` | Provide explicitly requested child-session capabilities           |
 
 A minimal composition is:
 
 ```ts
+import { createNodePlatform } from '@agimon-ai/po-core/nodePlatform';
 import { createHeadlessHub, createHeadlessSessionManager, serveHeadlessServer } from '@agimon-ai/po/server';
 
+const platform = createNodePlatform({ sessionsRoot: '/var/lib/po/sessions' });
 const manager = createHeadlessSessionManager();
-const hub = createHeadlessHub({ manager });
+const hub = createHeadlessHub({ manager, platform });
 const server = await serveHeadlessServer({
   headlessHub: hub,
   port: 7533,
@@ -135,10 +136,10 @@ const server = await serveHeadlessServer({
 });
 ```
 
-The caller remains responsible for creating admitted direct session hosts, closing `server`, closing `hub`, and closing `manager` in that order. The executable performs that lifecycle for the command-line case.
+The caller remains responsible for creating admitted direct session hosts with the same `platform`, closing `server`, closing `hub`, and closing `manager` in that order. The executable performs that lifecycle for the command-line case, keeping sessions under `<agent dir>/server/sessions`.
 
 ## Related guides
 
 - [IPC](ipc.md) explains `/api/ws`, typed operations, package dispatch, and replay.
-- [Lifecycle](lifecycle.md) explains when facets load and close.
+- [Lifecycle](lifecycle.md) explains when server packages load and close.
 - [Security](security.md) describes trusted package code and context capabilities.

package/docs/server/getting-started.md

@@ -1,6 +1,6 @@
 # Getting started
 
-`po-server` is the process boundary for one client-neutral headless Po session. It embeds the Pi harness, typed session services, and package facets in one process, then publishes an authenticated HTTP and WebSocket listener.
+`po-server` is the process boundary for one client-neutral headless Po session. It embeds the Pi harness, typed session services, and server plugins in one process, then publishes an authenticated HTTP and WebSocket listener.
 
 ## Choose the topology
 
@@ -57,10 +57,10 @@ A ready session owns:
 | Resource               | Purpose                                                                 |
 | ---------------------- | ----------------------------------------------------------------------- |
 | Loopback HTTP listener | Health, discovery, channel, and package API routes                      |
-| `/api/ws` WebSocket    | Authenticated Pi 0.85 Chord protocol                                    |
+| `/api/ws` WebSocket    | Authenticated Chord 1.2 link frames                                     |
 | Direct harness runtime | In-process Pi execution and typed session operations                    |
 | Session journal        | Upstream v4 JSONL history, normally below `~/.po/agent/server/sessions` |
-| Loaded server facets   | Built `poServer` entries the composition selects                        |
+| Loaded server plugins  | Built `poServer` entries the composition selects                        |
 
 No separate API listener or filesystem endpoint is created. The session service hydrates its authoritative snapshot from the journal and publishes it through the protocol state.
 
@@ -74,11 +74,11 @@ No separate API listener or filesystem endpoint is created. The session service
 | `--web [port]`             | 7533           | Listener port; the listener is started for every server |
 | `-- <harness arguments>`   | none           | Arguments passed to the embedded headless harness       |
 
-There is no server-side command, runtime-directory, or API-directory fallback. Composition comes from the live configuration of each scope. A required facet that cannot be imported fails startup instead of selecting a different module set.
+There is no server-side command, runtime-directory, or API-directory fallback. Composition comes from the live configuration of each scope. A required server package that cannot be imported fails startup instead of selecting a different module set.
 
 ## Select the runtime composition
 
-The server follows the repository that owns the session working directory; a member checkout such as a worktree resolves its composition from the workspace root. It composes that configuration, collects the selected packages' `poServer` entries, filters them for the active major mode and layers, and installs the resulting facets into the direct headless host.
+The server follows the repository that owns the session working directory; a member checkout such as a worktree resolves its composition from the workspace root. It composes that configuration, collects the selected packages' `poServer` entries, filters them for the active major mode and layers, and installs the resulting server plugins into the direct headless host.
 
 Each entry is imported through a URL that changes with the package content. After you rebuild or upgrade a package, the next new session imports the new build without a server restart; running sessions keep the module they loaded. Run `po sync` after changing configuration that names new packages, so they are installed.
 
@@ -96,9 +96,9 @@ Configure the cockpit with the server URL and token through its documented pairi
 
 ## Stop and recover
 
-`SIGINT` and `SIGTERM` dispose the headless host, close package facets, stop the direct runtime, close the listener, and release history ownership. A normal stop leaves the v4 session journal available for a later server.
+`SIGINT` and `SIGTERM` dispose the headless host, close server plugins, stop the direct runtime, close the listener, and release history ownership. A normal stop leaves the v4 session journal available for a later server.
 
-If startup fails while composing a scope or loading a required facet, no ready listener is published. Treat a failed composition, failed required facet, or history ownership conflict as a readiness failure, not as permission to use another module set.
+If startup fails while composing a scope or loading a required server package, no ready listener is published. Treat a failed composition, failed required server package, or history ownership conflict as a readiness failure, not as permission to use another module set.
 
 ## Development
 

package/docs/server/index.md

@@ -35,9 +35,9 @@ The token is read from the file, not the command line. Keep the file private. A
 
 ## How it works
 
-Startup composes the global scope from configuration and imports the eligible server facets from their packages' built entries. It then creates the direct harness, session service, and package API handlers in process. The listener provides:
+Startup composes the global scope from configuration and imports the eligible server plugins from their packages' built entries. It then creates the direct harness, session service, and package API handlers in process. The listener provides:
 
-- `/api/ws`, an authenticated WebSocket carrying the Pi 0.85 Chord protocol;
+- `/api/ws`, an authenticated WebSocket carrying Chord 1.2 link frames;
 - `/api/health`, an unauthenticated readiness check;
 - `/api/workspaces/<workspace-id>/sessions` and related routes for discovery and channel access; and
 - session package APIs below `/api/workspaces/<workspace-id>/sessions/<session-id>/plugins/<base-path>/...`.
@@ -46,7 +46,7 @@ The Pi protocol exposes typed management, hub, and session services. Session cal
 
 ## Security
 
-The server binds to loopback by default and requires the token for every route except `/api/health`. A token file keeps the capability out of process listings. The server is not a sandbox: the harness, extensions, and server facets run with the account's authority.
+The server binds to loopback by default and requires the token for every route except `/api/health`. A token file keeps the capability out of process listings. The server is not a sandbox: the harness, extensions, and server plugins run with the account's authority.
 
 Po Web owns browser authentication, remote tunnels, device cookies, and passkeys. When it proxies a session, browser code does not need the server token. Do not publish the server listener without an authenticated boundary.
 
@@ -59,7 +59,7 @@ Read [Security and trust boundaries](security.md) before sharing a listener or t
 | [Getting started](getting-started.md) | Installation, options, live composition, and web integration      |
 | [Lifecycle](lifecycle.md)             | In-process startup, readiness, shutdown, and history ownership    |
 | [IPC](ipc.md)                         | The `/api/ws` protocol, typed operations, HTTP routes, and replay |
-| [Session APIs](api.md)                | `poServer` facets, package handlers, and TypeScript exports       |
+| [Session APIs](api.md)                | `poServer` plugins, package handlers, and TypeScript exports      |
 | [Security](security.md)               | Tokens, listener exposure, trusted code, and data boundaries      |
 
 ## License

package/docs/server/ipc.md

@@ -11,7 +11,7 @@ The canonical server has one client-neutral listener. It exposes HTTP routes and
           |                                     |
           v                                     v
    HTTP control surface                 /api/ws WebSocket
- health, sessions, APIs                Pi 0.85 Chord services
+ health, sessions, APIs                 Chord 1.3 objects
           |                                     |
           +------------------+------------------+
                              v
@@ -29,9 +29,6 @@ The server exposes these client-neutral routes:
 | `GET /api/health`                                                      | Unauthenticated readiness and session count |
 | `GET /api/workspaces/<workspace-id>/sessions`                          | Session metadata for the headless hub       |
 | `GET /api/workspaces/<workspace-id>/sessions/<id>`                     | One session's metadata                      |
-| `GET /api/events`                                                      | Server-sent session and channel events      |
-| `GET /api/workspaces/<workspace-id>/sessions/<id>/channels`            | Current channel projections                 |
-| `POST /api/workspaces/<workspace-id>/sessions/<id>/channel/<type>`     | Deliver a channel operation                 |
 | `/api/workspaces/<workspace-id>/sessions/<id>/plugins/<base-path>/...` | Dispatch a session package API in process   |
 
 All routes other than health require the configured token. HTTP clients should send `Authorization: Bearer <token>` or `x-po-token`. The WebSocket may use the same capability in its authorization header or query string; avoid query strings when a header is available because URLs can be logged.
@@ -40,13 +37,12 @@ The old raw command route is not part of this surface. Session control uses the
 
 ## `/api/ws` protocol
 
-`/api/ws` carries the Pi 0.85 byte protocol over an already-authenticated WebSocket. The server hosts the stable cockpit server identity and publishes these typed services:
+`/api/ws` carries Chord 1.3 (link protocol v4) frames, one JSON text message each, over an already-authenticated WebSocket. Each socket is a client link stamped with its own connection principal. The server host is named `server` and serves these remote contracts:
 
-- `po.hub.v1` lists sessions, subscribes to channel events, and sends typed channel operations;
-- `po.session-management.v1` attaches and detaches a session; and
-- `po.session.v1` exposes one session's state and operations.
+- `po.hub` (input `{}`) lists sessions, subscribes to channel events, sends typed channel operations, reads Home, and invokes plugin methods; and
+- `po.session` (input `{ sessionId }`) exposes one session's `state` and operations, plus `alive`, which turns false when the runtime behind it exits.
 
-A client first attaches through the management service, then binds the session service for that session. The service boundary is typed even though the transport carries protocol bytes.
+A client holds `po.session` for the session it shows. Every connection shares one projected runtime per session; the server checks the connection's scope and Desktop ownership before resolving the object and on every call. Clients use `attachHub` and `attachSession` from `@agimon-ai/po-core/sessionProtocol`.
 
 ## Typed session operations
 
@@ -72,7 +68,7 @@ The hub's session and channel event history is also bounded to 1,024 events. The
 
 ## Session package APIs
 
-A package API is registered by a server facet and called through the in-process `Request` adapter. The listener strips `/api/workspaces/<workspace-id>/sessions/<id>/plugins/<base-path>` before invoking the handler, so a request to `/api/workspaces/<workspace-id>/sessions/one/plugins/runner/runs/r1/log` reaches the `runner` handler as `/runs/r1/log`.
+A package API is registered by a server plugin and called through the in-process `Request` adapter. The listener strips `/api/workspaces/<workspace-id>/sessions/<id>/plugins/<base-path>` before invoking the handler, so a request to `/api/workspaces/<workspace-id>/sessions/one/plugins/runner/runs/r1/log` reaches the `runner` handler as `/runs/r1/log`.
 
 Package handlers run with the session's trusted host context. They still validate request bodies, bound reads and streams, constrain paths, and avoid returning secrets merely because the caller passed the listener token.
 
@@ -94,4 +90,4 @@ Workspace settings are at `/api/workspaces/<workspace-id>/settings`. Create or a
 
 The global socket retains the aggregate hub protocol used by Po Web. Workspace sockets expose only sessions in that workspace; session sockets expose only the named session. Both restrict session attachments, subscriptions, thread reads, and package calls to their addressed scope. All transports use the same Pi/Chord framing. Old flat session routes, singular plugin mounts, and `/api/pi` are removed without aliases.
 
-Startup loads global facets from the global root's live composition, workspace facets when that workspace is admitted, and session facets from the owning workspace's composition with the session's selection. REST requests dispatch only to that mount; there is no fallback to another scope.
+Startup loads global packages from the global root's live composition, workspace packages when that workspace is admitted, and session packages from the owning workspace's composition with the session's selection. REST requests dispatch only to that mount; there is no fallback to another scope.

package/docs/server/lifecycle.md

@@ -2,7 +2,7 @@
 
 Package hooks follow the [plugin lifecycle contract](../../../po-core/docs/plugins.md): register, `onStart`, `onStop`, unregister, and `onDispose`. Server readiness waits for required plugin startup; browser reconnects do not restart those plugins.
 
-`po-server` owns one session boundary from startup through shutdown. The Pi harness, session services, package facets, and listener live in the same process. A client can disconnect without stopping the runtime, and a later client can recover the current replicated state.
+`po-server` owns one session boundary from startup through shutdown. The Pi harness, session services, server plugins, and listener live in the same process. A client can disconnect without stopping the runtime, and a later client can recover the current replicated state.
 
 ## The ownership model
 
@@ -12,7 +12,7 @@ po-server process
   +-- session manager and headless hub
   +-- DirectHarnessRuntime
   +-- typed management and session services
-  +-- package facet host and in-process API handlers
+  +-- server plugin host and in-process API handlers
   +-- HTTP and WebSocket listener, including /api/ws
   +-- v4 JSONL session journal
 ```
@@ -21,7 +21,7 @@ The server, not a client, owns runtime disposal and history ownership. This give
 
 ## Startup is readiness-ordered
 
-The server publishes the listener only after the runtime and required facets are ready:
+The server publishes the listener only after the runtime and required server packages are ready:
 
 ```text
 parse options and identity
@@ -30,13 +30,13 @@ parse options and identity
 read token and compose the global scope from configuration
           |
           v
-import eligible facets from built package entries
+import eligible server plugins from built package entries
           |
           v
 create DirectHarnessRuntime and prepare the headless host
           |
           v
-activate facets and initialize typed session services
+activate server packages and initialize typed session services
           |
           v
 bind HTTP and /api/ws
@@ -52,7 +52,7 @@ The executable performs these steps:
 3. Resolve session identity and harness options from the caller's repository.
 4. Compose the scope from configuration, collect the selected packages' `poServer` entries, check that each built entry stays inside its package, and filter by ownership and scope before importing modules through their content-addressed URLs.
 5. Create the direct runtime with explicit history ownership, model configuration, session identity, and working directory.
-6. Prepare and activate the selected server facets. Required failures stop readiness; optional failures are reported and isolated.
+6. Prepare and activate the selected server packages. Required failures stop readiness; optional failures are reported and isolated.
 7. Mount in-process package API handlers and initialize the typed session projection.
 8. Bind the loopback HTTP listener and authenticated `/api/ws` WebSocket endpoint.
 
@@ -62,14 +62,14 @@ A startup error is written to stderr with a `[po-server]` prefix and exits non-z
 
 Once ready, the server holds a stable session boundary:
 
-| Owned resource                     | Lifetime                         |
-| ---------------------------------- | -------------------------------- |
-| Session ID and name                | Whole server process             |
-| Direct harness runtime             | Whole server process             |
-| Typed session state and operations | Whole server process             |
-| Package facet registrations        | Until shutdown or facet disposal |
-| HTTP and `/api/ws` listener        | Whole server process             |
-| Session journal ownership          | Whole server process             |
+| Owned resource                     | Lifetime                          |
+| ---------------------------------- | --------------------------------- |
+| Session ID and name                | Whole server process              |
+| Direct harness runtime             | Whole server process              |
+| Typed session state and operations | Whole server process              |
+| Server plugin registrations        | Until shutdown or plugin disposal |
+| HTTP and `/api/ws` listener        | Whole server process              |
+| Session journal ownership          | Whole server process              |
 
 The session service projects runtime activity into an authoritative snapshot, transient progress, concurrent in-flight items, and bounded presentation events. A client does not need to remain connected for the runtime to update the journal.
 
@@ -83,16 +83,16 @@ Live presentation events are bounded to 1,024 events or 8 MiB. The state reports
 
 This is recovery state, not an audit log. Clients that need authoritative transcript or configuration data should use the typed snapshot and query operations. A client must not infer missing history from the bounded presentation window.
 
-## Package facet changes
+## Server package changes
 
-Each facet is imported through a URL that changes with its package content. Rebuilding or upgrading a package does not mutate a running session: the next new session imports the new build. Global and workspace scopes are checked again when a session opens or a workspace is admitted, and remount when an entry changed; a failed remount restores the previous facets. After a set number of superseded package versions, the server restarts at the next idle moment so old modules do not accumulate. During shutdown, facet disposers run before the host and runtime release their resources.
+Each server plugin is imported through a URL that changes with its package content. Rebuilding or upgrading a package does not mutate a running session: the next new session imports the new build. Global and workspace scopes are checked again after a watched package change, a finished sync, or a package install or removal, and reinstall only what changed: an unchanged package is skipped, a changed one is disposed and its new build applied, and a new build that fails restores the previous one. A package that is no longer selected stays installed. After a set number of superseded package versions, the server restarts at the next idle moment so old modules do not accumulate. During shutdown, plugin disposers run before the host and runtime release their resources.
 
 ## Shutdown and failures
 
 `SIGINT`, `SIGTERM`, runtime exit, and explicit disposal all disable new operations and release resources in ownership order:
 
 1. stop accepting new package and session operations;
-2. close active facet registrations and package handlers;
+2. close active plugin registrations and package handlers;
 3. stop the headless host and pending extension interactions;
 4. close the typed service projection and direct runtime;
 5. release history ownership and close the JSONL repository;