Среда запуска Unified Harness

Стабильный релиз 0.9

Линейка gigaloom 0.9 добавляет work-first surface, ограниченный Thread Relay и точные route overlays для gpt2giga 0.3. Совместимость с provider CLI и явно помеченные preview API могут развиваться. Используйте документированные локальные и контролируемые границы, а не unattended multi-user сервис.

Unified Harness — локальный project cockpit поверх gpt2giga. В одном интерфейсе можно запустить задачу через прямой GigaChat, Codex CLI, Claude Code, Gemini CLI или plugin harness, сравнить результаты, разобрать ход выполнения и решить, какие изменения разрешено вернуть в проект.

В Web UI и человекочитаемом выводе CLI продукт называется GigaLoom. Дистрибутив и Python namespace называются gigaloom; единственная публичная console-команда — giga.

Визуальная идентичность и политика иконок

Знак GigaLoom с мотивом ткацкого станка — оригинальная графика проекта, он не скопирован из брендинга GigaChat и не является его производным. Канонический исходник находится в web/branding/gigaloom-mark.svg и распространяется на условиях лицензии репозитория. Команда node web/branding/generate-assets.mjs воспроизводит light, dark, mask, favicon, manifest, packaged-UI и documentation варианты.

Для Skills, Plugins и MCP используются курируемые локальные пиктограммы. Неизвестные интеграции получают детерминированную текстовую монограмму. GigaLoom не загружает удалённые иконки, поэтому показ каталога не выдаёт внешнему origin сетевые, tracking, SVG или content-права.

Это не ещё одна модель и не замена gateway или внешним CLI. Harness управляет ими как control plane и хранит локальную нормализованную историю запусков, approvals, артефактов и повторно используемой автоматизации.

Зачем это нужно

У разных agent CLI разные команды, история, режимы разрешений и форматы результатов. Unified Harness добавляет общий слой:

• один cockpit проекта — запуск из текущего репозитория через giga ui;
• повторяемые сценарии — agents, prompts, evals, workflows и schedules в .giga/ вместо ручной настройки каждой задачи;
• сравнение — одна задача для нескольких доступных harness в Arena;
• проверка до изменения — edit-запуски в изолированных Git worktree, а apply и создание branch — только после явного approval;
• прозрачность — durable status, attempts, redacted events, артефакты, diff и provenance доступны после перезапуска браузера или UI;
• локальный контроль — конфигурация и runtime-история остаются на машине пользователя.

Как связаны компоненты

Слой	За что отвечает
Gateway gpt2giga	Даёт HTTP API в форматах OpenAI, Anthropic и Gemini с GigaChat в роли backend.
Unified Harness	Выбирает harness и модель, координирует запуски, хранит историю и предоставляет CLI/UI.
Direct Chat или agent CLI	Выполняет саму модельную или агентную работу. Внешний CLI отвечает за поведение внутри собственного процесса.

Approval в Harness относится к действиям, которыми Harness действительно владеет: например, запуску процесса или применению сохранённого patch. Harness не обещает видеть каждое внутреннее действие непрозрачного Codex, Claude или Gemini subprocess.

Поверхности work-first и gateway в 0.9

Основная browser composition — Project -> Thread -> Run -> Evidence -> Action. Work показывает перед отправкой единую сводку route/model support, workspace, read-only Effective Instructions, authority и blockers; Inbox, Automations, Library и More показывают существующих владельцев без дублирования state.

Пять основных CLI-примеров:

giga --with gpt2giga --model GigaChat-2-Max codex
giga --route codex-gpt2giga-gigachat-2-max codex --help
giga session send THREAD_ID --text "review failing tests" --dry-run --json
giga schema agent
giga evidence product-beta --project PROJECT_ID --output report.json

Gateway selectors расположены до agent token и разрешают один immutable route без fallback. Dry-run Thread Relay читает bounded target projection и не выполняет mutation или provider call. Экспорт schemas и evidence — явные локальные операции. Полные контракты приведены в Work, потоках и контексте и интеграции с gateway.

Контракт префикса нативного CLI

Правило совместимости буквальное: добавьте ровно giga перед командой provider. Harness не вводит общий синтаксис выполнения.

giga codex exec --json "проверь репозиторий"
giga claude -p "проверь репозиторий"
giga gemini -p "проверь репозиторий"
giga pi "проверь репозиторий"

После имени provider argv непрозрачен для Harness. Нативными остаются --help/--version, stdin, stdout/stderr, сырые байты, JSON/JSONL, --, сигналы и exit status. Неизвестные новые команды и flags не ждут обновления парсера Harness.

Ситуация	Пример	Результат
Human TTY	giga codex	Реальный provider CLI владеет терминалом через direct или managed native launch.
Pipe/stdin	printf 'task' | giga claude -p -	stdin и необработанные байты передаются без изменений.
Redirect	giga gemini -p task >result.txt	Provider stdout записывается напрямую.
JSON	giga codex exec --json task	Provider JSON/JSONL не изменяется.
CI	CI=1 giga gemini -p task	CLI работает напрямую, без формирования запроса в Harness.
Resume	giga codex resume --last	Точный provider selector и непрозрачный suffix без structured interception.
Drift	Версия вне reviewed window	Structured routes могут деградировать, но валидные native-команды остаются независимыми.
Нет runtime	giga claude --version без Claude	Понятная ошибка до provider side effects.

Pi использует тот же декларативный native path. Отдельный structured route pi.acp доступен только если reviewed executable pi-acp уже установлен локально и runtime capability negotiation завершился успешно. GigaLoom не скачивает adapter, не запускает npx и не переключает native Pi на ACP неявно.

giga doctor --json показывает declarative profile, executable и его источник, native launch evidence, structured routes, причину деградации и remediation. Отчёт не хранит provider argv, prompts или output.

Shell completion

Сгенерируйте completion стабильной границы Harness:

giga completion bash
giga completion zsh
giga completion fish
giga completion powershell

Скрипты намеренно не копируют upstream-парсеры. После выбора codex, claude, gemini или pi суффикс и -- остаются нетронутыми, а shell использует обычный fallback completion.

Установка, миграция и откат

Стандартные wheel/sdist содержат Web control plane и native facade, но не provider binary, Node.js runtime, credentials или provider config. uv tool и pipx создают изолированное окружение Harness:

uv tool install 'gigaloom==0.9.1'
pipx install 'gigaloom==0.9.1'

Существующий Textual prerelease обновляйте на месте без исторического extra [tui]. Перед обновлением сохраните user-owned state. Откат — установка точной прежней версии и восстановление проверенного pre-upgrade архива, если выполнялась миграция state:

giga state backup /safe/path/harness-before-upgrade.zip
uv tool install --force 'gigaloom==0.9.1'
uv tool install --force 'gpt2giga-harness==0.5.0a1'
uv tool uninstall gigaloom
uv tool install 'gigaloom==0.9.1'

Удаление пакета не удаляет ~/.gigaloom, проектные .giga/ или нативные provider homes. Harness не делает reverse migration provider config, не устанавливает provider runtime и не выполняет authentication.

Кому подходит GigaLoom

Используйте GigaLoom, если нужен локальный agent cockpit, сравнимые runs и проверяемые workflows. Первые запуски делайте через echo, --dry-run и режимы plan/read в тестовом репозитории.

GigaLoom не является high-availability централизованным multi-user сервисом или security boundary вокруг произвольных действий стороннего CLI.

Для каждого релиза:

• перед обновлением читайте release notes и делайте резервную копию ~/.gigaloom и важных определений из .giga/;
• учитывайте, что интеграции зависят от конкретной версии Codex, Claude или Gemini CLI на машине;
• оставляйте UI на loopback-адресе по умолчанию, если намеренно не настроили remote authentication и TLS;
• проверяйте созданные .giga/-файлы перед commit и никогда не храните в них секреты;
• сообщайте об ошибках в GigaLoom Issues, прикладывая вывод giga doctor, версию Harness, шаги воспроизведения и диагностику без секретов.

Быстрый старт

1. Установите GigaLoom

Требуются Python 3.11–3.14 и uv. Для разработки из source checkout:

git clone https://github.com/krakenalt/gigaloom.git
cd gigaloom
uv sync --all-extras --dev
source .venv/bin/activate
giga doctor
giga --version
giga harness list

Оставляйте virtual environment checkout активным в каждом терминале, где работаете с исходниками. После этого можно перейти через cd в пользовательский проект: команды giga и gpt2giga продолжат запускаться из checkout. В Windows используйте .venv\Scripts\Activate.ps1.

Для опубликованного stable-пакета используйте:

uv tool install 'gigaloom==0.9.1'
giga doctor

Для Direct Chat и provider preset gpt2giga установите явный extra:

uv tool install 'gigaloom[gpt2giga]==0.9.1'

Текущий дистрибутив gigaloom==0.9.1 добавляет только команду giga; его явный extra gpt2giga допускает стабильные gpt2giga>=0.3.0,<0.4.0.

Для Direct Chat понадобятся credentials из быстрого старта gpt2giga. Codex, Claude Code и Gemini — опциональные интеграции: соответствующий CLI executable должен быть в PATH или задан явным override, а локальный gateway — настроен и доступен. Для proxy-backed execution отдельный vendor login не нужен; самостоятельный provider-owned handoff Claude требует его. Отсутствующий CLI будет недоступен, но не сломает остальной cockpit.

Базовая установка и опциональные providers

Provider-neutral базовый distribution содержит девять проверенных прямых runtime dependencies. В release CI Harness wheel устанавливается с Python 3.11–3.14 под Linux, macOS и Windows, проходит terminal-command smoke, после чего versioned audit завершается ошибкой, если resolved environment превышает 64 distributions или содержит packages из следующих семейств опциональных интеграций:

• provider preset gpt2giga/GigaChat;
• чтение и запись Office-документов;
• удалённые messaging channels;
• внешние client или agent UI frameworks;
• sandbox и container providers.

Такие возможности подключаются через явный extra gpt2giga, отдельно установленный provider distribution или entry-point plugin Harness. Базовый пакет не устанавливает и не включает их неявно. Адаптеры Codex, Claude Code и Gemini остаются встроенными, но их отдельно управляемые CLI executables обнаруживаются в PATH, а не устанавливаются как Python dependencies.

Для проверки release или package запускайте следующую команду только в чистом base-install environment. Окружение с намеренно установленным optional provider ожидаемо не пройдёт base-only audit:

python -I -m gigaloom.base_install --json

Команда source-checkout uv sync --all-extras --dev устанавливает development tooling и repository integration fixtures, поэтому не измеряет footprint базовой установки.

Native agents и governed automation

Bare giga печатает ANSI-free launcher summary. giga <agent> запускает настоящий CLI провайдера, сохраняя opaque arguments и terminal ownership; этот путь никогда не входит в structured Workbench. giga run и Web владеют explicit governed execution, а giga chat и giga session остаются обычными CLI-командами для скриптов и администрирования.

В стандартной установке нет GigaLoom terminal frontend или extra tui. Help, version, JSON, dry-run, перенаправленные потоки, pipe, CI и admin-команды сохраняют CLI schema, bytes, exit code и разделение stdout/stderr. giga open ... остаётся явным внешним handoff.

Для перехода со старого TUI prerelease обновите стандартный пакет и удалите [tui] из исторических команд установки:

uv tool install --force 'gigaloom==0.9.1'
giga --version
giga

Для первого release с новым именем rollback использует последний проверенный исторический artifact: uv tool install --force 'gpt2giga-harness==0.5.0a1'. Последующие версии gigaloom откатываются на точную предыдущую версию gigaloom. Команда uv tool uninstall gigaloom удаляет пакет и команды, но не удаляет пользовательские runtime-данные Harness.

2. Инициализируйте тестовый проект

Начните с репозитория, где безопасно просмотреть созданные файлы и пробные изменения:

cd /path/to/project
giga doctor .
giga doctor . --json
giga init

giga doctor [workspace] показывает готовность первого запуска до старта агента. Структурированный вариант --json проверяет proxy и routes, model discovery, версии внешних CLI, готовность workspace и Git, durable worker, Harness-managed homes и managed MCP snapshots. Проверки получают статус ready, degraded или blocked; для degraded и blocked prerequisites отчёт предлагает remediation-команду. Secret values редактируются, абсолютный путь workspace не публикуется, а существующий runtime worker state читается без перезаписи. Отчёт также содержит стабильный kind, точные версии Harness/gateway, Python и platform metadata; совместимость внешних CLI берётся из тех же ограниченных capability probes, которые используются перед execution.

Schema v2 добавляет UI identity boundary, scoped network contract, GitHub CLI и раздельные проверки источников MCP, Skills и Plugins. Отчёт явно фиксирует privacy contract, ограничивает число checks, содержит канонический SHA-256 и показывает для каждого отключённого действия точный шаг восстановления. Настройки → Диагностика → Запустить first-run doctor использует тот же контракт в offline-режиме: Web-проверка не обращается к provider/model routes, GitHub, skills.sh или IdP. Экспортируемый JSON содержит только счётчики, хэши, статусы и recovery-команды — без prompts, secrets, OAuth material, raw traffic, raw paths и содержимого приватных файлов. CLI doctor следует запускать только когда нужны live-проверки proxy и routes.

Для CI порог задаётся явно. --fail-on blocked возвращает exit code 1 только при blocked checks, а --fail-on degraded — при degraded или blocked. Без --fail-on сохраняется интерактивный exit code 0. Для issue report флаг --output атомарно записывает тот же канонический redaction-safe JSON с mode 0600, а stdout сохраняет выбранный human или JSON формат:

giga doctor . --json --fail-on blocked
giga doctor . --json --output harness-doctor.json

giga init создаёт в .giga/ non-secret конфигурацию, стартовые agent profiles, prompts, smoke eval и review workflow. Существующие файлы не заменяются без флага --overwrite.

Сначала проверьте локальный execution path через echo без credentials и сети:

giga harness run echo \
  --workspace . \
  --prompt "Кратко опиши выбранную задачу"

Для полностью локального знакомства используйте демо-репозиторий первого запуска. Он содержит только вымышленные inventory-данные. Инструкция копирует их во временный Git-репозиторий, изолирует Harness runtime state внутри этой копии, запускает giga init и giga doctor ., затем проверяет read-only Echo run и два сгенерированных smoke-eval cases. Credentials, proxy, внешний agent CLI и доступ в публичную сеть не требуются.

Model-backed пример issue-to-reviewed-patch содержит три reviewed agent profiles, durable workflow с сохранением изменений в Harness-owned worktree и post-apply eval. До approval source checkout остаётся неизменным, а apply, commit, push и hosted writes выполняются только по явному решению оператора.

Model-backed nightly compatibility guardian содержит pinned Codex/Claude/Gemini eval, точные baseline dimensions, read-only triage workflow и durable nightly schedule. Он работает при закрытом UI и отправляет в Attention только failed-контракт, ранее прошедший test-now, для классификации product/adapter/model/environment.

Model-backed cross-harness review team параллельно запускает read-only роли explorer, security, tests и maintainability через Codex, Claude и Gemini. Единственный synthesis-шаг цитирует сохранённые child artifacts; сбой одного child остаётся видимым, а частичные evidence не могут быть молча представлены как успешный review.

Затем посмотрите план внешнего агента, не запуская его:

giga run \
  --agent codex \
  --mode read \
  --workspace . \
  --dry-run \
  "Кратко опиши этот репозиторий"

3. Подключите GigaChat

Настройте credentials и локальный API key по основному quickstart. Для browser и durable-worker запусков держите gateway в отдельном терминале. Активируйте в нём environment того же source checkout и запустите:

source /path/to/gpt2giga/.venv/bin/activate
gpt2giga

При установке tools отдельно установите gateway по основному quickstart, чтобы команда gpt2giga была доступна в PATH, и запустите её без uv run.

Проверьте Direct Chat:

giga chat --api-mode v2 --model GigaChat-2-Max "Привет"
giga harness list

Одиночные CLI-запуски могут временно поднять loopback sidecar, если gateway недоступен и реальные GigaChat credentials уже есть в окружении. Durable worker намеренно не поднимает proxy автоматически: для browser workflows gateway нужно держать запущенным отдельно.

4. Откройте cockpit

Из корня нужного проекта запустите:

giga ui

Команда запускает локальный UI и durable worker, но не открывает браузер сама. Перейдите на http://127.0.0.1:8091/.

Рекомендуемый первый маршрут:

1. В Workbench проверьте текущий проект и выбранную сессию.
2. Выберите echo и отправьте безопасный prompt.
3. В Runs откройте attempt, trace и сохранённые redacted payloads.
4. В Evaluation → Arena сравните доступные harness на одной задаче.
5. Изучите Approvals, Attention, Automation, Evaluation и Integrations, прежде чем включать edits или unattended execution.

Cockpit V2 — единственный поставляемый локальный UI. Сохранённые ссылки из предыдущего UI перенаправляются на канонические маршруты Cockpit без миграции или перезаписи runtime state Harness. Если пакетные assets Cockpit недоступны, переустановите пакет Harness или восстановите проверенный build artifact.

У сохранённого ответа assistant кнопка Copy запрашивает и копирует полный текст, даже если в ленте показан ограниченный preview. Для structured и one-shot запусков карандаш показывается только у последнего сообщения user. После редактирования и повторной отправки этот turn и следующий ответ assistant заменяются в активной ветке чата, а исходный run остаётся в Runs как append-only audit evidence. В native terminal карандаша нет: сохранённый интерактивный процесс нельзя безопасно перемотать назад.

Если worker уже запущен отдельно или UI нужен только для просмотра состояния:

giga ui --no-start-worker

Что уже можно попробовать

Раздел	Пользовательский сценарий
Work	Direct Chat, Codex, Claude, Gemini, plugin harness, attachments и project context.
Arena	Сравнение нескольких harness на одной задаче.
Runs	Durable queue, attempts, retries, cancellation, trace, events, artifacts и diffs.
Approvals	Явные решения перед действиями, которыми владеет Harness.
Agents	Повторно используемые project profiles в .giga/agents/.
Workflows	Версионированные многошаговые и multi-agent DAG в .giga/workflows/.
Evaluate	Повторяемые eval cases, матрицы harness/model и baselines.
Tools	Discovery и проверка MCP, preview/apply/rollback управляемой конфигурации.
Scheduled	Проверяемые расписания, история occurrences и Attention Inbox.

Эффективные параметры Agent Profiles

Перед постановкой Run as Agent в durable queue Agent Studio раскладывает каждое исполняемое поле профиля на effective, delegated или unsupported и показывает источник enforcement. В run сохраняются неизменяемые redacted agent_profile_snapshot и agent_execution_plan с requested/effective значениями. Неподдерживаемые safety- и budget-параметры блокируют queueing, а provenance-only selectors дают явное предупреждение.

Параметр профиля	Codex CLI	Claude Code	Gemini CLI
model, route, mode, workspace/permission policy	effective	effective	effective
timeout и retry attempts	enforced by Harness	enforced by Harness	enforced by Harness
reasoning_effort	capability-proven config	capability-proven --effort	unsupported
allowed_tools / disallowed_tools	unsupported	capability-proven fixed flags	unsupported
tool_ids	immutable managed-MCP snapshot	immutable managed-MCP snapshot	immutable managed-MCP snapshot
max_tokens	unsupported	unsupported	unsupported

max_concurrency больше 1 относится к coordinator уровня Workflow или Schedule. tool_ids должны ссылаться на enabled, trusted и совместимые с адаптером project MCP profiles. До queueing они замораживаются в неизменяемый snapshot и materialize только в активный временный execution home. Structured driver может отклонить параметр, projection которого ещё не доказан: например, Gemini ACP сейчас блокирует managed MCP projection вместо fallback в one-shot. Prompt files, skills и context/memory selectors пока сохраняются как явно unsupported provenance. Профиль не принимает произвольные CLI flags или secret literals.

Для process-backed run публичные metadata содержат только descriptor-free identity; полный безопасный snapshot проверяется по content hash внутри Harness data dir. Replay повторно использует тот же snapshot даже после изменения project TOML. Secret refs разрешаются только на границе создания subprocess config, а точная конфигурация записывается во временный Codex/Claude/Gemini home и удаляется после процесса. Пользовательские native homes при этом не меняются.

Конфигурация

CLI flags имеют приоритет над environment variables. Основные переменные:

GIGALOOM_PROXY_URL=http://127.0.0.1:8090
GIGALOOM_API_KEY=<local-proxy-api-key>
GIGALOOM_DEFAULT_MODEL=GigaChat-2-Max
GIGALOOM_DEFAULT_API_MODE=v2
GIGALOOM_UI_HOST=127.0.0.1
GIGALOOM_UI_PORT=8091
# Только remote deployment; secret хранится в deployment-owned secret storage:
GIGALOOM_UI_OIDC_ISSUER=https://issuer.example
GIGALOOM_UI_OIDC_CLIENT_ID=gigaloom
GIGALOOM_UI_OIDC_CLIENT_SECRET=<deployment-secret>
GIGALOOM_UI_OIDC_PUBLIC_ORIGIN=https://harness.example
GIGALOOM_UI_OIDC_ROLE_MAP='{"subject-1":"viewer","subject-2":"operator"}'
GIGALOOM_UI_TRUSTED_PROXIES=10.0.0.2
GIGALOOM_AUTO_START_PROXY=True
GIGALOOM_PROXY_START_TIMEOUT_SECONDS=15
GIGALOOM_TIMEOUT_SECONDS=3600
GIGALOOM_DATA_DIR=~/.gigaloom

В Cockpit Settings модели по умолчанию для чатов и генерации заголовков настраиваются независимо. Нажмите Найти модели и выберите оба значения из списка, который вернул активный API route. Настройки сохраняются в settings/defaults.json внутри Harness data directory и применяются к новым запускам; если модель заголовков очищена, используется выбранная модель чатов. GIGALOOM_DEFAULT_MODEL или GIGACHAT_MODEL по-прежнему блокирует изменение модели чатов, если значение принадлежит окружению.

Если GIGALOOM_API_KEY не задан, Harness использует GPT2GIGA_API_KEY для локального proxy. GigaChat credentials, OAuth tokens, certificates и содержимое .env не передаются внешнему agent CLI.

Пути к нестандартно установленным CLI храните в пользовательском ~/.gigaloom/config.toml, а не в проекте:

[executables]
"codex-cli" = "/opt/tools/codex"
"claude-code" = "/opt/tools/claude"
"gemini-cli" = "/opt/tools/gemini"

giga config path
giga config set executables.codex-cli /opt/tools/codex
giga config unset executables.codex-cli

Configured path должен быть абсолютным, имеет приоритет над PATH и проходит version/capability probe до запуска.

Профили providers и routes

В Cockpit Settings → Провайдер и Маршруты и модели управляют backend-owned профилями OpenAI-, Anthropic- и Gemini-compatible endpoints. Provider задаёт dialect протокола, base URL, route prefix, владельца authentication, состояния enabled/offline и модели по назначениям. Новый run фиксирует выбранные provider и route в execution snapshot, поэтому последующее изменение Settings не переписывает сохранённые evidence и активную structured session.

Credentials задаются ссылками, а не значениями формы. Settings и CLI принимают ссылку на environment variable или keychain и возвращают только её kind и name; значение секрета разрешается только на границе принадлежащего ему request или subprocess. Provider settings service отклоняет literal credentials, файлы с credentials и неограниченные filesystem paths.

Например, зарегистрируйте OpenAI Responses-compatible endpoint, ключ которого остаётся в OPENAI_API_KEY:

giga provider add openai-production \
  --name "OpenAI production" \
  --protocol openai_compatible \
  --dialect openai-responses-v1 \
  --base-url https://api.openai.com \
  --route-prefix /v1 \
  --authentication secret_reference \
  --secret-reference-kind environment \
  --secret-reference-name OPENAI_API_KEY \
  --coding-model <model-id> \
  --json

giga provider list --json
giga provider show openai-production --json
giga provider test openai-production --json
giga provider discover openai-production --json

test и discover — явные ограниченные операции. Отсутствующий probe backend, ошибка authentication или несовместимый endpoint возвращаются как content-free health evidence и не приводят к молчаливому выбору другого provider. Для edit нужен текущий revision из show или Settings, поэтому старый browser/CLI request не перезапишет более новую конфигурацию:

giga provider edit openai-production \
  --expected-revision <revision> \
  --coding-model <new-model-id> \
  --json

Legacy defaults proxy/API mode/model остаются читаемыми на время prerelease- перехода. Мигрируйте их только через forward-only flow с обязательным backup:

giga provider migrate-legacy --dry-run --json
giga provider migrate-legacy \
  --backup /safe/path/harness-before-provider-migration.zip \
  --json

Перед публикацией provider registry и journal миграция повторно проверяет source и target state под lock. Reverse migration нет: для rollback остановите Harness и восстановите проверенный pre-upgrade archive.

Конфигурация проекта

giga init создаёт .giga/harness.toml и стартовые определения. Посмотреть effective project config и его источник можно так:

giga project info --json
giga project init --name my-project --json

Project config хранит только переносимые несекретные ссылки: default harness, model/API mode, пути к prompts, agents, workflows, evals, tools и schedules. Absolute executable paths, credentials и runtime ownership остаются на уровне пользователя. Не редактируйте .giga/ из UI без просмотра diff.

Повторно используемые Agent Profiles

Agent profile — version-controlled YAML-описание harness, модели, режима plan|read|edit, workspace policy, timeout/retry и допустимых tools. Профиль не может подмешивать произвольные shell flags или literals секретов.

giga agent list --workspace .
giga agent show reviewer --workspace . --json
giga run --agent reviewer --workspace . "Проверь изменение"

Перед queueing Harness строит immutable execution plan. Неподдерживаемый safety-critical параметр блокирует запуск; delegated параметр остаётся явно отмеченным, чтобы UI не выдавал его за enforcement со стороны Harness.

Версионированные Workflows

Workflow — YAML DAG под .giga/workflows/ с шагами agent, prompt, eval или handoff. Определение получает content hash; durable run сохраняет snapshot, поэтому последующее редактирование YAML не меняет уже поставленную задачу.

giga workflow list --workspace .
giga workflow validate .giga/workflows/review.yaml
giga workflow run review --workspace . --prompt "Проверь изменение" --json

Условия, зависимости и retry описываются декларативно. Multi-agent fan-out ограничивается coordinator policy; workspace mutation всё равно требует worktree isolation и approvals.

В пустых разделах Automation сразу доступна связанная цепочка примеров:

1. Code Reviewer — read-only профиль Codex-агента.
2. Review Change — workflow, который вызывает code-reviewer.
3. Weekday Review — расписание по рабочим дням для review-change.

Откройте Automation → Agents, создайте и примените Code Reviewer, затем повторите это в Workflows. Agent и workflow запускаются из их detail view. После этого создайте schedule, выполните Test для точного content hash и нажмите Enable, когда worker online. На каждой карточке также показана эквивалентная команда giga run --agent, giga workflow или giga schedule.

Project Memory

Project memory хранит короткие, проверяемые факты и решения, а не скрытую копию всего репозитория:

giga memory add "Использовать Alembic migrations" --workspace . --tag decision
giga memory list --workspace . --json
giga memory disable <memory_id> --workspace .
giga memory enable <memory_id> --workspace .

Перед сохранением удалите credentials, personal data и приватный code content. Memory selectors в profile пока могут быть provenance-only; смотрите effective plan до запуска.

Preflight запуска

Preflight проверяет доступность executable, совместимость версии, route/model, proxy authentication, workspace trust, permission mapping, managed tools, attachments и нужные approvals до создания процесса:

giga run --agent codex --mode read --workspace . --dry-run "Проверь проект"
giga harness inspect codex-cli --json
giga doctor

Machine-readable секция readiness проецирует doctor checks только на выбранный execution plan: harness, invocation mode, точный API route/model, workspace/Git policy и synchronous или durable delivery. Отсутствующие обязательные capabilities блокируют запуск, а degraded checks показывают redaction-safe remediation message и command. Нерелевантные сбои proxy, внешнего CLI или worker не блокируют независимый локальный Echo path.

Ошибка preflight не должна оставлять process, worktree или временный managed home. Existing external proxy никогда не останавливается Harness; созданный им loopback sidecar имеет явный ownership и очищается при failed startup.

Проверяемый bootstrap и execution assurance

giga bootstrap даёт проверяемый first-run путь, не смешивая discovery и изменения. Preview запускает doctor в read-only режиме и возвращает детерминированный plan_id; apply принимает только этот актуальный plan и явно выбранные обратимые шаги:

giga bootstrap preview --workspace . --json
giga bootstrap apply <plan_id> --workspace . --all-reversible --json
giga bootstrap status <application_id> --json
giga bootstrap rollback <application_id> --workspace . --json

Журнал application хранит только ограниченные identities и пути, созданные Harness. Rollback удаляет объект, только пока он совпадает с журналом, и останавливается безопасным отказом при изменении workspace, data root или созданного содержимого. Bootstrap не устанавливает providers, не разрешает credentials, не запускает внешние процессы и не включает schedules.

Перед model-backed матрицей запустите side-effect-free compatibility guardian:

giga compatibility check --json
giga compatibility check --harness codex-cli --json

Guardian проверяет зафиксированные окна Codex, Claude и Gemini CLI, допуск native protocols, версии Adapter/Integration SDK и schemas, а также marketplace source contracts. Он не запускает providers или integrations и возвращает код 1, если обязательный fixture заблокирован. Cockpit получает тот же read-only report через GET /api/compatibility/guardian.

Preflight каждого run также строит content-free симуляцию permissions для точного Harness, provider route, execution transport, workspace policy и snapshot расширений. Filesystem, command, network, secret, integration, provider и Git/GitHub actions классифицируются как allowed, approval-required, denied или unknown, а также как pre-start, runtime-dependent или provider-owned. Обязательный deny блокирует запуск; runtime-dependent и provider-owned действия не выдаются за гарантированное разрешение.

Harness-owned исходящий HTTPS по умолчанию запрещён и использует контракт контролируемого сетевого доступа. Одновременно нужны точный непросроченный grant и включённая sandbox boundary; host, port, method class, redirect policy, purpose, digest request и transfer ceilings повторно проверяются до соединения. Публичные DNS answers pin-ятся, а connected peer обязан совпасть. Опциональная reviewed proxy policy работает только на loopback и по allowlist-first модели с purpose-bound expiring rules и без global wildcard. Сама policy не активирует provider или integration traffic.

Runs Center может создать Trace-to-Replay comparison, изменив ровно одну ось: model, provider, Harness или extensions. Preview связывает сохранённое source evidence и все неизменённые измерения с hash. Запуск проверенного manifest создаёт новую session, использует существующего execution owner и никогда автоматически не применяет patch. Сохранённое сравнение показывает нормализованные outcome, usage, tools, artifacts, environment и evidence deltas без обязательной external telemetry.

Для передачи без запуска target создайте truthful handoff capsule:

giga handoff capsule <run_id> --target-harness <harness_id> --json

Capsule — проверяемый content-free snapshot identities задачи и evidence, Git environment, pending approvals, target compatibility и ограничений continuity. Он не запускает target и не утверждает, что provider-owned history можно продолжить. Runs Center и GET /api/runs/{run_id}/handoff-capsule используют тот же контракт.

Tool Profiles и MCP

Tool profile содержит descriptor MCP server, trust state, transport, secret refs и policy labels. Раздел Tools показывает discovery и совместимость, но не выполняет tool автоматически.

Репозиторий может запросить доверие через trusted = true, но оно начинает действовать только после того, как пользователь пометит проект доверенным в состоянии проекта, принадлежащем Harness. До этого process-backed probe требует явного approval, а managed apply отклоняется.

Управление доступно в top-level разделе Tools и через аутентифицированные /api/tools, /api/mcp endpoints cockpit. Сначала используйте preview/dry-run. Apply/rollback managed configuration проходит через approval. Secret ref разрешается только у owning subprocess и не попадает в durable metadata, project YAML или browser response.

Федеративная установка Skills и MCP

В разделе Plugins Cockpit можно отделить встроенные пакеты (Built-in) от External Skills & MCP, найденных в offline-каталоге. Источник skills-sh добавляет hosted metadata Skills через отдельно разворачиваемый read-only proxy, а neuraldeep — публичные metadata Skills и MCP. Popularity, curation, health и presence источника являются только discovery evidence: они не дают права на установку, не разрешают сеть и не заменяют проверку точного artifact.

Для skills.sh запустите read-only metadata proxy и передайте Harness его фиксированный origin:

export VERCEL_OIDC_TOKEN=<request-scoped-token>
python -m gigaloom.skills_catalog_proxy

# в процессе Harness
export GIGA_SKILLS_PROXY_ORIGIN=http://127.0.0.1:8092
giga ui

На странице Skills тот же гайд расположен рядом с фильтром источника. После успешного подключения статус меняется с configuration_required или unavailable на ready; сохранённый last-good результат явно помечается stale.

В production включите OIDC Federation в Vercel и используйте request-scoped VERCEL_OIDC_TOKEN; не сохраняйте токен в image, config или статическом environment export. Контракт API skills.sh возвращает 401 для отсутствующего/просроченного токена и 429 с Retry-After при rate limit. /healthz сообщает configuration_required, пока OIDC не настроен. Ограниченный last-good cache задаётся через GIGA_SKILLS_PROXY_CACHE_ENTRIES и GIGA_SKILLS_PROXY_STALE_IF_ERROR_SECONDS; retained response явно помечается X-Giga-Cache-Status: stale, содержит Age и не скрывает ошибку источника.

Proxy поддерживает leaderboard/search, curated results, безопасные пути detail/file tree и optional audit metadata. Содержимое файлов и audit summary не возвращаются в Harness. Cockpit показывает canonical source, upstream ID, repository URL, immutable hash, relative path, discovery breadcrumb, last sync, cache age, last-good state и ограниченные audit verdicts. Та же URL/origin/ref/hash projection входит в точный install preview и retained flow receipt.

Harness также читает системные bundles OpenAI из plugin caches openai-primary-runtime и openai-bundled. Поэтому PDF, Documents, Presentations и Spreadsheets отображаются в Plugins с source badge OpenAI, именами вложенных Skills, default prompts и подсказкой вызова @name. Это read-only inventory: Harness не устанавливает, не включает и не перезаписывает bundle OpenAI.

В Work введите @, чтобы выбрать capability. Для запуска через Codex CLI Harness сохраняет явный выбор в prompt и преобразует @pdf в нативный вызов Skill $pdf. В ChatGPT Plugins и Skills выбираются через @, а в Codex CLI/IDE Skills вызываются через $; Cockpit сохраняет понятный пользователю picker @ и явно показывает это преобразование.

Если источник недоступен, ограничил частоту запросов, требует обновить аутентификацию или вернул некорректные данные, Harness сохраняет последний корректный snapshot каталога. Внешний Skill можно установить только после совпадения bytes с проверенными immutable reference и content hash, а также проверки ограниченного SKILL.md и файлов. Карточка MCP из NeuralDeep служит локализованными discovery metadata. Она связывается с пакетом официального MCP Registry только по точному official package name или canonical repository; версия, immutable reference и integrity из official Registry остаются authoritative.

В каждой строке результата и detail view показан source bubble, включая NeuralDeep. Каноническая страница GigaChat Image MCP: NeuralDeep GigaChat Image MCP.

Сначала изучите offline inventory, затем создайте preview одной цели:

giga integration list --json
giga integration preview \
  --source catalog \
  --catalog-id <catalog-id> \
  --target <target-id> \
  --scope managed_home \
  --json
giga integration apply <flow-id> \
  --plan-id <plan-id> \
  --authority <operator> \
  --json
giga integration status <flow-id> --json
giga integration rollback <flow-id> --json

Preview связывает точные package/artifact hashes, target, владельца scope/root, configuration, permissions, границы network и native consent, risk и approval hash. Apply отклоняет устаревший или расширенный plan. Безопасный default — managed_home; project scope требует --workspace, а user_home остаётся выключенным, пока preview и apply не разрешат его явно. Секреты остаются непрозрачными references и разрешаются только owning subprocess. Для обновления выберите новый immutable pin и пройдите новый preview и approval: изменение каталога не обновляет существующую установку неявно.

Для проверенного Skill или MCP package из каталога all-supported group сохраняет отдельные child plan и transaction для каждой цели:

giga integration group-preview \
  --catalog-id <catalog-id> \
  --scope managed_home \
  --json
giga integration group-apply <group-id> \
  --plan-id <plan-id> \
  --authority <operator> \
  --json
giga integration group-status <group-id> --json
giga integration group-recover <group-id> --json
giga integration group-rollback <group-id> --json

Skills разворачиваются в Skill targets Codex, Claude и Gemini. MCP packages — в три managed native home и Harness-managed MCP inventory. До первой мутации должны успешно завершиться все child previews. Межкорневой apply — это recoverable compensating transaction, а не filesystem-atomic write: при частичном сбое уже применённые owned и verified children откатываются в обратном порядке либо сохраняются точные repair actions для group-recover. Status показывает verification и repair-required state; rollback отказывается менять чужие или изменённые после установки файлы.

Portable Extension Pack связывает один проверенный Skill и один MCP catalog entry с точными pack id и semantic version. Preview строит content-free матрицу совместимости для Codex, Claude, Gemini и Harness-managed targets, явно исключает несовместимые providers и собирает поддерживаемые child plans в одну восстанавливаемую группу:

giga integration pack-preview \
  --pack-id workspace.extension-pack \
  --pack-version 1.0.0 \
  --skill-catalog-id <skill-catalog-id> \
  --mcp-catalog-id <mcp-catalog-id> \
  --scope managed_home \
  --json
giga integration group-apply <group-id> \
  --plan-id <plan-id> \
  --authority <operator> \
  --allow-network \
  --ack-native-consent \
  --json

Plan связывает immutable package integrity, точную MCP configuration, permissions, native consent, включённые targets и все child plan ids. Apply не может расширить этот набор; recovery и rollback используют обычный grouped lifecycle. В Cockpit тот же flow называется Portable Extension Pack и показывает compatibility matrix до approval.

Те же inventory и lifecycle доступны через GET /api/integrations, POST /api/integrations/preview, apply/rollback routes /api/integrations/flows/{flow_id} и соответствующие routes /api/integrations/groups. Cockpit показывает тот же source filter, точный preview одной цели или Install to all Harnesses, approval, verification, recovery и rollback. Федеративные Plugins не поддерживаются, discovery не разрешает неявную загрузку, и ни одна операция по умолчанию не меняет реальный user home.

Eval Lab и матрицы совместимости

Eval case фиксирует input, проверяемые критерии и ожидаемые artifacts. Матрица запускает независимую пару case/harness/model и сравнивает только совместимые dimensions: Git SHA, config hash, CLI version, event schema и route.

giga eval list --workspace .
giga eval run smoke --workspace . --harness echo --json
giga eval run smoke --harness codex-cli,claude-code,gemini-cli --dry-run

Baseline — локальный versioned reference, а не гарантия качества модели. Не сравнивайте результаты после изменения CLI/model/route как одну и ту же серию: UI пометит такой baseline несовместимым.

Git и GitHub environments

Для session с Git workspace Workbench показывает bounded snapshot: worktree, branch и HEAD, количество staged, unstaged и untracked файлов, upstream/base/ahead readiness и credential-free подсказку hosted repository. При наличии аутентифицированного gh Harness добавляет read-only статус GitHub pull request, связанных issues, checks и последних Actions runs только для точного repository. Diff contents, remote credentials и raw command output в snapshot не попадают.

Workbench может создать один точный staged commit, выполнить один non-force push и создать один GitHub pull request. Каждая мутация проходит три шага:

1. сохранение preview, связанного с точным HEAD/diff или local/remote state;
2. approval именно этого действия во Inbox;
3. повторная проверка state и применение того же preview.

Commit hooks не запускаются, push hooks отключены, force push и pushurl override отклоняются. Новый upstream задаётся только если был показан в preview. Для pull request исходная ветка должна быть attached и уже находиться на проверенном remote HEAD. Изменившийся checkout или remote, detached HEAD, repository mismatch, устаревший approval и неоднозначный network failure fail-closed либо сверяются с content-free evidence. Web UI предоставляет проверенные операции, не добавляет файлы в index, не выполняет merge и не обходит branch protection.

Аутентифицированные API routes:

GET  /api/environment?session_id=...
POST /api/environment/commit/preview
POST /api/environment/commit/apply
POST /api/environment/push/preview
POST /api/environment/push/apply
POST /api/environment/pull-request/preview
POST /api/environment/pull-request/apply

PR artifacts, provenance и replay

Run может собрать локальный diff, patch, summary, test evidence и PR-ready metadata. Создание и просмотр этого artifact не выполняют hosted write. Поздний GitHub push или pull request — отдельное environment action со своим immutable preview и approval; GitLab writes пока не поддерживаются. Provenance связывает execution snapshot, attempt, workspace, model, adapter evidence, approvals и artifacts.

giga runtime inspect --json
giga runtime export --output harness-runtime.json

Replay использует сохранённый snapshot и не подменяет его текущей project configuration. Export по умолчанию не содержит raw task payloads; всё равно просмотрите файл перед передачей третьей стороне.

Promotion и Editor Bridge

Успешный run можно превратить в proposal для agent/prompt/workflow/eval. Promotion сначала показывает diff и требует approval; она не изменяет source checkout неявно. Editor Bridge открывает поддерживаемый local artifact или diff в настроенном editor и не превращает browser input в произвольную shell-команду. Аргументы конфигурации запрещены, кроме безопасных флагов окна и ожидания для редакторов семейства Code.

Встроенные Harness-адаптеры

Адаптер	Назначение	Continuation
direct-chat	Прямой Chat Completions через gateway	structured replay
codex-cli	Structured app-server, managed native terminal или one-shot	durable app-server thread при доказанном контракте
claude-code	One-shot, managed native terminal или отдельный provider handoff	embedded structured blocked; handoff недолговечен и provider-owned
gemini-cli	Structured ACP, managed native terminal или one-shot	durable ACP session при доказанном --acp
echo	Deterministic smoke без credentials и сети	stateless

giga harness list показывает только реально доступные adapters, а giga harness inspect <id> --json — capability evidence, transport attachments, policy ownership и причины degraded/disabled state.

Workbench, Settings, session API и giga session turn используют канонические transport-значения native_structured, native_terminal и one_shot. Structured transport означает provider-owned session под управлением проверенного протокола; terminal означает managed PTY без видимости внутренних семантик TUI; one-shot не обещает native continuity. Transport, interactive/batch mode и request-bound/durable ownership сохраняются в execution snapshot независимо. Заблокированный structured-запрос не переключается молча на terminal или one-shot.

Codex и совместимый Gemini по умолчанию используют native_structured в Workbench. Для Claude structured-вариант остаётся явно blocked, потому что граница embedded SDK/auth не была принята. Remote Control/Desktop handoff — отдельный provider_owned, non-durable и non-queueable preview, а не Harness session continuity.

giga harness inspect gemini-cli --json
giga session turn <session-id> \
  --transport native_structured \
  --prompt "Проверь этот репозиторий"

Codex CLI

Для durable native_structured continuity Harness предпочитает reviewed codex app-server JSON-RPC. Если contract не доказан, structured transport блокируется; явный one-shot compatibility path использует codex exec --ephemeral --json с degraded_replay. Native terminal запускает TUI в managed PTY; это другой transport и другой уровень наблюдаемости.

Claude Code

One-shot run использует capability-probed flags для model, permission mode, effort и allowed/disallowed tools. Managed MCP config материализуется только во временном home. Native terminal output может содержать структурированную tool activity, но внутренние prompts и approvals CLI остаются delegated.

Embedded Claude Agent SDK execution не productized: проверенный auth surface не удовлетворяет принятой subscription-native границе. На поддерживаемом macOS Integrations может показать content-free preview отдельного Remote Control или Desktop handoff через GET /api/provider-handoffs/claude-code/preview. Он требует full-scope provider login, может открыть provider-owned process/UI и не является durable, queueable или Harness-owned continuity.

Gemini CLI

Перед native start проверяется --prompt-interactive, чтобы initial prompt был доставлен ровно один раз. Wrapper argv задаётся TOML-массивом без shell=True. Неизвестный или несовместимый event stream завершается явной ошибкой вместо догадок по terminal text.

Для durable Workbench или giga session turn --transport native_structured совместимый Gemini запускается через reviewed ACP stdio driver, а не prompt-mode command. Harness требует versioned capability --acp, сохраняет content-free structured-session link, нормализует ACP updates, передаёт live approvals, поддерживает interrupt/resume и recovery после потери процесса. Managed MCP projection в ACP пока blocked и не подменяется другим transport.

CLI истории и native sessions

giga session list --workspace .
giga session show <session-id> --json
giga native sync --harness codex-cli --workspace . --json
giga native list --harness codex-cli --workspace . --json
giga native import <native_ref_id> --json

session работает с Harness-owned history. native обнаруживает и связывает vendor sessions через adapter-specific read-only contract. Sync не импортирует transcript автоматически и не переписывает homes Codex, Claude или Gemini.

Browser UI, Smart Router и Arena

Скомпилированные Cockpit bundles не хранятся в Git. В свежем source checkout до первого uv sync или сборки Harness wheel/sdist выполните npm --prefix web ci --ignore-scripts, затем npm --prefix web run build. Producer атомарно создаёт ignored, привязанное к commit дерево с integrity metadata, npm SBOM и license evidence. Python build проверяет его без Node.js и network access и завершается ошибкой при отсутствии, stale source, подмене или неожиданных файлах. CI/release передают то же immutable дерево между jobs; wheel из sealed sdist остаётся Node-free. Для rollback checkout предыдущий release и повторите producer либо восстановите его точный asset artifact до Python build.

UI состоит из Work, Runs, Native, Arena, Approvals, Agents, Workflows, Evaluate, Tools и Scheduled. Runs Center читает durable queue, trace и artifacts; reasoning model не отображается в timeline. Smart Router объясняет выбор adapter/model и не скрывает unavailable capabilities. Arena создаёт независимые child jobs и workspaces, чтобы один участник не менял контекст другого.

После завершения всех candidates Cockpit позволяет выставить каждому score от 0 до 1 и выбрать один успешный результат. Record verdict связывает полный набор оценок и выбранный run с точным hash candidate evidence. Повтор того же запроса idempotent, но изменившийся набор candidates отклоняется, а записанный verdict неизменяем: follow-up или retry требуют нового Arena comparison. Выбранный run получает ссылки на сохранённое evidence и preview promotion; Harness не применяет patch и не выполняет promotion автоматически.

После начала первого run Work постепенно показывает компактный путь Run → Evidence → Approval/worktree → Reuse/automation. Пока run активен, evidence остаётся pending. После success, failure или cancellation кнопка Open evidence открывает trace именно этого run в Runs Center и показывает только сохранённые counts событий/tools и duration, не повторяя prompt, response или workspace content. Если run сохранил изолированный patch, Review worktree открывает его точный Diff inspector; apply patch и выдача approval остаются отдельными явными действиями оператора. Для успешного run без ожидающего review кнопка Reuse run открывает существующий provenance/promotion inspector именно этого run; preview/apply кандидата agent/workflow/eval и его последующее добавление в schedule остаются отдельными явными действиями оператора.

Attachments сначала копируются или связываются по безопасному project policy, затем преобразуются в adapter-specific render plan. UI различает rich transport, CLI flag, staged path, prompt reference и metadata-only delivery; supports_attachments=True сам по себе не доказывает multimodal delivery.

Durable worker, schedules и очередь

Worker владеет leases, heartbeats, retries, timeout/cancel и crash reconciliation. Browser можно закрыть после queueing. Interactive composer умеет interrupt текущего turn и durable queue следующих сообщений; они отправляются последовательно и остаются видимыми рядом с composer.

giga worker start
giga worker status
giga worker stop-on-idle --idle-seconds 30
giga schedule list --workspace . --json
giga schedule preview schedule.yaml --workspace . --json
giga schedule test-now daily-review --workspace . --json
giga schedule enable daily-review --workspace . --json

Schedule нельзя включить без live worker и успешного Test now для точного content hash. Изменение material field ставит schedule на pause. Occurrence history не удаляется при archive, а unattended edit fail-closed без worktree и нужных approvals.

Пустой worker теперь увеличивает idle wait от 250 мс до ограниченной 1 секунды. Изменения queue, approval и конфигурации schedule посылают content-free loopback wake signal, а ближайшие schedule, retry и lease deadlines ограничивают ожидание даже при недоступной доставке wake. --poll-seconds задаёт минимум, --max-idle-seconds — верхнюю границу. Это не увеличивает concurrency workers и не меняет семантику lease, cancellation, recovery или durable ownership.

Форма Schedule следует модели Codex Scheduled для частых сценариев: выберите Once, Daily, Weekdays или Weekly, затем задайте первый запуск, IANA timezone, target, prompt и уведомление. Harness преобразует эти поля в governed one-shot, interval или RRULE. Режим Custom и свёрнутый Advanced · JSON нужны только для явного RRULE или низкоуровневых policy fields.

Безопасный edit-сценарий

1. Сначала выполните задачу в plan или read либо используйте --dry-run.
2. Для edit оставьте workspace policy в auto или явно выберите изолированный worktree.
3. После запуска откройте diff и artifacts в Runs.
4. Не применяйте patch, если он обрезан, конфликтует с исходным checkout или содержит неожиданные файлы.
5. Разрешайте apply или создание branch только через понятный approval.

Harness не включает скрытый auto-apply, push или merge. Сторонний CLI может иметь собственную sandbox/permission-модель, поэтому проверяйте одновременно его настройки и то, что сообщает Harness.

Где хранятся данные

Путь	Содержимое
~/.gigaloom	Runtime SQLite, sessions, attempts, redacted logs, managed native homes, worktrees и локальное UI state.
.giga/ в проекте	Non-secret project config, prompts, agents, workflows, evals и schedules.

При uninstall/reinstall не удаляйте эти каталоги автоматически. Сначала остановите UI и worker, сделайте backup и проверьте release notes.

Секреты храните в environment variables или разрешённом локальном secret backend. Не записывайте credentials, API keys, OAuth tokens, cookies, сертификаты, private keys или содержимое .env в .giga/harness.toml, YAML, issue или диагностический архив.

Удалённый доступ

Безопасный режим по умолчанию — 127.0.0.1:8091. Первый OS-local browser claim создаёт opaque HttpOnly SameSite=Strict сессию со сроком действия; на диске остаются только хэши и сроки в приватном server-side state. В Cockpit Settings сессию можно ротировать или завершить, а loopback-only recovery отзывает старые сессии перед созданием новой. Browser mutations требуют same-origin CSRF marker. Локальный access token не попадает в URL, localStorage, sessionStorage, diagnostics, screenshots или project files.

Remote binding реализует ограниченный single-issuer OIDC/BFF identity contract из контракта remote identity. Non-loopback listener требует полной статической конфигурации issuer, client, публичного HTTPS origin, точного subject-to-role mapping и явного --allow-remote. Authorization Code + PKCE S256, nonce/signature/audience validation, opaque server-side sessions, exact-origin CSRF, роли viewer/operator, JWKS rotation и session/actor/global/back-channel revocation работают fail-closed. Старые bootstrap token и Host allowlist не аутентифицируют remote users.

giga ui-identity validate --json проверяет deployment profile без запроса к issuer. giga ui-identity revoke-all --confirm --json — OS-local recovery, который отзывает все remote sessions и ротирует их generation.

Принятые контракты ролей, sessions, CSRF, revocation, trusted proxy и recovery описаны в правилах идентификации удалённых пользователей. Не публикуйте и не туннелируйте loopback listener как multi-user workaround.

Ограничения preview

• Поведение Codex, Claude и Gemini зависит от versioned structured capabilities, custom endpoints, one-shot/headless mode, native resume и формата local history в установленной версии CLI.
• Часть действий внутри внешнего CLI непрозрачна; policy enforcement может быть delegated или advisory.
• MCP-раздел ориентирован на discovery и управляемую конфигурацию; это не обещание автоматической установки, OAuth или выполнения любого MCP tool.
• Scheduled jobs требуют живого worker, успешного Test now для текущего hash и необходимых approvals.
• Generated artifacts и patches всегда нужно проверять вручную. Preview не даёт production SLA и гарантии полной обратной совместимости.

Если что-то не работает

Начните с:

giga doctor
giga harness list
giga harness inspect codex-cli --json

Диагностика совместимости адаптера

Для встроенных внешних CLI поле protocol_capability_scope имеет значение harness_surface: capability-описание фиксирует то, что Harness действительно наблюдает и гарантирует, а не все внутренние wire-протоколы CLI. В adapter_capabilities используются состояния supported, partial, delegated и unsupported, поэтому giga harness inspect --json и /api/harnesses явно показывают ограничения continuity, native policy, доставки первого prompt и managed tools. Отдельное поле headless_continuation сообщает фактическую стратегию: structured_thread, structured_replay, native_cli_resume, degraded_replay, one_shot или unsupported.

Единую проверяемую матрицу для всех встроенных внешних CLI можно сгенерировать непосредственно из этих runtime-контрактов:

giga harness capabilities
giga harness capabilities --json

Markdown и версионированный JSON детерминированы, не запускают probes установленных бинарных файлов и не читают native CLI homes. Необъявленная ячейка остаётся null/undeclared: генератор не превращает отсутствие claim в поддержку. Evidence для установленной версии по-прежнему доступно отдельно через giga harness inspect <id> --json.

Перед тем как считать Codex CLI, Claude Code или Gemini CLI доступным, Harness выполняет ограниченные --version и --help probes во временном изолированном home. Они не читают пользовательские history/config и не сохраняют environment или секреты. Результат кэшируется по безопасному argv и версии; поэтому найденный, но несовместимый binary получает явный compatibility warning в doctor, worker fingerprint, giga harness inspect --json, /api/harnesses и cockpit. Для Gemini wrapper можно задать безопасный TOML-массив argv в ~/.gigaloom/config.toml; элементы передаются напрямую без shell=True. Парсеры допускают неизвестные добавочные поля из versioned fixtures, но поток без единого распознанного обязательного event contract завершается ошибкой.

Текущие окна поддержки внешних CLI намеренно ограничены minor-линиями, которые покрыты пакетными fixtures для one-shot, structured, terminal и native history:

Адаптер	Поддерживаемое окно версий
Codex CLI	>=0.146.0,<0.147.0
Claude Code	>=2.1.0,<2.2.0
Gemini CLI	>=0.46.0,<0.47.0

Должны одновременно пройти окно версии и probes обязательных capabilities. Версия ниже окна или binary без обязательного флага получает статус unsupported. Более новая версия со всеми обязательными флагами получает degraded: диагностика показывает version_contract.status=above_window, но запуск остаётся fail-closed до пересмотра fixtures и объявленного окна. Неразбираемый вывод версии обрабатывается так же со статусом version_contract.status=unparsed. JSON-контракт также публикует minimum и maximum_exclusive, поэтому CI и issue reports не должны разбирать warning.

One-shot-потоки, Codex app-server и Gemini ACP публикуют стабильные tool, command, file, usage, failure и lifecycle events только из capability-probed schema. Usage сохраняет доступные cached-input, reasoning-output и tool token details. Нативные TUI Codex, Claude и Gemini остаются редактированным потоком raw-terminal-v1 с явными ограничениями tool_lifecycle_opaque, usage_unavailable и artifacts_unclassified: Harness не угадывает структуру по тексту терминала.

Baseline eval и live compatibility matrix

Baseline eval фиксирует не только Git SHA и config hash, но и точную версию CLI, event schema и маршрут /v1|/v2. Без совпадения этих dimensions сравнение явно помечается несовместимым. Без запуска model task установленную матрицу можно проверить opt-in командой:

GPT2GIGA_RUN_CLI_COMPAT_MATRIX=1 GPT2GIGA_COMPAT_API_MODE=v2 \
  uv run pytest -q tests/live/test_adapter_compatibility_matrix.py

Structured continuity Codex

Для Codex main chat Harness дополнительно проверяет контракт codex app-server --help. Если доступен reviewed stdio JSON-RPC v2, первая реплика создаёт thread/start и turn/start, а следующие реплики используют тот же thread_id без нового TUI или codex exec --ephemeral. Один supervised app-server процесс может держать несколько совместимых Harness sessions как разные Codex threads. Явный Harness fork отображается в thread/fork, cancel — в turn/interrupt, а после смены owner Harness выполняет thread/read и thread/resume и сохраняет recovery outcome.

Durable link содержит только opaque runtime id, thread_id, последний turn_id, protocol/version evidence, status и неизменяемый execution snapshot. Route, model, managed home identity, source/effective workspace, permission mode и hash managed-MCP snapshot должны совпадать при продолжении; изменить их можно только через явный fork. Стабильный внутренний message id передаётся как clientUserMessageId, поэтому повторная доставка prompt блокируется. Raw stdio и PID app-server не попадают в browser. turn/*, item/*, tool, file-change и assistant delta преобразуются в обычные normalized Run events.

Structured app-server turns используют approvalPolicy=on-request и передают поддержанные command/file-change requests в durable Approval Center. Deny, timeout, unsupported request family и stale binding завершаются fail-closed; approval не выводится из скрытого user input. MCP secret refs разрешаются только на границе запуска owning process, после initialize удаляются из Harness-owned config, а durable metadata хранит только snapshot id/hash.

Если app-server contract не доказан, запрошенный native_structured блокируется. Явный compatibility command сохраняет codex exec --ephemeral --json, но full-history replay помечается degraded_replay, а не resume того же Codex thread. Direct Chat использует structured_replay. Gemini имеет отдельный durable ACP contract; Claude embedded structured остаётся blocked. Plugins по умолчанию остаются one_shot, пока versioned SDK manifest и conformance evidence не объявят другой проверенный contract.

Native session continuity

Для новых управляемых native-запусков Harness сохраняет неизменяемый безопасный execution snapshot: route v1|v2, model, managed home, workspace, project id, permission mode и hash управляемой tool-конфигурации. Этот snapshot переносится через sync, import, link и resume. Старые refs без snapshot помечаются route_unknown: перед resume нужно явно подтвердить api_mode, и неизвестный исходный route больше не подменяется молча на /v2. Противоречащие snapshot route, model, home, workspace, project или harness блокируются до запуска CLI.

Native discovery теперь берёт workspace/project identity из самой истории CLI, а не приписывает каждому внешнему ref проект, из которого запустили sync. Если такого evidence нет, ref явно остаётся unscoped и не попадает в project-filtered списки по умолчанию. CLI-list и file-backed записи с одинаковым native session id сводятся к одному стабильному metadata ref без автоматического импорта transcript. Большие выборки sync можно обходить через --limit и возвращённый --cursor. Когда управляемые Codex или Gemini записывают новую history, Harness автоматически связывает ref с owning run только при однозначном совпадении execution snapshot.

Native preflight и policy

Управляемые native start и resume для Codex, Claude Code и Gemini выполняют route-aware proxy preflight до spawn CLI. Harness сначала проверяет health, затем требует, чтобы точный выбранный route GET /v1/models или GET /v2/models принял настроенный локальный proxy key. Недоступный route, auth-enabled внешний proxy без GIGALOOM_API_KEY и запрещённый remote auto-start завершаются явной ошибкой до spawn. Новый loopback sidecar помечается как Harness-owned в безопасном plan evidence и останавливается при ошибке native startup до handoff; существующий proxy помечается external и никогда не останавливается. Созданный sidecar key передаётся напрямую в startup context CLI, а не восстанавливается из временного key cache UI-процесса.

Spawn native-процесса также проходит через общее действие Approval Center process.spawn до создания worktree, запуска proxy или spawn CLI. Профиль review_every_action возвращает approval, после которого исходный запрос можно повторить; deny не запускает процесс и не создаёт worktree. Для безопасной политики auto и явной worktree native-режим edit создаёт отдельный detached Git worktree и передаёт CLI только его effective path. Ошибка изоляции блокирует запуск без fallback в source checkout. Run, native link и безопасный plan сохраняют source/effective workspace и результат Harness policy.

После spawn permission enforcement остаётся делегированным конкретному CLI: Codex отображает plan|read в --sandbox read-only, а edit в workspace-write; Claude Code использует --permission-mode plan для plan|read и default для edit; Gemini использует --approval-mode plan и default соответственно. Интерактивные approval prompts внутри CLI явно помечаются delegated: Approval Center не заявляет, что видит или подтверждает их.

Durable native process и terminal transport

Для каждого управляемого native-процесса Harness теперь сохраняет в runtime.sqlite3 публичную запись ownership: owner и process id, lease, heartbeat, timeout/cancel state, terminal cursor и ограниченные redacted-ссылки на output. Сырые PTY и process handles остаются только у процесса-владельца. Другой UI/API-клиент может читать durable state и запросить cooperative cancel, но не может писать в неподтверждённый PTY или «усыновить» его. После истечения lease reconciliation явно фиксирует interrupted, exited или unknown, оставляет managed home и изолированный worktree для review, а живой orphan помечает process_alive_not_adopted без ложного reconnect.

Панель Native по умолчанию читает terminal output через аутентифицированный cursor-based SSE endpoint GET /api/native/processes/{process_id}/output/stream. Ограниченные batches несут монотонный cursor; reconnect принимает и query cursor, и браузерный Last-Event-ID, поэтому уже показанный output не дублируется. Ограниченный /output polling сохранён как compatibility fallback. Для PTY локального owner endpoint POST /api/native/processes/{process_id}/resize валидирует и применяет rows/columns; pipe transport и чужой owner завершаются явной ошибкой. При навигации и завершении terminal UI закрывает EventSource, polling timers и resize observer.

Доставка первого prompt в Gemini

Перед новым Gemini native-запуском Harness проверяет поддержку --prompt-interactive установленной версией CLI. Если flag доступен, составной prompt вместе с отрендеренными ссылками на attachments передаётся ровно в одном interactive invocation, без обрезания и повторной отправки через stdin. Run и native link сохраняют безопасные idempotency key, hash prompt, число байт, механизм и состояние pending|delivered|failed; сам prompt не копируется в command или plan metadata. Повторный browser submit с тем же key отклоняется и после перезагрузки UI. Старая версия Gemini без подтверждённого flag завершается явной ошибкой до spawn, а не открывает пустой terminal.

Транспорт вложений

Attachment capability теперь описывается по типу файла и transport отдельно для headless и native. У Codex изображение передаётся через --image только после успешной version-aware проверки этого флага; обычные файлы остаются безопасными path references, а rich image transport через app-server не заявляется. Claude Code и Gemini CLI получают изображения и документы только как ограниченные ссылки на путь, пока установленная версия CLI не докажет более богатый transport. UI, Smart Router и render-plan показывают это как reference-only, а не как полноценную multimodal-доставку. Legacy-поля supports_attachments и accepted_attachment_kinds сохранены для совместимости плагинов, но больше не используются как доказательство rich transport.

Checklist диагностики

Проверьте:

• доступен ли proxy по GIGALOOM_PROXY_URL;
• совпадает ли GIGALOOM_API_KEY с ключом gateway;
• есть ли GigaChat credentials для реального запроса;
• находится ли нужный внешний CLI в PATH;
• выбран ли ожидаемый backend route v1 или v2;
• запущен ли worker для durable и scheduled runs.

Перед публикацией diagnostics удалите секреты и приватный код. Runtime summary без raw payloads можно получить командами giga runtime inspect --json и giga runtime export.

CLI-справочник по задачам

Показать путь к пользовательской конфигурации и изменить executable override:

giga config path
giga config set executables.codex-cli /opt/tools/codex
giga config unset executables.codex-cli

Создать или проверить project cockpit:

giga project info --json
giga project init --name my-project --json

Посмотреть и запустить preset:

giga preset list --workspace .
giga preset run review --workspace . --dry-run

Проверить и запустить agent profile:

giga agent list --workspace .
giga agent show reviewer --workspace . --json
giga agent validate .giga/agents/reviewer.yaml
giga agent run reviewer --workspace . --prompt "Проверь patch" --dry-run

Управлять durable workflow:

giga workflow list --workspace .
giga workflow run review-team --workspace . --prompt "Проверь change" --json
giga workflow status <workflow_run_id> --json
giga workflow cancel <workflow_run_id>

Управлять project memory:

giga memory list --workspace . --json
giga memory add "Решение проекта" --workspace . --tag decision
giga memory disable <memory_id> --workspace .
giga memory enable <memory_id> --workspace .

Запустить eval или dry-run matrix:

giga eval list --workspace . --json
giga eval run smoke --workspace . --harness echo --json
giga eval run smoke --harness codex-cli,claude-code --dry-run

Проверить worker:

giga worker status
giga worker stop-on-idle --idle-seconds 30

Управлять schedule:

giga schedule list --workspace . --json
giga schedule show daily-review --workspace . --json
giga schedule run-now daily-review --workspace . --json
giga schedule pause daily-review --workspace . --json

Просмотреть Harness-owned session:

giga session list --workspace .
giga session show <session_id> --json

Обнаружить native sessions:

giga native sync --harness codex-cli --workspace . --json
giga native list --harness codex-cli --include-external --json
giga native import <native_ref_id> --json

Открыть session, run, diff, terminal или файл в настроенном editor:

giga open session <session_id>
giga open run <run_id> --diff
giga open run <run_id> --terminal
giga open file src/foo.py --workspace . --line 42

Проверить или экспортировать coordination state:

giga runtime inspect --json
giga runtime export --output /tmp/harness-runtime.json

Добавление собственного Harness

Новый plugin использует versioned provider-neutral entry-point group gigaloom.harness_adapters.v1; его import target не должен находиться в gateway namespace:

[project.entry-points."gigaloom.harness_adapters.v1"]
my-harness = "my_package.my_harness:MyHarness"

Встроенные harnesses публикуются в gigaloom.harnesses.v1. Внешние adapters используют gigaloom.harness_adapters.v1; все entry-point targets и Python imports находятся в gigaloom.*.

Начните со scaffold, затем проверьте metadata/capabilities и dry-run:

giga harness scaffold my-harness
giga harness validate my-harness --json
giga harness inspect my-harness --json
giga harness conformance my-harness --json

Adapter обязан явно описать execution modes, continuation, event schema, attachments transport, tool/policy ownership, required executable и redaction boundaries. Не объявляйте capability, которую не подтверждает probe или test.

Резервная копия пользовательского state и runtime export

Перед обновлением или откатом package остановите Cockpit, durable workers и активные runs, которые используют выбранный data directory. Создайте архив вне каталога Harness state и проверьте его до изменения установленной версии:

giga state backup --output ../gigaloom-state.zip
giga state verify ../gigaloom-state.zip --json
# после остановки Harness восстановите отсутствующий каталог или подтвердите замену
giga state restore ../gigaloom-state.zip --replace --json

Backup использует versioned content-addressed schema: относительные пути, детерминированные ZIP metadata, согласованные SQLite snapshots и SHA-256 для каждого файла. Transient lock, WAL, SHM и временные файлы не включаются. Создание fail-closed при symbolic link, неподдерживаемом типе файла, существующем destination, output внутри data directory или изменении source state во время capture.

Архив записывается атомарно с mode 0600, но не редактируется: в нём могут быть opt-in captured content, attachments и managed configuration. Храните его как приватный пользовательский state и не прикладывайте к issue. Для support используйте content-free coordination export:

giga runtime export --output /tmp/harness-runtime.json

giga state backup охватывает настроенный Harness user data directory (GIGALOOM_DATA_DIR, обычно ~/.gigaloom). Project-local .giga/ остаётся вне архива и должно входить в backup/version-control policy самого проекта.

giga state restore повторно проверяет архив, отклоняет runtime schema новее поддерживаемой установленным Harness, переносит retained modes и проверяет SQLite integrity в приватном sibling staging-каталоге, а затем публикует восстановленный каталог. Для существующего destination обязателен --replace; активные lock/WAL/SHM markers или параллельное изменение destination завершают операцию до swap. Более старая runtime schema обновляется только при следующем штатном открытии store установленным package. Reverse migrations не поддерживаются: для package rollback нужно восстановить pre-upgrade архив, созданный соответствующей версией. Команда не изменяет project-local .giga/.

Миграция со старого combined prerelease

Gateway и Harness теперь два самостоятельных дистрибутива и namespace. Перед переустановкой удалите обе старые tool installations, но не удаляйте runtime и project state:

uv tool uninstall gpt2giga
uv tool uninstall gpt2giga-harness
uv tool install 'gigaloom==0.9.1'
giga doctor

Текущая metadata gigaloom==0.9.1 сохраняет gpt2giga>=0.3.0,<0.4.0 в явном optional extra gpt2giga. Старый import gpt2giga.harness больше не является публичным; используйте gigaloom. Миграция package не переносит и не перезаписывает ~/.gigaloom, .giga/ или vendor-owned CLI homes.

Ручной QA checklist

• giga doctor . --json не показывает неожиданных secret values, абсолютного workspace path или user-home content;
• giga harness run echo завершается без сети и credentials;
• giga ui слушает loopback, а remote bind без opt-in и token блокируется;
• run переживает reload UI, а SSE reconnect не дублирует события;
• cancel/interrupt оставляет понятный final state и не бросает orphan ownership;
• plan|read не пишет в source workspace;
• edit использует isolated worktree и требует approval для apply/branch;
• native terminal восстанавливает cursor, принимает resize только от owner и закрывает EventSource при завершении;
• attachment UI показывает реальный transport, а не общий optimistic флаг;
• schedule нельзя включить без exact-hash Test now и live worker;
• export и browser API не содержат raw reasoning, credentials или secret refs.

Выбор модели и текущие ограничения

model в profile/request — клиентская модель. При GPT2GIGA_PASS_MODEL=True она передаётся gateway; при False gateway использует свою configured GigaChat model. Для Claude/Gemini через Harness выбранная upstream model закрепляется во внутреннем trusted context, но публичная форма ответа остаётся совместимой с исходным protocol.

Alpha не обещает stable API/SQLite/YAML contracts, high availability, multi-tenant isolation, полный контроль действий black-box CLI или rich attachments для любого adapter. Codex app-server и Gemini ACP поддерживают capability-proven durable structured continuity; Claude embedded structured execution остаётся blocked, а provider handoff не считается continuity. Всегда ориентируйтесь на giga harness inspect --json, а не на название установленного CLI.