@tequila99/githuman 0.11.2 → 0.13.0

package/README.md

@@ -22,6 +22,9 @@ staged/unstaged diff, сравнение веток и коммитов, бра
 - Чаты с ACP-агентами (Claude Code, Cursor, Codex, pi): до 5 чатов во
   вкладках, контекст — diff, файл целиком, ревью, вложения и `@`-файлы и папки из
   репозитория. Подробнее — в разделе «Агенты» ниже.
+- Раздел **Artifacts**: неизменяемые Markdown-документы, поиск и справочники,
+  комментарии по строкам и редакциям, проверка и подтверждение принятия,
+  контекст документов в чате и экспорт оригинала/истории.
 - Ручной/авто выбор тёмной-светлой темы.
 - CLI: `serve` (поднять сервер), `list`/`export` (быстрый доступ к
   сохранённым ревью без веб-интерфейса).
@@ -130,8 +133,34 @@ Tailscale) разрешается флагом `--allowed-host <имя>`, его
 - **Подтверждения.** Запросы разрешений приходят карточкой в чат. Для
   отдельного чата можно включить автоподтверждение (кнопка-щит) — агент
   тогда меняет файлы и выполняет команды без вашего ответа; включайте его
-  только для работы, которую готовы проверить и откатить. pi вообще не
-  спрашивает.
+  только для работы, которую готовы проверить и откатить. Native tools pi
+  выполняются без ACP-подтверждений; его MCP-вызовы требуют разрешения.
+- **Артефакты через MCP.** Агенты внутри работающего GitHuman получают
+  инструменты создания неизменяемых черновиков, чтения содержимого и истории,
+  просмотра связей, работы с задачами и типами, [поиска с опечатками](docs/artifact-search.md).
+  Проверены Claude Code и штатный локальный мост pi; остальные
+  ACP-пресеты пока не проверены на поддержку этих инструментов.
+  Самостоятельный MCP без GitHuman не поддерживается. Раздел Artifacts показывает
+  документы и позволяет подтверждать точные предложения агента. Статус документа
+  меняется кнопкой в шапке: одно «Да» запускает проверку и применение на сервере;
+  принятие документов требует проверки и пользовательского разрешения;
+  [жизненный цикл и API](docs/artifact-lifecycle.md).
+  Ревью артефактов отложено; обсуждения и блокирующие замечания удалены.
+- **Локальный мост pi** — в пакет включена команда
+  `githuman pi-acp --stdio`, использующая установленный pi, его авторизацию
+  и выбор моделей. MCP-вызовы проходят отдельное ACP-подтверждение;
+  валидатор получает серверный профиль с запретом native tools. Штатный
+  preset использует этот мост без runtime npx и подбора внешнего адаптера.
+  Явные пользовательские command/args overrides сохраняются. Для ручной
+  проверки нужен авторизованный pi с настроенной моделью.
+  При аварийном падении/SIGKILL pi запущенные native shell-команды могут
+  продолжить работу после закрытия чата. Очистка таких процессов — best effort;
+  это явно принятое ограничение обычного чата, не ослабление MCP-подтверждений.
+  Валидация через прежнюю или произвольную команду pi недоступна.
+  Проверки выполняются на Linux; macOS-проверки пропущены по поручению
+  пользователя, поддержка macOS не подтверждена. Windows не поддерживается.
+  Подробное руководство по MCP-интеграции: [русский](docs/pi-mcp-integration.md) ·
+  [English](docs/pi-mcp-integration.en.md).
 - **Свои команды запуска** — `<репозиторий>/.githuman/ght-agents.json`:
   `{ "cursor": { "args": ["--model", "<модель>", "acp"] } }`. Допустимы поля
   `command`, `args`, `env`; любое другое (в том числе опечатка) — ошибка
@@ -168,6 +197,18 @@ node dist/cli/index.js list --db-prefix ""         # .githuman/reviews.db (ор
 `--api-docs` (`pnpm run dev:server` включает его сам). Агентские маршруты
 попадают в спецификацию, только когда сервер их отдаёт (loopback-хост).
 
+### Отладка валидации артефактов
+
+`githuman serve --debug-validation` не закрывает сессию валидатора после
+завершения проверки и пишет в консоль сервера строки `[validation <id>]`:
+статусы сессии, вызовы инструментов, решения политики прав (ALLOW/DENY с
+причиной), причину завершения. Текст вывода инструментов обрезается до 500
+символов. Флаг нужен для отладки: в обычном режиме сессия закрывается, а
+причина остановки валидатора нигде не сохраняется. Оставленная открытой
+сессия не занимает место в лимите чатов: новый чат закрывает самую старую
+завершённую сессию валидатора. Ключ артефактной сессии такого валидатора
+отзывается сразу при завершении проверки.
+
 ## Разработка
 
 Два процесса нужны одновременно — backend (Fastify, автоперезапуск при
@@ -245,6 +286,37 @@ MIT, см. [LICENSE](LICENSE).
 
 Для разработки на другом порту backend можно передать `GITHUMAN_DEV_API=http://localhost:3848` при запуске Quasar dev-сервера.
 
+## Артефакты
+
+Раздел **Artifacts** хранит неизменяемые Markdown-документы, созданные агентом
+через MCP. Каталог поддерживает обычный поиск и поиск с опечатками, фильтры по
+статусу, типу, задаче и тегу и группировку загруженных результатов; порядок
+фиксирован (новые сверху), переключателя сортировки нет. Документ показывается
+как Markdown; редактирования body и режима Source нет. Обсуждения, комментарии и
+блокирующие замечания удалены (ADR 0097). Кнопка добавления в чат прикладывает
+контекст документа; задачи чата назначаются через Tasks в панели чата.
+
+Статус документа меняется кнопкой в шапке: меню показывает только допустимые
+переходы, диалог — точные последствия и выбор валидатора. Одно «Да» запускает на
+сервере проверку независимым валидатором и применение при свежем pass; повторного
+подтверждения нет, работа продолжается после закрытия вкладки и показывает
+стадию, отмену и результат проверки. Это отдельный путь от MCP/API жизненного
+цикла (`change_sets`, `actions`, `validations`), где агент запрашивает действие
+и использует выданное пользователем разрешение; очереди таких запросов в
+интерфейсе нет. Подробности и ограничения — в
+[жизненном цикле](docs/artifact-lifecycle.md) и
+[матрице возможностей](docs/artifact-capabilities.md).
+
+Если текст документа не читается (повреждённый или недоступный файл), метаданные,
+история, связи и выгрузка JSON остаются доступны, а тело заменяется ошибкой с
+кнопкой «Retry»; оригинал при повреждении не выгружается. Исходный путь
+импорта (`sourcePath`), если он есть, показан в метаданных как обычный текст.
+
+Download artifact выгружает точный оригинал с историческим frontmatter либо
+JSON актуальных метаданных и полной истории. Текущие метаданные и исходный
+frontmatter показаны отдельно. История и файлы сохраняются в `.githuman/`;
+существующие Markdown-файлы репозитория автоматически не импортируются.
+
 ## Проектные заметки
 
 Раздел **Notes** хранит Markdown-заметки в `.githuman/notes/` относительно

package/dist/cli/commands/mcp.js

@@ -0,0 +1,112 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { Value } from '@sinclair/typebox/value';
+import { ARTIFACT_TASK_INSTRUCTIONS } from "../../shared/artifact-tools/instructions.js";
+import { ARTIFACT_TOOL_DESCRIPTIONS } from "../../shared/artifact-tools/descriptions.js";
+import { ArtifactToolSchemas } from "../../shared/artifact-tools/schemas.js";
+import { ARTIFACT_AGENT_KEY_ENV, ARTIFACT_AGENT_KEY_PATTERN, ARTIFACT_AGENT_URL_ENV, ARTIFACT_BRIDGE_PATH_PREFIX, ARTIFACT_MCP_MAX_MESSAGE_BYTES } from "../../shared/artifacts/mcp-constants.js";
+import { isRecord } from "../../shared/utils/guards.js";
+import { getAppVersion } from "../../server/app-version.js";
+// Fail boundedly when serve disappears; retries use the original request ID.
+const REQUEST_TIMEOUT_MS = 30_000;
+// MCP tool names allow no dots, so operation names map dots to underscores.
+const TOOLS = new Map(Object.entries(ArtifactToolSchemas).map(([operation, schema]) => [
+    operation.replaceAll('.', '_'),
+    {
+        operation,
+        schema,
+        description: ARTIFACT_TOOL_DESCRIPTIONS[operation] ?? schema.description
+    }
+]));
+function toolError(text) {
+    return { isError: true, content: [{ type: 'text', text }] };
+}
+export async function runMcp(argv) {
+    if (argv.length !== 1 || argv[0] !== '--stdio') {
+        throw new Error('Usage: githuman mcp --stdio');
+    }
+    const endpoint = process.env[ARTIFACT_AGENT_URL_ENV];
+    const key = process.env[ARTIFACT_AGENT_KEY_ENV];
+    if (!endpoint || !key || !ARTIFACT_AGENT_KEY_PATTERN.test(key)) {
+        throw new Error('Artifact MCP requires a running GitHuman agent session.');
+    }
+    const url = new URL(endpoint);
+    if (url.protocol !== 'http:' ||
+        url.username ||
+        url.password ||
+        url.pathname !== '/' ||
+        url.search ||
+        url.hash) {
+        throw new Error('Invalid GitHuman server address.');
+    }
+    const server = new Server({ name: 'githuman-artifacts', version: getAppVersion() }, { capabilities: { tools: {} }, instructions: ARTIFACT_TASK_INSTRUCTIONS });
+    const active = new AbortController();
+    server.setRequestHandler(ListToolsRequestSchema, () => ({
+        tools: [...TOOLS].map(([name, { schema, description }]) => ({
+            name,
+            description,
+            inputSchema: { ...schema, type: 'object' }
+        }))
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+        const tool = TOOLS.get(request.params.name);
+        if (!tool) {
+            return toolError(`Unknown artifact tool "${request.params.name}".`);
+        }
+        const args = request.params.arguments ?? {};
+        // The message names the field and the rule, never the rejected value.
+        const invalid = Value.Errors(tool.schema, args).First();
+        if (invalid) {
+            return toolError(`Invalid parameters for ${request.params.name}: ${invalid.path || '/'} ${invalid.message}.`);
+        }
+        let response;
+        try {
+            response = await fetch(new URL(`${ARTIFACT_BRIDGE_PATH_PREFIX}${tool.operation}`, url), {
+                method: 'POST',
+                redirect: 'error',
+                headers: {
+                    authorization: `Bearer ${key}`,
+                    'content-type': 'application/json'
+                },
+                body: JSON.stringify(args),
+                signal: AbortSignal.any([
+                    active.signal,
+                    extra.signal,
+                    AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+                ])
+            });
+        }
+        catch (error) {
+            const name = error instanceof Error ? error.name : '';
+            return toolError(name === 'TimeoutError' || name === 'AbortError'
+                ? 'The GitHuman artifact request timed out or was cancelled.'
+                : 'GitHuman artifact server is unavailable.');
+        }
+        let result;
+        try {
+            result = await response.json();
+        }
+        catch {
+            result = undefined;
+        }
+        if (!isRecord(result)) {
+            return toolError(`GitHuman artifact server returned an unreadable response (HTTP ${response.status}).`);
+        }
+        return {
+            isError: !response.ok,
+            content: [{ type: 'text', text: JSON.stringify(result) }],
+            structuredContent: result
+        };
+    });
+    const transport = new StdioServerTransport(undefined, undefined, {
+        maxBufferSize: ARTIFACT_MCP_MAX_MESSAGE_BYTES
+    });
+    // oxlint-disable-next-line unicorn/prefer-add-event-listener -- MCP SDK exposes a callback property, not EventTarget
+    server.onclose = () => active.abort();
+    process.stdin.once('end', () => {
+        active.abort();
+        void server.close();
+    });
+    await server.connect(transport);
+}

package/dist/cli/commands/pi-acp.js

@@ -0,0 +1,21 @@
+import * as acp from '@agentclientprotocol/sdk';
+import { Readable, Writable } from 'node:stream';
+import { createPiAgent } from "../../server/adapters/pi-acp/agent.js";
+export function runPiAcp(argv) {
+    if (argv.length !== 1 || argv[0] !== '--stdio') {
+        throw new Error('Usage: githuman pi-acp --stdio');
+    }
+    const profile = process.env.GITHUMAN_PI_PROFILE ?? 'chat';
+    if (profile !== 'chat' && profile !== 'validator') {
+        throw new Error('Invalid trusted pi launch profile');
+    }
+    const agent = createPiAgent(profile);
+    agent.connect(acp.ndJsonStream(Writable.toWeb(process.stdout), 
+    // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- Node and DOM streams have equivalent runtime contracts.
+    Readable.toWeb(process.stdin)));
+    const shutdown = () => {
+        agent.close();
+    };
+    process.once('SIGTERM', shutdown);
+    process.once('SIGINT', shutdown);
+}

package/dist/cli/config.js

@@ -1,5 +1,7 @@
+import { DEFAULT_DB_PREFIX } from "../shared/app/storage-constants.js";
 import { isIP } from 'node:net';
 import { parseArgs } from 'node:util';
+import { isValidFilenamePrefix } from "../shared/utils/is-valid-filename-prefix.js";
 import { isLoopbackHost } from "../shared/network/loopback.js";
 import { WILDCARD_HOSTS } from "../server/utils/lan-addresses.js";
 const DEFAULT_PORT = 3847;
@@ -13,7 +15,7 @@ const HOST_NAME_PATTERN = /^(?=.{1,253}$)[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:
  * without a prefix, running both tools against the same repository would
  * silently corrupt or crash on the other tool's database file.
  */
-export const DEFAULT_DB_PREFIX = 'ght-';
+export { DEFAULT_DB_PREFIX };
 /**
  * `GITHUMAN_DB_PREFIX` is intentionally not one of the env vars the original
  * mcollina/githuman CLI reads (`GITHUMAN_DB_PATH`, `GITHUMAN_TOKEN`), so
@@ -86,6 +88,7 @@ export function parseServeArgs(argv) {
             'notes-dir': { type: 'string' },
             'db-prefix': { type: 'string' },
             'api-docs': { type: 'boolean', default: false },
+            'debug-validation': { type: 'boolean', default: false },
             'allowed-host': { type: 'string', multiple: true }
         },
         strict: false
@@ -94,7 +97,12 @@ export function parseServeArgs(argv) {
     const host = resolveHost(typeof values.host === 'string' ? values.host : undefined);
     const open = values['no-open'] === true ? false : values.open !== false;
     const dbPrefix = resolveDbPrefix(typeof values['db-prefix'] === 'string' ? values['db-prefix'] : undefined);
+    // Only `serve` creates artifact files, so only it needs a filename-safe prefix.
+    if (!isValidFilenamePrefix(dbPrefix)) {
+        throw new Error(`Invalid --db-prefix value "${dbPrefix}": use at most 100 characters and none of < > : " / \\ | ? * or control characters. Set it with --db-prefix or GITHUMAN_DB_PREFIX.`);
+    }
     const apiDocs = values['api-docs'] === true;
+    const debugValidation = values['debug-validation'] === true;
     const allowedHosts = resolveAllowedHosts(Array.isArray(values['allowed-host']) ? values['allowed-host'] : []);
     return {
         port,
@@ -102,6 +110,7 @@ export function parseServeArgs(argv) {
         open,
         dbPrefix,
         apiDocs,
+        debugValidation,
         allowedHosts,
         ...(typeof values['notes-dir'] === 'string'
             ? { notesDir: values['notes-dir'] }

package/dist/cli/index.js

@@ -1,18 +1,13 @@
 #!/usr/bin/env node
 import { errorMessage } from "../shared/utils/error-message.js";
 import { writeFileSync } from 'node:fs';
-import { parseServeArgs } from "./config.js";
-import { startServer, resolveRepositoryPath, resolveReviewsDbPath } from "./server-runtime.js";
-import { formatStartupMessage } from "./startup-message.js";
-import { lanAddresses } from "../server/utils/lan-addresses.js";
-import { parseListArgs, runList } from "./commands/list.js";
-import { parseExportArgs, runExport } from "./commands/export.js";
-import { createFileDatabase } from "../server/db/index.js";
 import { getAppVersion } from "../server/app-version.js";
 // Force exit when a graceful close hangs. It must exceed the terminal kill time: ps timeout plus grace.
 const SHUTDOWN_TIMEOUT_MS = 5000;
 /** Opens the reviews DB for the repo at cwd, shared by `list` and `export`. */
 async function openReviewsDb(dbPrefix) {
+    const { resolveRepositoryPath, resolveReviewsDbPath } = await import("./server-runtime.js");
+    const { createFileDatabase } = await import("../server/db/index.js");
     const repositoryPath = await resolveRepositoryPath(process.cwd());
     return {
         db: createFileDatabase(resolveReviewsDbPath(repositoryPath, dbPrefix)),
@@ -20,10 +15,24 @@ async function openReviewsDb(dbPrefix) {
     };
 }
 async function main(argv) {
+    if (argv[0] === 'pi-acp') {
+        const { runPiAcp } = await import("./commands/pi-acp.js");
+        runPiAcp(argv.slice(1));
+        return;
+    }
+    if (argv[0] === 'mcp') {
+        const { runMcp } = await import("./commands/mcp.js");
+        await runMcp(argv.slice(1));
+        return;
+    }
     console.log(`githuman v${getAppVersion()}`);
     const [command, ...rest] = argv;
     switch (command) {
         case 'serve': {
+            const { parseServeArgs } = await import("./config.js");
+            const { startServer } = await import("./server-runtime.js");
+            const { formatStartupMessage } = await import("./startup-message.js");
+            const { lanAddresses } = await import("../server/utils/lan-addresses.js");
             const options = parseServeArgs(rest);
             const { app, url } = await startServer(options);
             let stopping = false;
@@ -52,12 +61,14 @@ async function main(argv) {
             return;
         }
         case 'list': {
+            const { parseListArgs, runList } = await import("./commands/list.js");
             const options = parseListArgs(rest);
             const { db } = await openReviewsDb(options.dbPrefix);
             console.log(runList(db, options));
             return;
         }
         case 'export': {
+            const { parseExportArgs, runExport } = await import("./commands/export.js");
             const options = parseExportArgs(rest);
             const { db, repositoryPath } = await openReviewsDb(options.dbPrefix);
             const output = await runExport(db, options.id, options.format, repositoryPath);
@@ -71,7 +82,7 @@ async function main(argv) {
         }
         default:
             console.error(`Unknown command: ${command ?? '(none)'}`);
-            console.error('Usage: githuman serve|list|export [options]');
+            console.error('Usage: githuman serve|list|export|mcp|pi-acp [options]');
             process.exitCode = 1;
     }
 }

package/dist/cli/server-runtime.js

@@ -66,8 +66,13 @@ export async function startServer(options) {
         projectPath: process.cwd(),
         notesDir: options.notesDir,
         db,
+        artifactPrefix: resolveDbPrefix(options.dbPrefix),
         watchFiles: true,
         apiDocs: options.apiDocs === true,
+        // The server logs are off; validation debug lines go to the console.
+        ...(options.debugValidation === true
+            ? { onValidationDebug: (line) => console.log(line) }
+            : {}),
         allowedHosts: options.allowedHosts ?? [],
         onPairingRequest: device => console.log(`Pairing request from ${device.name} (${device.address}). Enter the code from the device in a localhost tab.`),
         terminalEnabled: true,

package/dist/server/adapters/agents/artifact-permission.js

@@ -0,0 +1,88 @@
+import { ArtifactToolSchemas } from "../../../shared/artifact-tools/schemas.js";
+import { ARTIFACT_MCP_SERVER_NAME } from "../../../shared/artifacts/mcp-constants.js";
+import { isRecord } from "../../../shared/utils/guards.js";
+// MCP names replace operation dots with underscores on the stdio bridge.
+const OPERATIONS = new Map(Object.entries(ArtifactToolSchemas).map(([operation, schema]) => [
+    operation.replaceAll('.', '_'),
+    { operation, schema }
+]));
+// Claude's qualified name binds an operation to the configured server.
+const CLAUDE_PREFIX = `mcp__${ARTIFACT_MCP_SERVER_NAME}__`;
+export function artifactPermissionCall(request, previous, presetId) {
+    const call = request.toolCall;
+    const pi = call['_meta']?.githumanPi;
+    if (pi !== undefined &&
+        (!isRecord(pi) ||
+            pi.server !== ARTIFACT_MCP_SERVER_NAME ||
+            pi.registryGeneration !== 1 ||
+            call.name !== `${CLAUDE_PREFIX}${String(pi.tool)}`)) {
+        return undefined;
+    }
+    const claude = call['_meta']?.claudeCode;
+    const metadataName = isRecord(claude) ? claude.toolName : undefined;
+    const name = call.name ?? metadataName;
+    if (name !== undefined) {
+        if (typeof name !== 'string' || !name.startsWith(CLAUDE_PREFIX)) {
+            return undefined;
+        }
+        if (metadataName !== undefined && metadataName !== name)
+            return undefined;
+        if (previous?.name !== undefined &&
+            previous.name !== null &&
+            previous.name !== name) {
+            return undefined;
+        }
+        if (isRecord(claude) && claude.mcpServer !== undefined) {
+            if (!isRecord(claude.mcpServer) ||
+                claude.mcpServer.name !== ARTIFACT_MCP_SERVER_NAME) {
+                return undefined;
+            }
+        }
+        const operation = OPERATIONS.get(name.slice(CLAUDE_PREFIX.length));
+        return operation ? { ...operation, input: call.rawInput } : undefined;
+    }
+    // Cursor supplies MCP identity in the correlated tool update, not the permission card.
+    if (presetId === 'cursor' && call.kind === 'other') {
+        if (call.rawInput !== undefined ||
+            request['_meta']?.is_mcp_tool_approval !== undefined ||
+            !previous ||
+            previous.toolCallId !== call.toolCallId ||
+            previous.kind !== 'other' ||
+            (previous.name !== undefined && previous.name !== null)) {
+            return undefined;
+        }
+        const input = previous.rawInput;
+        if (!isRecord(input) ||
+            input.providerIdentifier !== ARTIFACT_MCP_SERVER_NAME ||
+            typeof input.toolName !== 'string' ||
+            !isRecord(input.args) ||
+            Object.keys(input).some(key => !['providerIdentifier', 'toolName', 'args'].includes(key))) {
+            return undefined;
+        }
+        const operation = OPERATIONS.get(input.toolName);
+        return operation ? { ...operation, input: input.args } : undefined;
+    }
+    // Codex omits call details only for a correlated MCP approval, not an elicitation.
+    if (request['_meta']?.is_mcp_tool_approval !== true ||
+        call.rawInput !== undefined ||
+        call.kind !== 'execute') {
+        return undefined;
+    }
+    if (!previous ||
+        previous.toolCallId !== call.toolCallId ||
+        previous.kind !== 'execute' ||
+        (previous.name !== undefined && previous.name !== null)) {
+        return undefined;
+    }
+    const input = previous.rawInput;
+    if (!isRecord(input) ||
+        input.server !== ARTIFACT_MCP_SERVER_NAME ||
+        typeof input.tool !== 'string') {
+        return undefined;
+    }
+    if (Object.keys(input).some(key => !['server', 'tool', 'arguments'].includes(key))) {
+        return undefined;
+    }
+    const operation = OPERATIONS.get(input.tool);
+    return operation ? { ...operation, input: input.arguments } : undefined;
+}

package/dist/server/adapters/pi-acp/agent.js

@@ -0,0 +1,98 @@
+import { errorMessage } from "../../../shared/utils/error-message.js";
+import * as acp from '@agentclientprotocol/sdk';
+import { PiSession } from "./session.js";
+export function createPiAgent(profile) {
+    let session;
+    let used = false;
+    let connection;
+    const app = acp
+        .agent({ name: 'githuman-pi' })
+        .onRequest(acp.methods.agent.initialize, () => ({
+        protocolVersion: acp.PROTOCOL_VERSION,
+        agentCapabilities: {
+            promptCapabilities: { image: true, embeddedContext: true },
+            mcpCapabilities: { http: false, sse: false },
+            loadSession: false
+        }
+    }))
+        .onRequest(acp.methods.agent.session.new, async (ctx) => {
+        if (used) {
+            throw new acp.RequestError(-32602, 'One pi bridge process supports exactly one session/new');
+        }
+        used = true;
+        session = new PiSession(profile, {
+            update: (sessionId, update) => ctx.client.notify(acp.methods.client.session.update, {
+                sessionId,
+                update
+            }),
+            permission: (request, signal) => ctx.client.request(acp.methods.client.session.requestPermission, request, { cancellationSignal: signal }),
+            failure: () => connection?.close(new Error('Pi bridge runtime or MCP failed'))
+        });
+        try {
+            await session.start(ctx.params.cwd, ctx.params.mcpServers);
+        }
+        catch (error) {
+            throw new acp.RequestError(-32000, errorMessage(error), {
+                githumanBridge: { version: 1, profile, phase: 'startup' }
+            });
+        }
+        return {
+            sessionId: session.id,
+            configOptions: session.config,
+            _meta: {
+                githumanBridge: { version: 1, profile, registryGeneration: 1 }
+            }
+        };
+    })
+        .onRequest(acp.methods.agent.session.prompt, async (ctx) => {
+        if (!session) {
+            throw new acp.RequestError(-32602, 'Pi session has not been created');
+        }
+        session.assertSession(ctx.params.sessionId);
+        try {
+            return await session.prompt(ctx.params.prompt);
+        }
+        catch (error) {
+            throw new acp.RequestError(-32000, errorMessage(error), {
+                githumanBridge: { version: 1, profile, phase: 'prompt' }
+            });
+        }
+    })
+        .onNotification(acp.methods.agent.session.cancel, async (ctx) => {
+        if (!session) {
+            throw new acp.RequestError(-32602, 'Pi session has not been created');
+        }
+        session.assertSession(ctx.params.sessionId);
+        await session.cancel();
+    })
+        .onRequest(acp.methods.agent.session.setMode, async (ctx) => {
+        if (!session) {
+            throw new acp.RequestError(-32602, 'Pi session has not been created');
+        }
+        session.assertSession(ctx.params.sessionId);
+        await session.setConfig('thought_level', ctx.params.modeId);
+        return {};
+    })
+        .onRequest(acp.methods.agent.session.setConfigOption, async (ctx) => {
+        if (!session) {
+            throw new acp.RequestError(-32602, 'Pi session has not been created');
+        }
+        session.assertSession(ctx.params.sessionId);
+        if (typeof ctx.params.value !== 'string') {
+            throw new acp.RequestError(-32602, 'Invalid pi setting');
+        }
+        await session.setConfig(ctx.params.configId, ctx.params.value);
+        return { configOptions: session.config };
+    });
+    return {
+        connect(stream) {
+            connection = app.connect(stream);
+            void connection.closed.then(() => session?.close());
+            return connection;
+        },
+        close() {
+            session?.close();
+            connection?.close();
+        }
+    };
+}

package/dist/server/adapters/pi-acp/compatibility.js

@@ -0,0 +1,57 @@
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+// Probe only flags needed for isolation. Do not infer capabilities from semver.
+const REQUIRED_FLAGS = [
+    '--mode',
+    '--no-session',
+    '--no-extensions',
+    '--no-skills',
+    '--no-prompt-templates',
+    '--no-themes',
+    '--no-context-files',
+    '--no-builtin-tools',
+    '--offline'
+];
+// Bound runtime discovery before opening a session.
+const PROBE_TIMEOUT_MS = 10000;
+const execute = promisify(execFile);
+export async function piLaunchArgs(command, profile, extension) {
+    if (process.platform !== 'linux' && process.platform !== 'darwin') {
+        throw new Error('Pi bridge requires Linux or macOS (macOS verification was skipped).');
+    }
+    let help;
+    const probeDir = await mkdtemp(join(tmpdir(), 'githuman-pi-probe-'));
+    try {
+        const result = await execute(command, ['--help'], {
+            cwd: probeDir,
+            env: {
+                PATH: process.env.PATH,
+                HOME: probeDir,
+                PI_CODING_AGENT_DIR: probeDir,
+                PI_OFFLINE: '1'
+            },
+            timeout: PROBE_TIMEOUT_MS,
+            maxBuffer: 256 * 1024
+        });
+        help = result.stdout;
+    }
+    catch {
+        throw new Error('Pi bridge could not probe the installed pi executable.');
+    }
+    finally {
+        await rm(probeDir, { recursive: true, force: true });
+    }
+    if (REQUIRED_FLAGS.some(flag => !help.includes(flag))) {
+        throw new Error('Unsupported pi runtime: required RPC/isolation flags are missing. Control versions start at pi 0.81.0; install a compatible runtime.');
+    }
+    const args = ['--mode', 'rpc', '--no-session', '--no-themes', '-e', extension];
+    if (profile === 'validator') {
+        args.push('--no-extensions', '--no-skills', '--no-prompt-templates', '--no-context-files', '--no-builtin-tools', '--offline');
+        if (help.includes('--no-mcp'))
+            args.push('--no-mcp');
+    }
+    return args;
+}