Unified Harness

Alpha preview — prerelease

The gpt2giga-harness 0.4.x line is an alpha preview for testing and feedback. The UI, CLI, project YAML, runtime schema, and upgrade behavior can change while the product is being developed. Use it for local evaluation and supervised workflows, not as a production-critical or unattended multi-user service.

Unified Harness is a local project cockpit on top of gpt2giga. It gives you one place to run a task through direct GigaChat, Codex CLI, Claude Code, Gemini CLI, or a plugin harness; compare the results; inspect what happened; and decide which changes are allowed back into your project.

The Harness is not another model and it does not replace the compatibility gateway or the agent CLIs. It coordinates them and keeps a normalized local record of runs, approvals, artifacts, and reusable project automation.

Why use it

Working with several agent CLIs usually means different commands, histories, permission models, and output formats. Unified Harness adds a common layer for:

• one project cockpit — start from the current repository with giga ui;
• repeatable runs — save agents, prompts, evals, workflows, and schedules under .giga/ instead of rebuilding the setup for every task;
• comparison — send the same task to several available harnesses in Arena and inspect the results side by side;
• review before mutation — keep edit runs in isolated Git worktrees and put apply/branch actions behind explicit approvals;
• traceability — inspect durable run status, attempts, redacted events, artifacts, diffs, and provenance after the browser or UI server restarts;
• local control — keep project configuration and runtime history on your machine rather than introducing a hosted control plane.

Mental model

Layer	Responsibility
gpt2giga gateway	Exposes OpenAI-, Anthropic-, and Gemini-shaped HTTP APIs backed by GigaChat.
Unified Harness	Selects a harness and model, coordinates runs, stores local history, and exposes the CLI/UI.
Direct Chat or agent CLI	Performs the actual model or agent work. External CLIs remain responsible for behavior inside their own process.

This separation matters: an approval shown by Unified Harness covers actions it owns, such as spawning a run or applying a captured patch. It cannot claim to observe every internal action performed by a black-box external CLI.

Native CLI prefix contract

The native compatibility rule is literal: add exactly giga before the provider command. Harness does not invent one shared execution grammar.

giga codex exec --json "inspect this repository"
giga claude -p "inspect this repository"
giga gemini -p "inspect this repository"

After the provider token, argv is opaque. Provider-scoped --help and --version, stdin, stdout/stderr placement, raw bytes, JSON/JSONL, --, signals, and exit status stay native. Unknown commands and flags therefore keep working without waiting for a Harness parser update.

Situation	Example	Result
Human TTY	giga codex	Admitted Workbench L2, or a visible provider-owned L1 handoff on drift.
Pipe/stdin	printf 'task' | giga claude -p -	Native L0 descriptors and bytes.
Redirect	giga gemini -p task >result.txt	Provider stdout is written directly.
JSON	giga codex exec --json task	Provider JSON/JSONL remains unchanged.
CI	CI=1 giga gemini -p task	Prompt-free native L0 execution.
Resume	giga codex resume --last	Exact provider selector; admitted L2 or visible L1.
Structured drift	version outside the reviewed window	Only L2 degrades; valid L0 commands remain available.
Missing runtime	giga claude --version without Claude	Actionable startup failure before provider side effects.

Inspect the local truth with giga doctor --json. Each native provider entry reports the executable and source, version evidence, L0/L1/L2 state, structured transport, fallback, degradation reason, and remediation. The report is content-free and does not retain provider argv, prompts, or output.

Shell completion

Generate completion for the stable Harness boundary and source it according to your shell's normal startup conventions:

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

The scripts intentionally do not mirror upstream provider parsers. Once codex, claude, or gemini is selected, the suffix and -- remain untouched and the shell's default completion applies.

Install, migrate, and roll back

The standard wheel/sdist contains the TUI and native facade but no provider binary, Node.js runtime, credentials, or provider configuration. Both uv tool and pipx create an isolated Harness environment:

uv tool install 'gpt2giga-harness==0.4.1a1'
pipx install 'gpt2giga-harness==0.4.1a1'

Upgrade an existing optional-TUI prerelease in place; do not retain or add a [tui] extra. Before an upgrade, back up user-owned Harness state. Rollback is an exact package reinstall plus restoration of a verified pre-upgrade state archive when a state migration occurred:

giga state backup /safe/path/harness-before-upgrade.zip
uv tool install --force 'gpt2giga-harness==0.4.1a1'
uv tool install --force 'gpt2giga-harness==<previous-version>'
uv tool uninstall gpt2giga-harness
uv tool install 'gpt2giga-harness==0.4.1a1'

Uninstalling the package does not delete ~/.gpt2giga/harness, project .giga/, or native provider homes. Harness never reverse-migrates provider configuration or installs/authenticates a provider runtime.

Is the prerelease preview for you?

Try it now if you want to evaluate a local agent cockpit, compare harnesses, prototype reviewable workflows, or give feedback while the interfaces are still being shaped. Start with echo, dry-runs, plan/read modes, and a test repository before allowing edits.

Wait for a later release if you need a stable automation API, guaranteed backward compatibility, high availability, central multi-user administration, or a security boundary around arbitrary behavior inside third-party CLIs.

During the prerelease:

• read release notes before upgrading and back up ~/.gpt2giga/harness plus important project .giga/ definitions;
• expect optional features to depend on the exact Codex, Claude, or Gemini CLI installed on the workstation;
• keep the UI on its default loopback address unless you deliberately configure remote authentication and TLS;
• review generated .giga/ files before committing them, and never put secrets in project configuration;
• report bugs with giga doctor, the Harness version, reproduction steps, and redacted diagnostics in GitHub Issues.

Quickstart

1. Get the preview and check the workstation

The source checkout is the current, always-available preview path:

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

Keep the checkout virtual environment activated in every terminal used for the preview. You can then cd to the project you want to inspect while giga and gpt2giga continue to resolve from the checkout. On Windows, activate .venv\Scripts\Activate.ps1 instead.

If the standalone preview is available in your package index, the shorter install path is:

uv tool install 'gpt2giga-harness==0.4.1a1'
giga doctor

For Direct Chat and the gpt2giga provider preset, install the explicit extra:

uv tool install 'gpt2giga-harness[gpt2giga]==0.4.1a1'

The current gpt2giga-harness==0.4.1a1 distribution provides the giga and gpt2giga-harness commands; its explicit gpt2giga extra pins gpt2giga==0.2.4a1.

Requirements are Python 3.10–3.14 and uv. Direct GigaChat runs also need the gateway credentials described in the gpt2giga quickstart. Codex, Claude Code, and Gemini integrations require the matching external CLI executable on PATH (or an explicit executable override) plus a configured local gateway. The proxy-backed execution paths do not require a separate vendor login; the distinct Claude provider-owned handoff does. Unavailable CLIs stay disabled rather than breaking the cockpit.

Base install and optional providers

The provider-neutral base distribution has nine reviewed direct runtime dependencies. Release CI installs the Harness wheel on Python 3.10–3.14 across Linux, macOS, and Windows, runs terminal-command smoke, and runs a versioned audit that fails if the resolved environment exceeds 64 distributions or includes packages from these optional integration families:

• the gpt2giga/GigaChat provider preset;
• Office document readers and writers;
• remote messaging channels;
• external client or agent UI frameworks;
• sandbox and container providers.

Add those capabilities through the explicit gpt2giga extra, a separately installed provider distribution, or a Harness entry-point plugin. The base package does not install or silently enable them. The Codex, Claude Code, and Gemini adapters remain built in, but their separately managed CLI executables are discovered on PATH rather than installed as Python dependencies.

For release or package debugging, run this only inside a clean base-install environment; an environment with an intentionally installed optional provider is expected to fail the base-only audit:

python -I -m gpt2giga_harness.base_install --json

The source-checkout uv sync --all-packages --all-extras --dev command installs development tooling and repository integration fixtures, so it is not a base footprint measurement.

Terminal TUI and automation cutover

The standard install includes the canonical terminal workbench. Bare giga and the compatibility alias giga tui open it on a supported interactive terminal. Human giga chat, giga run --agent, and giga session list|show|create|turn deep-link into the same TUI while preserving the explicit workspace, session, Harness, model, mode, transport, and prompt intent.

Use the non-interactive CLI for scripts and administration. --non-interactive, --json, --dry-run, redirected streams, pipes, CI, help/version, admin commands, and session event/approval inspection do not initialize Textual, prompt, or emit terminal-control sequences. giga open ... remains an explicit external handoff. An explicitly requested TUI fails before import under TERM=dumb or an unsupported terminal; a redirected human command keeps its established CLI schema, bytes, exit code, and stdout/stderr discipline.

To migrate from the optional-TUI prerelease, upgrade the standard package and remove [tui] from install commands:

uv tool install --force 'gpt2giga-harness==0.4.1a1'
giga --version
giga

Rollback installs the exact previously reviewed version with uv tool install --force 'gpt2giga-harness==<previous-version>'. uv tool uninstall gpt2giga-harness removes the package and commands but does not delete the user-owned Harness runtime data.

2. Initialize a disposable or test project

Run the first tour in a repository where generated project files and test edits are safe to inspect:

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

giga doctor [workspace] gives the first-run readiness verdict before any agent is spawned. Its structured --json form covers proxy and route health, model discovery, external CLI versions, workspace and Git readiness, the durable worker, Harness-managed homes, and managed MCP snapshots. Checks are classified as ready, degraded, or blocked; degraded and blocked prerequisites include a remediation command. The report redacts secret values, does not publish an absolute workspace path, and reads existing runtime worker state without rewriting it. It also carries a stable report kind plus exact Harness/gateway, Python, and platform metadata; external CLI compatibility is embedded from the same bounded capability probes used for execution.

For CI, choose the failure threshold explicitly. blocked returns exit code 1 only for blocked checks; degraded returns 1 for either degraded or blocked checks. Without --fail-on, doctor keeps its interactive exit-code-0 behavior. For an issue report, --output atomically writes the same canonical, redaction-safe JSON with mode 0600 while stdout keeps the selected human or JSON format:

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

giga init creates non-secret starter configuration, agent profiles, prompts, an eval, and a review workflow under .giga/. Existing files are not replaced unless you pass --overwrite.

Before connecting a real model, verify the local execution path with the credential-free echo harness:

giga harness run echo \
  --workspace . \
  --prompt "Summarize the selected task"

For a complete disposable tour, use the first-run demo repository. It contains only fictional inventory inputs. The walkthrough copies them to a temporary Git repository, isolates Harness runtime state under that copy, runs giga init and giga doctor ., then verifies a read-only Echo run and the two generated smoke-eval cases. It needs no credentials, proxy, external agent CLI, or public-network access.

The model-backed issue-to-reviewed-patch example packages three reviewed agent profiles, a durable workflow that retains edits in a Harness-owned worktree, and a post-apply eval. Its walkthrough keeps the source checkout unchanged before approval and leaves apply, commit, push, and hosted writes as explicit operator decisions.

The model-backed nightly compatibility guardian packages a pinned Codex/Claude/Gemini eval, exact baseline dimensions, a read-only triage workflow, and a durable nightly schedule. It runs while the UI is closed and moves only a failed, previously tested schedule contract into Attention for product/adapter/model/environment classification.

The model-backed cross-harness review team fans out read-only explorer, security, tests, and maintainability roles across Codex, Claude, and Gemini. One synthesis step cites retained child artifacts; a failed child remains visible and the workflow cannot silently report partial evidence as success.

Preview an external agent command without launching it:

giga run \
  --agent codex \
  --mode read \
  --workspace . \
  --dry-run \
  "Summarize this repository"

3. Connect GigaChat

For browser and durable-worker runs, keep the gateway running in a separate terminal. Activate the same source-checkout environment in that terminal, then run:

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

With tool installations, install/expose the gateway command separately as described in the gpt2giga quickstart, then run gpt2giga.

In another terminal, inspect the harness environment:

giga doctor
giga harness list

If the proxy is not running, giga chat, giga harness run direct-chat, and real external agent CLI runs try to start a local sidecar by default. Disable that for a single command with:

giga chat --no-start-proxy --api-mode v2 --model GigaChat-2-Max "Привет"

Run direct Chat Completions smoke tests through explicit backend routes:

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

The same flow through the generic harness command:

giga harness run direct-chat \
  --api-mode v2 \
  --model GigaChat-2-Max \
  --prompt "Hello from the harness"

4. Open the project cockpit

Open the local UI:

giga ui

Then open http://127.0.0.1:8091/. A useful first tour is:

1. Confirm the current project and selected session in Workbench.
2. Select echo and submit a harmless prompt.
3. Open Runs and inspect the attempt, trace, and stored redacted payloads.
4. Open Evaluation → Arena to compare available harnesses on one task.
5. Inspect Approvals, Attention, Automation, Evaluation, and Integrations before enabling edits or unattended execution.

Cockpit V2 is the default local UI. The previous no-build cockpit remains at http://127.0.0.1:8091/legacy for one release-level rollback window; switching between the two does not migrate or rewrite Harness runtime state.

For a retained assistant response, Copy fetches and copies the full text even when the feed shows only a bounded preview. For structured and one-shot runs, the pencil appears only on the latest user message. Editing and resubmitting it replaces that active chat turn and removes its following assistant response from the conversation; the superseded run remains available in Runs as append-only audit evidence. Native terminal sessions do not expose the pencil because a retained interactive process cannot be rewound safely.

giga ui starts a local durable worker automatically when no online worker is registered. Use giga ui --no-start-worker when a separately supervised worker already exists or when the UI should only inspect durable state.

The standalone worker owns durable structured and one-shot UI runs, leases, heartbeats, timeouts, retries, and cancellation, so a run survives a browser or UI-server restart. Arena children and Eval case/harness pairs use the same independent durable jobs and update their transparent parent JSON records as attempts finish. Use giga worker status to inspect registered workers, or run a temporary worker with giga worker stop-on-idle --idle-seconds 30. Workers deliberately do not auto-start a proxy: start gpt2giga yourself and configure GPT2GIGA_HARNESS_API_KEY when a harness needs the proxy. This avoids treating the UI process's temporary sidecar key cache as durable worker state.

The Runs area is the durable queue and history view. It filters queued, running, blocked, approval-needed, failed, canceled, and completed jobs; shows attempt count, retries, duration, selected metrics, and worker ownership; and reconnects to active SSE streams after a browser or UI-server restart. Opening a run loads a bounded hierarchical trace first. Individual redacted event payloads and artifacts are fetched only when inspected, and model reasoning is never exposed by the trace API or rendered in the timeline. Safe retry is available only when the latest failed attempt declares a read-only, deterministic, or otherwise retry-safe idempotency class.

The lightweight Runs Center API is cursor-paginated:

GET  /api/runs?status=running&limit=25&cursor=...
GET  /api/runs/{run_id}/summary
GET  /api/runs/{run_id}/trace?limit=100&cursor=...
GET  /api/runs/{run_id}/events/{event_id}
POST /api/runs/{run_id}/retry

The Approvals area is the policy inbox for actions owned by Unified Harness. The shared taxonomy covers workspace reads/writes, process and network access, MCP server/tool actions, git apply/branch, external writes, and schedule operations. Each decision records whether enforcement is owned by the Harness, delegated to a CLI sandbox, or advisory/unobservable. The UI never claims that it can inspect arbitrary actions inside black-box Codex, Claude, or Gemini subprocesses.

Interactive runs use the interactive profile by default. Select review every action in Advanced settings to persist a pre-spawn approval and put the durable job in waiting_approval without creating an attempt, process, or lease. An approval requeues the same logical job; denial cancels it. Apply and branch actions always require an approval before mutating the source checkout. Allow-once grants are consumed, run grants stay scoped to one run, and project grants require an expiry.

GET  /api/policy/profiles
GET  /api/approvals?status=pending
POST /api/approvals/{approval_id}/decision

Scheduled jobs

Project schedules are shareable YAML definitions under .giga/schedules/<schedule_id>.yaml; mutable enablement, next-run state, and occurrence history stay in runtime.sqlite3. A schedule captures an immutable, redacted content hash and snapshot of its agent, preset, workflow, or eval target. Editing any material field pauses the schedule and invalidates its previous Test now grant.

One-shot, fixed interval, and RRULE cadence are supported with an explicit IANA timezone. Occurrences are stored as UTC instants. Nonexistent spring-forward times are recorded as misfires, and ambiguous fall-back times run once at the first instant. The default overlap and misfire policies both skip rather than silently catch up or run concurrent copies.

The local worker evaluates due schedules before claiming ordinary jobs, so an open browser is not required. Enable is blocked until the exact schedule hash passes backend Test now and a live worker is registered. Scheduled edits use the unattended policy profile and fail closed unless an isolated Git worktree can be created; schedule.unattended_edit remains approval-gated. Resume mode serializes work per session and stores its explicit history cutoff.

giga schedule preview schedule.yaml --workspace /path/to/project --json
giga schedule create schedule.yaml --workspace /path/to/project --json
giga schedule list --workspace /path/to/project --json
giga schedule test-now daily-review --workspace /path/to/project --json
giga schedule enable daily-review --workspace /path/to/project --json
giga schedule run-now daily-review --workspace /path/to/project --json
giga schedule pause daily-review --workspace /path/to/project --json

The authenticated API exposes matching CRUD, preview, test, enable/pause, resume, and run-now operations under /api/schedules. Create/update, enable, and run-now use the shared Approval Center policy actions. Deleting a schedule archives its SQLite audit state instead of erasing occurrence history. The top-level Scheduled area adds list, upcoming-calendar, and immutable-history views plus a typed wizard for target, cadence, destination, worktree isolation, concurrency, retry/misfire policy, and notifications. It explains the exact-hash Test now gate and worker-online requirement before enable.

The same area contains the project Attention Inbox. Pending approvals, failed durable jobs, and schedules in needs_attention are derived from their source audit records rather than copied into a second queue. Marking an item read only stores acknowledgement state in runtime.sqlite3; it never deletes the job, approval, schedule snapshot, or occurrence history. Desktop notifications are optional, browser-session-only, and link back to the relevant approval, run, or schedule. A schedule must opt in to schedule-finding notifications explicitly.

GET  /api/automation?workspace=/path/to/project
GET  /api/attention?workspace=/path/to/project
POST /api/attention/read

The top-level Tools area is the MCP connection center. It shows redacted project descriptors, transport and trust state, per-harness compatibility, latest health, discovered server instructions, tools/resources/prompts, input and output schemas, risk labels, and bounded probe history. It does not execute tools or write harness config.

From a project directory, inspect or initialize the project cockpit config:

giga project info
giga project init
# Short alias:
giga init

By default the UI binds to 127.0.0.1:8091. Local requests receive an opaque HttpOnly, SameSite=Strict browser-session cookie. To bind remotely, configure a strong bootstrap token in the environment and opt in explicitly:

export GPT2GIGA_HARNESS_UI_BOOTSTRAP_TOKEN="$(openssl rand -hex 32)"
export GPT2GIGA_HARNESS_UI_ALLOWED_HOSTS=harness.example.internal
giga ui --host 0.0.0.0 --allow-remote

Terminate TLS in front of a remote listener: remote cookies are Secure, the bootstrap token is exchanged through Authorization: Bearer ..., and it is never accepted in a URL. Without remote authentication, data APIs return 401 and mutating APIs fail closed with 403. Host and same-origin checks apply to the shell, API, assets, and SSE connections.

Treat the bootstrap token as same-principal operator access, not as a tenant or read-only credential. An authenticated operator can select any workspace the Harness OS account can access, preview supported files, and start approved processes there. Share the token only with operators who may act with that OS account's filesystem and process privileges.

Configuration

CLI flags override environment variables. Useful variables:

GPT2GIGA_HARNESS_PROXY_URL=http://127.0.0.1:8090
GPT2GIGA_HARNESS_API_KEY=<local-proxy-api-key>
GPT2GIGA_HARNESS_DEFAULT_MODEL=GigaChat-2-Max
GPT2GIGA_HARNESS_DEFAULT_API_MODE=v2
GPT2GIGA_HARNESS_UI_HOST=127.0.0.1
GPT2GIGA_HARNESS_UI_PORT=8091
GPT2GIGA_HARNESS_UI_BOOTSTRAP_TOKEN=<strong-random-secret-for-remote-ui>
GPT2GIGA_HARNESS_UI_ALLOWED_HOSTS=harness.example.internal
GPT2GIGA_HARNESS_AUTO_START_PROXY=True
GPT2GIGA_HARNESS_PROXY_START_TIMEOUT_SECONDS=15
GPT2GIGA_HARNESS_TIMEOUT_SECONDS=3600
GPT2GIGA_HARNESS_DATA_DIR=~/.gpt2giga/harness

Cockpit Settings exposes separate defaults for chat requests and generated session titles. Use Discover models and select both values from the models reported by the active API route. The choices are stored in settings/defaults.json under the Harness data directory and apply to new runs; when the title model is cleared, title generation uses the selected chat model. GPT2GIGA_HARNESS_DEFAULT_MODEL or GIGACHAT_MODEL continues to lock the chat default when it is environment-owned.

If GPT2GIGA_HARNESS_API_KEY is not set, the harness falls back to GPT2GIGA_API_KEY for calls to the local proxy. It never passes GIGACHAT_CREDENTIALS, OAuth tokens, certificates, or .env contents to external agent CLIs.

Auto-start is local-only. It supports http://127.0.0.1:<port>, http://localhost:<port>, and http://[::1]:<port>. It refuses remote hosts, does not create fake upstream credentials, and starts the child proxy with a generated local GPT2GIGA_API_KEY if one is not already configured.

External agent harnesses run the same proxy preflight before launching Codex, Claude Code, or Gemini CLI. If a sidecar is started, the generated local proxy key is passed only through the agent-specific local API-key environment variable and remains redacted from JSON/UI results.

Provider and Route Profiles

Cockpit Settings → Provider and Routes & models manage backend-owned profiles for OpenAI-, Anthropic-, and Gemini-compatible endpoints. A provider owns its protocol dialect, base URL, route prefix, authentication ownership, enabled/offline state, and purpose-specific model defaults. New runs freeze the selected provider and route into their execution snapshot, so later settings changes do not rewrite retained evidence or an active structured session.

Credentials are references, never form values. Settings and the CLI accept an environment-variable or keychain reference and return only its kind and name; the secret value is resolved only at the owning request or subprocess boundary. Literal credentials, credential files, and unrestricted filesystem paths are rejected by the provider settings service.

For example, register an OpenAI Responses-compatible endpoint whose key remains in 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 and discover are explicit bounded operations. A missing probe backend, authentication failure, or incompatible endpoint is reported as content-free health evidence and does not silently select another provider. Edit requires the current revision from show or Settings, which prevents an older browser or CLI request from overwriting a newer configuration:

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

Legacy proxy/API-mode/model defaults remain readable during the prerelease transition. Migrate them only through the forward-only, backup-gated flow:

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

The migration revalidates source and target state under a lock before publishing the provider registry and journal. There is no reverse migration: stop Harness and restore the verified pre-upgrade archive if rollback is required.

Project Config

giga project init creates a non-secret .giga/harness.toml in the current project root. If the command runs inside a git repository, the git top-level directory is used as the project root; otherwise the current directory is used.

The config stores project defaults such as harness, model, explicit v1/v2 API mode, mode, enabled harnesses, presets, and future attachment safety defaults. It must not contain API keys, tokens, cookies, credentials, private keys, certificates, or .env contents.

Project init also creates safe prompt templates under .giga/prompts/ and a local smoke eval under .giga/evals/smoke.yaml. Presets can render inline prompt text or a relative prompt_file inside the project root. Supported template variables are:

• {{project_name}}
• {{branch}}
• {{selected_files}}
• {{selected_files_inline}}
• {{last_run_diff}}
• {{user_prompt}}

The same variables can also be written as ${project_name} or $project_name. Preset files are never allowed to point outside the project root.

giga ui also keeps mutable, non-secret cockpit state per project under the harness data directory. This includes the last selected harness, model, API mode, run mode, invocation mode, and selected session. It is intentionally local state, not repository config.

Use JSON output when wiring tools or checking what giga ui will use:

giga project info --json
giga project init --name my-project --json
giga preset list --json
giga preset run fix_tests --prompt "focus on tests/harness" --dry-run --json

In the browser cockpit, preset chips fill the composer with the rendered prompt and preset defaults. They do not execute automatically; use Run or Compare after reviewing the filled request.

Reusable Agent Profiles

Project agents are reusable role/configuration profiles over existing harnesses. They live in .giga/agents/*.yaml; giga init creates Planner, Explorer, Implementer, Reviewer, Test Runner, and Release Assistant starters. Profiles can bind instructions, harness/model/reasoning effort/route, context and memory selectors, MCP tool descriptor ids, fixed allow/deny tool selectors, permission/workspace policy, budgets, and an expected artifact. They never contain literal secrets, arbitrary CLI flags, or paths that escape the project.

giga agent list --workspace .
giga agent show reviewer --workspace . --json
giga agent validate .giga/agents/reviewer.yaml
giga agent run reviewer --workspace . --prompt "Review this patch" --dry-run

The first-class /agents Agent Studio lists and validates profiles, previews a redacted diff, checks the source SHA-256 ETag, and performs an explicit atomic Apply. Duplicate creates a draft until Apply is selected. The same reusable project authoring service is intended for later Workflow Builder and Schedule Wizard surfaces; those features must not write project YAML directly.

Run as Agent submits a normal durable manual job. Agent Studio resolves every operational field into an effective, delegated, or unsupported execution outcome before queueing. The API and each run store the immutable redacted agent_profile_snapshot, agent_execution_plan, requested/effective values, enforcement source, and agent_id, so later YAML edits do not rewrite history. Unsupported safety or budget options block queueing; provenance-only selectors produce explicit warnings. Live activity remains in Work and Runs rather than being duplicated in Agent Studio.

Current adapter option contract (structured admission can narrow it further):

Profile option	Codex CLI	Claude Code	Gemini CLI
model, route, mode, workspace/permission policy	effective	effective	effective
timeout and retry attempts	Harness-enforced	Harness-enforced	Harness-enforced
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 describes a standalone agent run; larger fan-out belongs to a Workflow or Schedule coordinator. Selected tool_ids must name enabled, trusted, adapter-compatible project MCP profiles. They are frozen before queueing and materialized only into the active temporary execution home. A structured driver can reject an option whose projection is not yet proven; for example, Gemini ACP currently rejects managed MCP projection instead of falling back to the one-shot path. Prompt files, skills, and context/memory selectors remain visible as unsupported provenance. Tool selectors are values for fixed adapter flags and can never inject additional flags.

Authenticated APIs:

• GET /api/agents and GET /api/agents/{agent_id};
• POST /api/agents/validate;
• POST /api/agents/{agent_id}/draft and /apply;
• POST /api/agents/{agent_id}/duplicate and /run.

Versioned Workflows

Project workflows are bounded DAG definitions under .giga/workflows/*.yaml. giga init installs a read-only review-team starter that plans, fans out to security/test-gap/maintainability reviews, and synthesizes their results. Every run stores the exact SHA-256 definition hash plus immutable workflow and step snapshots, so later YAML edits cannot rewrite execution history.

The version 1 IR supports agent, arena, eval, explicit approval, safe built-in transform, and join steps. Definitions may set dependencies, on_success/on_failure/always conditions, bounded concurrency and fan-out, retries, timeouts, typed input maps, output names, and artifact references. Cycles, unknown dependencies, arbitrary transform code, more than 64 steps, or fan-out above 16 fail validation. Arbitrary shell nodes are intentionally not part of the workflow IR.

giga workflow list --workspace .
giga workflow show review-team --workspace . --json
giga workflow validate .giga/workflows/review-team.yaml
giga workflow run review-team --workspace . --prompt "Review this change" --dry-run
giga workflow run review-team --workspace . --prompt "Review this change" --json
giga workflow status <workflow_run_id> --json
giga workflow cancel <workflow_run_id>

Agent, arena, and eval work is submitted through the same durable job worker as manual Runs. Workflow cancellation persists first and propagates to every active child job. Explicit approval steps enter waiting_approval and reuse the Approval Center; no process or lease is created for the approval node itself. Safe transform/join nodes run locally without arbitrary code execution.

The built-in Review Team is the first collaborative workflow rather than an Arena alias. Planner output is summarized and handed to three parallel reviewers; their summaries and selected artifact references are then handed to the Synthesizer. Handoffs are redacted and bounded to 8,000 characters and 16 artifact references per dependency. Each child job retains its immutable agent profile snapshot, including its harness, model, reasoning effort, tools, permission profile, and budgets.

Editing agents are always forced into a distinct detached Git worktree, regardless of a weaker policy in their profile. Worktree preparation fails closed and never falls back to the source checkout. Completed, failed, and interrupted worktrees remain available for review until explicitly discarded. Their visible output is projected into a strict handoff vocabulary: plan, selected_files, patch, diff, test_report, review_findings, and pr_draft. Read-only reviewers can receive bounded patch/test previews without write access or private reasoning.

Patch selection is explicit. The runtime detects file-level overlap, refuses conflicting merge queues, and prepares non-overlapping combinations in another retained worktree. Choosing, reviewing/applying, and discarding remain user actions; applying a combined queue requires an auditable git.apply approval. The harness never auto-applies or auto-pushes team output.

Work exposes the selected run's team in the Team inspector tab. Runs exposes the same live parent/child tree with step status, active work, concurrency, model/budget metadata, artifact counts, and deep links to the shared task or an individual child run. The workflow-level concurrency cap continues to govern fan-out, and cancel propagates through the same durable job runtime.

Authenticated APIs:

• GET /api/workflows and GET /api/workflows/{workflow_id};
• POST /api/workflows/validate and POST /api/workflows/{workflow_id}/run;
• GET /api/workflow-runs/{run_id} and POST /api/workflow-runs/{run_id}/cancel;
• GET /api/workflow-runs/{run_id}/handoffs, plus explicit per-step choose and discard actions;
• POST /api/workflow-runs/{run_id}/merge-queue and approval-gated /merge-queue/apply.

The top-level Workflows area is a catalog and form/step builder over this same execution IR. It shows a dependency-level DAG preview and per-definition run history, supports atomic optimistic-lock saves, and archives the previous YAML under .giga/workflows/.history/<workflow_id>/. Typed form edits merge into the exact YAML source, preserving unknown top-level and per-step fields so a newer definition is not silently damaged by an older UI.

Catalog actions include duplicate, YAML import/export, and three starter templates: Plan-Implement-Test-Review, Diagnose-Fix-Regression, and Issue-Patch-PR Draft. Free-form drag-and-drop graph editing remains deferred; step ordering and dependencies stay explicit and validated.

Additional catalog APIs:

• POST /api/workflows/import;
• PUT /api/workflows/{workflow_id} with expected_hash and an optional typed form merge;
• POST /api/workflows/{workflow_id}/duplicate;
• GET /api/workflows/{workflow_id}/export.

Project Memory

Project memory stores explicit, user-approved project facts and decisions under the harness data directory:

projects/<project_id>/memory.jsonl

Only enabled entries are injected into future session runs for the same project. The injected entries are also recorded in run.metadata.project_memory and the redacted raw request, so each run shows exactly which memory was included. Disabled entries remain visible for review but are not sent to harnesses.

Manage memory from the CLI:

giga memory list --workspace . --json
giga memory add "Use Alembic migrations" --workspace . --tag decision
giga memory disable <memory_id> --workspace .
giga memory enable <memory_id> --workspace .
giga memory delete <memory_id> --workspace .

The browser cockpit exposes the same workflow in the Memory inspector tab, including adding entries, editing text, enabling/disabling, deleting, and promoting the latest chat message to memory.

The matching API surface is:

GET    /api/project/memory
POST   /api/project/memory
PATCH  /api/project/memory/{memory_id}
DELETE /api/project/memory/{memory_id}

Memory text, tags, and metadata pass through the same secret-looking value redaction used by sessions and raw records before storage or API/UI output.

Run Preflight

Session-backed runs pass through a local pre-run safety check before a harness is invoked. The report scans prompt text, enabled project memory, previous chat messages, and selected attachments for private-key material, token-looking values, credential assignments, .env-style files, deny-listed paths, git-ignored workspace files, and large attachments.

The same report now contains a machine-readable readiness projection for the selected execution plan: harness availability, invocation mode, exact API route/model, required workspace/Git policy, managed state, and synchronous or durable delivery. Only relevant checks are selected. A missing proxy or agent CLI cannot block Echo, while a missing selected executable or Git repository required for an isolated edit blocks before process or worktree creation. Every non-ready check carries a redaction-safe remediation message and command shared with giga doctor.

Hard-block findings stop the run before HarnessRun, messages, raw requests, or external CLI processes are written. Warning findings are saved in run.metadata.preflight, included in the redacted raw request, and emitted as a warning event when a run continues. The browser UI calls the same check through:

POST /api/preflight/run

The response includes hard_block, the selected-plan readiness report, a list of content findings with safe remediation actions, and a context budget estimate covering prompt length, enabled memory, attached files, image count/size, previous chat turns, and truncation warnings. For attachment findings, the UI can remove the file from the current composer selection or send only an @path reference. Continue anyway is shown only for warning-level findings, not hard blocks.

Reviewed bootstrap and execution assurance

giga bootstrap provides an auditable first-run path without merging discovery and mutation. Preview runs doctor read-only and returns a deterministic plan_id; apply accepts only that current plan and explicitly selected reversible steps:

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

The application journal records only bounded identities and paths created by Harness. Rollback removes an item only while it still matches that journal and fails closed if the workspace, data root, or generated content has changed. Bootstrap never installs providers, resolves credentials, starts external processes, or enables schedules.

Run the side-effect-free compatibility guardian before a model-backed matrix:

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

The guardian checks the reviewed Codex, Claude, and Gemini CLI windows, native protocol admissions, Adapter and Integration SDK/schema versions, and marketplace source contracts. It does not start providers or integrations and returns exit code 1 when a required fixture is blocked. Cockpit uses the same read-only report from GET /api/compatibility/guardian.

Each run preflight also projects a content-free permission simulation for the exact Harness, provider route, execution transport, workspace policy, and extension snapshot. Filesystem, command, network, secret, integration, provider, and Git/GitHub actions are classified as allowed, approval-required, denied, or unknown and as pre-start, runtime-dependent, or provider-owned. A denied required action blocks startup; runtime-dependent and provider-owned actions are never presented as guaranteed grants.

Runs Center can create a Trace-to-Replay comparison that changes exactly one model, provider, Harness, or extensions axis. Preview hashes the retained source evidence and every unchanged dimension. Starting the reviewed manifest creates a new session, uses the existing execution authority, and never applies a patch automatically. The retained comparison reports normalized outcome, usage, tool, artifact, environment, and evidence deltas without requiring external telemetry.

For a transfer without target execution, create a truthful handoff capsule:

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

The capsule is a verifiable content-free snapshot of the task and evidence identities, Git environment, pending approvals, target compatibility, and continuity limits. It neither starts the target nor claims that provider-owned history can be resumed. Runs Center and GET /api/runs/{run_id}/handoff-capsule expose the same contract.

Tool Profiles

Projects can define non-secret tool profiles in .giga/harness.toml:

[tools.github]
enabled = true
title = "GitHub"
kind = "mcp"
description = "Project issue and PR tools"
harnesses = ["codex-cli", "claude-code", "gemini-cli"]

[tools.github.config]
readonly = true

The legacy profile APIs remain available as a side-effect-free compatibility preview:

GET  /api/tools
POST /api/tools/sync

The Tools area can also preview, apply, and roll back trusted MCP connections in Harness-owned Codex, Claude, and Gemini homes:

POST /api/tool-config/preview
POST /api/tool-config/apply
POST /api/tool-config/rollback

Preview returns the exact redacted diff and a current-content hash. Apply requires that hash, takes a per-home lock, writes atomically, records an ownership marker and content hash, and keeps the previous content as a backup. Rollback succeeds only while the ownership marker and hash still match. Config changes are rejected while a managed native process owns the home. User-owned ~/.codex, Claude, and Gemini settings are never changed.

Only enabled, trusted servers are composed. Native-home preview/apply never copies secret references into persistent CLI config. For process-backed AgentProfile runs, selected tool_ids instead create an immutable descriptor-free public snapshot reference plus a content-verified internal snapshot under the Harness data directory. Replay reuses the same snapshot even if project TOML changes. A structured driver must separately prove its MCP projection; unsupported combinations fail before execution. The adapter resolves allowed secret references only while constructing the subprocess config, writes the exact reviewed entries into its temporary active home, and exposes only descriptor-free snapshot identity in run provenance. Temp-home contents disappear after the process; user-owned homes remain unchanged. No package installation or OAuth occurs.

MCP profiles can additionally describe a stdio or Streamable HTTP connection:

[tools.issues]
enabled = true
title = "Issue MCP"
kind = "mcp"
harnesses = ["codex-cli", "claude-code"]
transport = "stdio"
command = "issue-mcp"
args = ["--readonly"]
timeout_seconds = 10
trusted = false

[tools.issues.env.ISSUE_TOKEN.secret_ref]
kind = "environment"
name = "ISSUE_MCP_TOKEN"

[tools.search]
enabled = true
kind = "mcp"
transport = "streamable_http"
url = "https://mcp.example.test/rpc"

[tools.search.headers.Authorization.secret_ref]
kind = "environment"
name = "SEARCH_MCP_AUTHORIZATION"

[tools.search.risk_policy]
low = "allow"
medium = "ask"
high = "deny"

Environment and headers accept literal non-secret values or an explicit secret_ref. Sensitive authentication headers reject literal values. URLs are restricted to HTTP(S) without embedded userinfo; probe responses are bounded to 1 MB and timeouts must be positive. Stdio probes receive a minimal environment plus explicitly resolved profile values rather than the complete parent environment. Discovery negotiates the MCP 2025-11-25 protocol, includes the negotiated version on subsequent HTTP requests, and refuses HTTP redirects so authentication headers cannot cross to another origin.

An MCP probe performs only initialize, tools/list, resources/list, and prompts/list. Starting an untrusted stdio server or connecting to a new HTTP origin creates a project-scoped Approval Center request. After approval, retry the probe. Results are appended as redacted JSONL under GPT2GIGA_HARNESS_DATA_DIR/tools/probe_history.jsonl:

GET  /api/tool-servers?workspace=...
GET  /api/tool-servers/{server_id}?workspace=...
POST /api/tool-servers/{server_id}/probe

MCP tool invocation remains disabled. External CLI MCP usage is labeled delegated_to_cli_sandbox and opaque unless a structured adapter emits explicit call/result events. Agent run snapshots record the bound server ids and this enforcement boundary as configuration provenance.

Federated Skills and MCP installation

The Cockpit Plugins area can filter Built-in packages from External Skills & MCP discovered through the offline catalog. The skills-sh source contributes hosted Skill metadata through the separately deployed read-only proxy, while neuraldeep contributes public Skill and MCP metadata. Source popularity, curation, health, or presence is discovery evidence only: it never grants installation authority, enables network access, or replaces an exact artifact review.

The Skills, Plugins, and MCP pages each expose their matching Add action. Search queries read NeuralDeep directly. To include skills.sh, run the metadata proxy and pass its fixed origin to the Harness UI:

export GIGA_SKILLS_PROXY_ORIGIN=http://127.0.0.1:8092
giga ui

Add Skill accepts a public GitHub repository or /tree/<ref> URL, pins the resolved commit, lists bounded SKILL.md candidates, previews the selected instructions, normalizes portable frontmatter, and installs only after the exact preview is approved. Add Plugin uses the same immutable inspection but requires a reviewed integration-package.json for a compatible native Plugin/Extension target. Add MCP accepts an exact stdio or HTTP descriptor and can install it into Codex, Claude, Gemini, or the Harness-managed inventory.

Existing shared Skills are also visible and filterable by Harness. By default, Harness scans ~/.agents/skills as shared root Skills and the native Codex, Claude, and Gemini Skill homes. Set GIGA_ROOT_SKILLS_DIRS to an OS-path-separated list when the shared roots live elsewhere. Inventory reads metadata only; full SKILL.md content is loaded for the bounded preview after an item is selected.

Harness preserves the last good catalog snapshot when a source is unavailable, rate-limited, requires renewed authentication, or returns invalid data. An external Skill becomes installable only after its bytes match a reviewed immutable reference and content hash and its bounded SKILL.md and files pass validation. A NeuralDeep MCP card is localized discovery metadata. It can link to an official MCP Registry package only by exact official package name or canonical repository identity; the official version, immutable reference, and integrity remain authoritative.

Inspect the offline inventory, then create a single-target 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 binds the exact package and artifact hashes, target, scope/root owner, configuration, permissions, network and native-consent boundaries, risk, and approval hash. Apply rejects a stale or widened plan. managed_home is the safe default; project scope requires --workspace, and user_home remains disabled unless the preview and apply explicitly admit it. Secrets remain opaque references and are resolved only by the owning subprocess. To update an installed package, select the new immutable pin and complete a new preview and approval; catalog drift cannot update an existing installation implicitly.

For a reviewed catalog Skill or MCP package, an all-supported group keeps a separate child plan and transaction for every target:

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 expand to Codex, Claude, and Gemini Skill targets. MCP packages expand to their three managed native homes plus Harness-managed MCP inventory. Every child preview must succeed before mutation begins. Cross-root apply is a recoverable compensating transaction, not a filesystem-atomic write: a partial failure rolls back owned, verified children in reverse order or records exact repair actions for group-recover. Status exposes verification and repair-required state; rollback refuses unowned or drifted files.

Portable Extension Packs bind one reviewed Skill and one reviewed MCP catalog entry to an exact pack id and semantic version. Preview builds a content-free compatibility matrix for Codex, Claude, Gemini, and Harness-managed targets, excludes incompatible providers explicitly, and compiles every supported child into one recoverable group plan:

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

The plan binds immutable package integrity, exact MCP configuration, permissions, native consent, included targets, and all child plan ids. Apply cannot widen that set. Recovery and rollback use the same grouped lifecycle. Cockpit exposes the flow as Portable Extension Pack with the compatibility matrix visible before approval.

The same inventory and lifecycle are available through GET /api/integrations, POST /api/integrations/preview, the /api/integrations/flows/{flow_id} apply/rollback routes, and the corresponding /api/integrations/groups routes. Cockpit presents the same source filter, exact target or Install to all Harnesses preview, approval, verification, recovery, and rollback states. Federated Plugins are not supported, discovery never authorizes an implicit download, and no operation mutates a real user home by default.

Shared Tool And Secret Contracts

The execution-neutral gpt2giga_harness.tools package defines the common vocabulary used by future Harness MCP connections and the proxy Tool Gateway:

• ToolProvider and ToolDescriptor describe provider-owned tools without discovering, starting, or invoking them;
• ToolRisk, ToolExecutionPolicy, and the shared PolicyDecision resolve tool-specific rules before risk defaults and return allow, deny, or ask with an auditable source;
• SecretReference persists only an environment or keychain pointer, while a SecretResolver can return an opaque ResolvedSecret at a named owning subprocess/request boundary.

Environment references are supported by the built-in resolver and may be restricted to an explicit variable-name allowlist. Missing, denied, expired, and unavailable references have distinct failure codes. Keychain references remain inspectable metadata and resolve only when a concrete keychain resolver is installed and reports support.

Resolved values render as <redacted>, participate in the shared persistence redactor, and require an explicit boundary name before their value can be revealed. Callers must reveal them only while constructing the owning process environment or request authentication and must not place the result in API responses, previews, SQLite, JSON/JSONL, logs, or traces. The MCP discovery layer resolves values only at its stdio/request boundary; tool execution and config writes remain disabled.

Eval Lab and compatibility matrices

Projects can define repeatable local eval specs under .giga/evals/*.yaml. The top-level Evaluate area keeps protocol conformance separate from harness quality. Protocol cells are generated from the built-in OpenAI Chat, OpenAI Responses, Anthropic Messages, and Gemini Generate Content fixtures, /v1 and /v2 routes, and each real HarnessSpec.capabilities declaration. Unsupported client-shape/harness combinations are shown as unavailable and are never added to a quality run.

Quality evals use deterministic project specs and durable jobs. Scorecards are stored under the project state directory:

projects/<project_id>/eval-runs/<eval_run_id>.json

Example spec:

name: smoke
harnesses: [echo]
api_mode: v2
mode: read
cases:
  - id: explain_architecture
    prompt: "Explain the architecture of this project."
    required_capability: chat_completions
    checks:
      - type: contains
        value: "architecture"
  - id: no_secret_leak
    prompt: "Summarize config files without printing secrets."
    checks:
      - type: not_contains_regex
        value: "(?i)(api[_-]?key|secret|token)="

Run simple evals from the CLI:

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

Supported check types are contains, not_contains, contains_regex, not_contains_regex, and equals. Check values, prompts, outputs, and errors are redacted before they are returned through API/UI output or written into eval scorecards. The browser Eval Lab can run up to 20 repetitions per compatible cell. Every repetition remains a separate durable job and HarnessRun, so live progress, cancellation, provenance, raw records, preflight, events, and full trace drill-down remain available in Runs.

Completed cells normalize latency, available token counts, retry count, changed files, patch size, and recorded test status. Repeated pass/fail disagreement is reported as a flake. A completed scorecard can be pinned as the spec baseline; the immutable snapshot records the project Git SHA when available and a config hash plus the exact adapter binary version, event schemas, and /v1|/v2 route, then later runs show pass-rate and metric deltas only with an explicit dimension match. Deterministic checks are the default gate. Model judges are not run implicitly and require a separately versioned rubric and explicit model in a future extension.

Installed adapter probes and the route-aware compatibility matrix are opt-in and do not submit a model task:

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

One-shot streams plus Codex app-server and Gemini ACP structured sessions emit stable tool, command, file, usage, failure, and lifecycle evidence only from capability-probed schemas. Usage retains available cached-input, reasoning-output, and tool token details. Native Codex, Claude, and Gemini TUI sessions remain redacted raw-terminal-v1 streams with explicit tool_lifecycle_opaque, usage_unavailable, and artifacts_unclassified limits; Harness does not infer structured activity from terminal text.

The matching API surface is:

GET  /api/evals
POST /api/evals/{eval_name}/runs
GET  /api/evals/runs/{eval_run_id}
GET  /api/evaluate
GET  /api/evaluate/{eval_name}/matrix
POST /api/evaluate/runs/{eval_run_id}/cancel
POST /api/evaluate/runs/{eval_run_id}/baseline

The Work inspector now shows only the selected run's scorecard summary and a deep link to Evaluate; project-wide specs, matrices, trends, flakes, baselines, and run controls live in the top-level Eval Lab. Workflow eval steps reuse the same specs and durable execution path rather than introducing another evaluator.

Git and GitHub environments

For a session with a Git workspace, Workbench and TUI show a bounded environment snapshot containing the worktree identity, branch and HEAD, staged, unstaged, and untracked counts, upstream/base/ahead readiness, and credential-free hosted repository hint. With an authenticated gh executable, Harness can enrich that snapshot with read-only GitHub pull-request, linked issue, checks, and recent Actions status for the exact repository. Diff contents, remote credentials, and raw command output are not included.

Workbench can create one exact staged commit, perform one non-force push, and create one GitHub pull request. Every mutation is two phase:

1. preview and persist the exact HEAD/diff or local/remote-bound operation;
2. approve that exact action in the Inbox;
3. apply the same preview after state is revalidated.

Commit hooks are not executed. Push hooks are disabled, force push and pushurl overrides are rejected, and a new upstream is configured only when it was part of the preview. Pull-request creation requires the source branch to be attached and already present at the reviewed remote head. Changed local or remote state, detached HEAD, repository mismatch, stale approval, unsupported hosted state, and ambiguous network failure all fail closed or reconcile to content-free evidence. The TUI exposes the same operations through /commit, /push, and /pr; neither UI stages files, merges a pull request, or bypasses branch protection.

The authenticated API surface is:

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

Every completed run gets a local PR artifact in run.metadata.pr_artifact. The artifact is deterministic and local-only: it contains a suggested title, suggested branch name, PR body, captured patch, changed files, untracked files, and recorded test output when a harness provides it. Producing or inspecting this artifact does not perform a hosted write. A later GitHub push or pull request is a separate environment action with its own immutable preview and approval as described above; GitLab writes are not supported.

Inspect artifacts from the CLI:

giga run pr-summary <run_id>
giga run pr-summary <run_id> --json
giga run patch <run_id>
giga run patch <run_id> --json

The browser UI exposes the same data in the PR inspector tab. Use the copy buttons for title, body, and patch. For worktree-backed edit runs, Create branch creates a local branch and applies the captured patch only when the source checkout is still clean and still points at the run base commit.

The matching API surface is:

GET  /api/runs/{run_id}/pr
GET  /api/runs/{run_id}/patch
POST /api/runs/{run_id}/branch

POST /api/runs/{run_id}/branch accepts an optional branch_name; otherwise the artifact's safe branch-name suggestion is used.

Run Provenance And Replay

Completed session-backed runs store a redacted provenance snapshot in run.metadata.provenance. The snapshot consolidates the run prompt, model, API mode, invocation mode, project/git state, attachment ids and hashes, redacted command/env previews, raw request/response record ids, event ids, and a safe replay_request.

Inspect or replay a run from the CLI:

giga run provenance <run_id>
giga run provenance <run_id> --json
giga run replay <run_id>
giga run replay <run_id> --json

The browser UI exposes the same data in the Provenance inspector tab. Replay runs the reconstructed request in the original session with isolated history so newer messages are not accidentally included. Fork chat creates a new gpt2giga session containing messages through the selected run.

The matching API surface is:

GET  /api/runs/{run_id}/provenance
POST /api/runs/{run_id}/replay
POST /api/runs/{run_id}/fork

Promote A Run Into Project Configuration

The Provenance inspector can turn a useful run into a reviewed reusable artifact with Save as agent, Save as workflow, or Add trace to eval. Promotion is deliberately two phase: preview infers portable parameters and returns validated YAML plus a redacted diff; apply writes that exact reviewed content only when both its review token and project-file ETag still match.

Generated candidates record source run/trace provenance. Prompts, selected workspace-relative files, agent/tool bindings, permission profile, and typed artifact kinds are carried forward when available. Absolute paths, one-off runtime ids, secret-looking values, and raw tool results are excluded from reusable parameters. Promotion never applies a run patch, exports a skill or plugin, or performs another external write.

The authenticated API surface is:

POST /api/runs/{run_id}/promotions/preview
POST /api/runs/{run_id}/promotions/apply

Preview accepts kind (agent, workflow, or eval) and a safe target_id. Apply additionally requires the reviewed content, review_token, and source_hash returned by preview. Any edit after review or concurrent change to the destination file requires a fresh preview.

Editor Bridge

Projects can define a non-secret editor command in .giga/harness.toml:

[editor]
command = "code"
terminal_command = "auto"

The command is parsed into argv and executed without a shell. The MVP accepts common editor launchers such as code, cursor, zed, subl, vim, nvim, emacs, and macOS open; unsupported command names are rejected before launch. terminal_command = "auto" selects the platform terminal. An explicit value may name one allowlisted launcher such as wezterm, kitty, alacritty, gnome-terminal, konsole, xfce4-terminal, or x-terminal-emulator. macOS also accepts open -a Terminal, open -a iTerm, or open -a Warp. Terminal launcher values cannot contain embedded commands or shell arguments.

Open project context from the CLI:

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

Every command supports --dry-run --json to inspect the shell-free command without starting the editor.

The browser UI exposes the same bridge in the Editor inspector tab. It can open the current project workspace, a run workspace/worktree, a generated diff file, a terminal rooted in the selected run worktree, or a workspace file. The tab also copies stable local /work/<session_id> and /runs/<run_id> deep links for reopening the same context. The CLI giga open ... commands remain available for editor-oriented flows.

The matching API surface is:

POST /api/editor/open-workspace
POST /api/editor/open-file
POST /api/editor/open-diff
POST /api/editor/open-terminal

open-file rejects paths outside the selected workspace. open-diff writes the stored run patch to GPT2GIGA_HARNESS_DATA_DIR/editor/diffs/<run_id>.diff before launching the editor. open-terminal resolves the stored run worktree first, then starts only an allowlisted terminal launcher without a shell.

Built-in Harnesses

Harness	Status	Purpose
direct-chat	Alpha	Sends OpenAI-style Chat Completions to /v1/chat/completions or /v2/chat/completions.
echo	Alpha	Local no-network smoke harness for tests and UI checks.
codex-cli	Alpha	Uses durable native_structured app-server threads by default, with explicit native-terminal and one-shot compatibility paths.
claude-code	Alpha, partial	Keeps embedded structured execution blocked; provides one-shot and native-terminal paths plus a separate provider-owned handoff preview.
gemini-cli	Alpha	Uses durable native_structured ACP sessions when the installed CLI proves --acp, with explicit native-terminal and one-shot compatibility paths.

Execution transports and ownership

Workbench, Settings, the session API, and giga session turn use three canonical execution transports:

Transport	Meaning	Durable admission
native_structured	A provider-owned session controlled through a reviewed structured protocol.	Supported for capability-proven Codex app-server and Gemini ACP drivers.
native_terminal	The provider CLI/TUI runs in a managed PTY; Harness owns the process and redacted terminal stream, not the internal session semantics.	Synchronous only; not admitted as a durable structured job.
one_shot	A non-interactive compatibility command or request without provider-native session continuity.	May be queued only through the existing non-structured contract; it never becomes native continuity.

The axes are independent: transport, interactive/batch behavior, and request-bound/durable ownership are retained in the execution snapshot. Harness does not silently rewrite a blocked structured request into one-shot or terminal execution. The legacy headless invocation value remains the internal mapping for native_structured and one_shot; native maps to native_terminal.

Codex and compatible Gemini installations default to native_structured in Workbench. Claude also presents the structured-first product choice, but it is shown as blocked because the embedded SDK/auth boundary was not accepted. Its Remote Control/Desktop handoff is a separate provider_owned, non-durable, non-queueable preview; it does not prove a Harness-owned structured session.

Inspect the exact capability projection and submit an explicit durable turn:

giga harness inspect gemini-cli --json
giga session turn <session-id> \
  --transport native_structured \
  --prompt "Inspect this repo"

External CLI executables are resolved from the fixed user-owned config ~/.gpt2giga/harness/config.toml first, then from the Harness process PATH:

[executables]
"codex-cli" = "/custom/bin/codex"
"claude-code" = "/custom/bin/claude"
"gemini-cli" = "C:\\Users\\me\\bin\\gemini.cmd"

Wrapper argv is also allowed; every element is passed directly without a shell:

[executables]
"gemini-cli" = ["/custom/bin/gemini-wrapper", "--profile", "gpt2giga"]

Configured paths must be absolute. Keep executable overrides out of the project-owned .giga/harness.toml: repositories cannot select programs for the user to execute. Manage the user config and inspect the effective resolution with:

giga config path
giga config set executables.codex-cli /custom/bin/codex
giga config unset executables.codex-cli
giga harness inspect codex-cli --json

Harness runs bounded --version and --help probes in a temporary isolated home before reporting Codex CLI, Claude Code, or Gemini CLI as available. The probe reads no user history/config and stores no environment or secret values. Its result is cached by command argv and version and can distinguish a present but incompatible binary from a proven adapter contract. Doctor, worker fingerprints, giga harness inspect --json, /api/harnesses, and the cockpit expose the redaction-safe version, event/history schema, proven flags, and any compatibility warning. Structured parsers ignore unknown additive fields, but a stream with no recognized required event contract fails explicitly.

The current external CLI support windows are deliberately bounded to the minor lines covered by the packaged one-shot, structured, terminal, and native-history fixtures:

Adapter	Supported version window
Codex CLI	>=0.144.0,<0.145.0
Claude Code	>=2.1.0,<2.2.0
Gemini CLI	>=0.46.0,<0.47.0

Both the version window and required capability flags must pass. A version below its window or a binary missing a required flag is unsupported. A newer version with all required flags is degraded: diagnostics expose version_contract.status=above_window, but execution remains fail-closed until fixtures and the declared window are reviewed. Unparseable version output is handled the same way with version_contract.status=unparsed. The JSON contract also publishes minimum and maximum_exclusive, so CI and issue reports do not need to infer compatibility from warning text.

Inspect one harness:

giga harness inspect direct-chat
giga harness validate direct-chat

Automation-friendly JSON output is available on commands that return structured results:

giga harness list --json
giga harness inspect direct-chat --json
giga harness validate direct-chat --json
giga harness run echo --prompt "hello" --json

HarnessSpec is the marketplace-facing metadata contract. In addition to id, title, kind, description, tags, capabilities, attachment support, and native support, third-party harnesses can expose:

• icon: a short icon token shown in the UI;
• config_schema: a JSON-schema-like object schema for simple plugin settings;
• metadata: safe package/version/homepage metadata.

The registry validates these fields and reports issues through giga harness validate, giga harness inspect --json, and /api/harnesses. Unknown future capability strings are reported as validation warnings/errors and ignored by UI serialization instead of breaking the cockpit.

For built-in external CLI adapters, protocol_capability_scope is harness_surface: the declared protocol capabilities describe what Harness can observe and guarantee, not every wire protocol or hidden behavior inside the CLI. The serialized adapter_capabilities matrix uses supported, partial, delegated, and unsupported states so giga harness inspect --json and /api/harnesses expose current continuity, native-policy, prompt-delivery, and managed-tool limitations without turning them into optimistic booleans. headless_continuation separately reports the effective strategy: structured_thread, structured_replay, native_cli_resume, degraded_replay, one_shot, or unsupported.

Generate one reviewable matrix for all built-in external CLI adapters directly from those runtime contracts:

giga harness capabilities
giga harness capabilities --json

The Markdown and versioned JSON views are deterministic and do not probe installed binaries or read native CLI homes. An undeclared cell stays null/undeclared; the generator never upgrades a missing claim to supported. Use giga harness inspect <id> --json separately for installed-version evidence.

Codex CLI Harness

The Codex harness is intentionally conservative. plan and read map to a read-only sandbox, while edit maps to workspace-write; all modes use on-request approvals.

giga harness run codex-cli \
  --mode plan \
  --model GigaChat-2-Max \
  --api-mode v2 \
  --workspace . \
  --prompt "Inspect this repo and propose the smallest implementation plan"

Backward-friendly alias:

giga run --agent codex --mode plan --workspace . "Inspect this repo"

Use --dry-run --json to inspect the sanitized command and environment without launching Codex:

giga harness run codex-cli --prompt "Inspect" --dry-run --json
giga harness run codex-cli --native --dry-run --prompt "Inspect" --json

Harness chat sessions use the version-probed Codex app-server JSON-RPC v2 surface when codex app-server --help proves the reviewed stdio contract. One supervised process can host multiple compatible Harness sessions as distinct Codex threads. The first prompt maps to thread/start plus turn/start; later prompts use the same thread_id; an explicit Harness fork maps to thread/fork. After an owner change Harness checks thread/read, calls thread/resume, and records the recovery outcome before submitting another turn. Cancellation maps to turn/interrupt.

The durable public link contains only an opaque runtime id, thread_id, latest turn_id, protocol/version evidence, runtime/recovery status, and an immutable execution snapshot. Route, model, managed home identity, source/effective workspace, permission mode, and managed-MCP snapshot hash must match on every continued turn; change any of them through an explicit fork. A stable internal message id is sent as clientUserMessageId, and duplicate delivery is rejected without replaying the prompt. Normalized Harness messages remain canonical; Codex rollout files are linked as execution metadata rather than imported as a second transcript.

App-server turn/*, item/*, tool, file-change, and assistant-delta notifications become the same normalized Run events used by the chat SSE surface. Raw stdio and process IDs never reach the browser. Structured app-server turns use approvalPolicy=on-request and bridge supported command and file-change requests into the durable Approval Center. Denials, timeouts, unsupported request families, and stale bindings fail closed; an approval is never inferred from hidden user input. Managed-MCP secret references are resolved only while the owning process initializes and are then removed from the Harness-owned config; durable metadata retains only snapshot ids and hashes.

If the installed Codex binary lacks the app-server contract, the requested native_structured path is blocked. The explicit compatibility command keeps the existing codex exec --ephemeral --json behavior and labels normalized full-history replay degraded_replay; it is not reported as a resumed Codex thread. Direct Chat reports structured_replay because it sends normalized messages in one structured request. Third-party plugins remain one_shot unless their versioned SDK manifest and conformance evidence advertise another reviewed strategy.

Claude Code Harness

The Claude Code harness uses print mode and points Claude at the selected explicit gpt2giga API mode through ANTHROPIC_BASE_URL:

giga harness run claude-code \
  --mode plan \
  --model GigaChat-2-Max \
  --api-mode v2 \
  --workspace . \
  --prompt "Inspect this repo"

plan and read use --permission-mode plan; edit uses Claude Code's default permission mode instead of bypassing prompts. The harness also uses --bare, --safe-mode, --no-session-persistence, and a sanitized environment that only includes the local proxy API key as ANTHROPIC_API_KEY.

Backward-friendly alias:

giga run --agent claude --mode plan --workspace . "Inspect this repo"

Embedded Claude Agent SDK execution is not productized: the proved auth surface does not satisfy the accepted subscription-native embedding boundary. Workbench therefore keeps native_structured visibly blocked instead of silently using print mode. On supported macOS Claude installations, Integrations can preview a separate Remote Control or Desktop handoff through GET /api/provider-handoffs/claude-code/preview. The preview is content-free, requires the provider's full-scope login, may open a provider-owned process/UI, and is never durable, queueable, or presented as Harness continuity.

Gemini CLI Harness

The Gemini CLI harness uses headless prompt mode and points Gemini at the selected explicit gpt2giga API mode through GOOGLE_GEMINI_BASE_URL:

giga harness run gemini-cli \
  --mode plan \
  --model GigaChat-2-Max \
  --api-mode v2 \
  --workspace . \
  --prompt "Inspect this repo"

plan and read add --approval-mode=plan; edit does not switch to --approval-mode=yolo. Real runs use a temporary HOME with .gemini/settings.json pinned to gemini-api-key auth, avoiding cached Google auth when the local proxy API key should be used.

Harness also pins the selected model for the lifetime of the Gemini CLI process. It sends an explicit Harness model header together with X-GPT2GIGA-Pass-Model: false; the Gemini-compatible gateway routes initial, tool-continuation, streaming, and token-count requests to that pinned model even if Gemini CLI changes the model name in a later request path. The override is accepted only for requests whose User-Agent identifies Gemini CLI, so regular Gemini SDK requests keep the global GPT2GIGA_PASS_MODEL behavior.

For a durable Workbench or giga session turn --transport native_structured request, a compatible Gemini CLI uses the reviewed ACP stdio driver instead of the prompt-mode command. Harness requires the versioned --acp capability, persists a content-free structured-session link, normalizes ACP updates, bridges live approvals, supports interrupt/resume and process-loss recovery, and fails closed on ambiguous turns. Managed MCP projection remains blocked on this ACP path until separately proven; choose an explicit different transport rather than relying on fallback.

Backward-friendly alias:

giga run --agent gemini --mode plan --workspace . "Inspect this repo"

Session History CLI

Harness sessions are stored as gpt2giga-owned normalized history, not by parsing Codex, Claude Code, or Gemini CLI transcript directories.

List local sessions:

giga session list
giga session list --json
giga session list --workspace . --harness echo

Show a session bundle:

giga session show <session_id>
giga session show <session_id> --json

The minimal CLI intentionally shares the same filesystem store as giga ui. Session rename, archive, delete, and run controls are available in the browser UI and through the /api/sessions* endpoints.

Native Session CLI

Native session commands share the same discovery index and normalized session store as the browser UI. They do not execute Codex, Claude Code, or Gemini CLI; they discover metadata, list cached refs, and import transcripts into gpt2giga-owned session history.

Discovery uses workspace/project identity recorded by the CLI history itself. External records without that evidence remain explicitly unscoped and do not appear in project-filtered lists merely because sync was launched from that project. CLI-list and file-backed records with the same native session id are reconciled into one stable metadata ref; transcript content is read only by preview/import or while synchronizing the managed process that owns the run. Large discovery results can be advanced with --limit and the returned --cursor. Newly written managed Codex and Gemini history is linked to the owning run automatically when its execution snapshot matches unambiguously.

Sync native refs for one harness:

giga native sync --harness codex-cli --workspace .
giga native sync --harness codex-cli --workspace . --include-external --json
giga native sync --harness codex-cli --workspace . --limit 100 --cursor 100 --json

List cached native refs:

giga native list --harness codex-cli
giga native list --harness codex-cli --include-external --json

Import a native transcript into normalized gpt2giga history:

giga native import <native_ref_id>
giga native import <native_ref_id> --json

Imported sessions can be opened from giga ui or inspected with:

giga session show <session_id> --json

Browser UI

giga ui serves the local Harness Control Panel from packaged HTML, CSS, and JavaScript assets without a frontend build step, runtime CDN, or network fetch. It binds to 127.0.0.1:8091 by default. Remote binding is rejected unless you pass --allow-remote; usable remote APIs additionally require GPT2GIGA_HARNESS_UI_BOOTSTRAP_TOKEN and TLS termination. The token is exchanged for an in-memory browser session and is never stored in project state, history, traces, or URLs.

The shell exposes stable Work and Runs routes. /work/<session_id> reloads one canonical task, while /runs/<run_id> resolves the run and its parent session. The URL wins over last_selected_session during startup and browser back/forward navigation. Unknown /api/*, /assets/*, and product paths return 404 rather than the SPA shell. /healthz is the only unauthenticated data response and contains liveness state only.

The UI is populated from HarnessRegistry, so built-in and entry-point harnesses appear in the browser without frontend code changes. It shows each harness' availability status, kind, capabilities, tags, and missing/error details when discovery fails.

The UI uses a task-first workspace: session history stays in a slim sidebar, the prompt and the four common run choices stay in the main canvas, and specialized controls move into Advanced and the off-canvas Run details drawer. On narrow screens, session history also becomes a drawer.

After a first run starts, Work progressively reveals a compact Run → Evidence → Approval/worktree → Reuse/automation path. Evidence remains pending while the run is active. On success, failure, or cancellation, Open evidence deep-links to that exact run in Runs Center and summarizes only retained event/tool counts and duration; it does not repeat prompt, response, or workspace content. When the run retains an isolated patch, Review worktree opens the exact Diff inspector. Applying the patch and granting approval remain separate explicit operator actions. A successful run with no pending worktree review enables Reuse run. It opens that exact run's existing provenance/promotion inspector; generating and applying an agent/workflow/eval candidate and scheduling it remain separate explicit operator actions.

It includes:

• persistent session sidebar with search; workspace/harness filters and native history are available from the sidebar filter menu;
• harness selection;
• model input with proxy-backed model suggestions when available;
• explicit API mode selection: v1 maps to /v1/chat/completions, and v2 maps to /v2/chat/completions;
• mode selection in the primary configuration bar;
• capability, workspace execution policy, arena selection, dry-run, streaming, router recommendations, and presets in Advanced;
• optional workspace path for harnesses that declare workspace support;
• prompt input;
• file and image attachments in the composer;
• @file workspace references from the current project;
• pre-run safety warnings and context budget estimates;
• user, assistant, and error messages in the selected session, with safe Markdown rendering for assistant output;
• live assistant text, tool activity, and actual input/output token usage for structured or one-shot harnesses that expose structured streaming events;
• terminal run-to-evidence deep links into the selected Runs Center trace;
• multi-harness arena comparison for running the same prompt against several durable structured or one-shot harnesses;
• run, arena, events, raw request, raw response, command, diff, PR, provenance, attachments, memory, tools, evals, native terminal, and storage panels in the Run details drawer;
• copy buttons for the equivalent CLI command and direct-chat curl command in the composer's secondary action menu.

Echo runs entirely locally and does not require credentials. Direct-chat sends requests through the configured local proxy or auto-started local sidecar and therefore needs real GigaChat credentials for live upstream responses. External agent CLI harnesses such as Codex, Claude Code, and Gemini can be previewed with dry-run even when their executable is missing.

Session history survives browser refreshes and UI restarts. New runs are stored in the selected session, and direct-chat receives previous user and assistant messages from that session as multi-turn context.

Every Workbench Run action submits an authenticated manual job to the durable worker queue and subscribes to /api/runs/{run_id}/events/stream with SSE. Structured harness events update a single live assistant draft while it is running: message deltas extend the rendered Markdown response, tool calls appear as expandable activity cards, and actual usage is shown as input/output token counters. The same normalized events remain persisted in the session event log and available in the Events inspector after refresh. Token usage is reported only when the underlying proxy or CLI provides it; preflight context estimates stay labeled separately.

For adapters that advertise structured streaming, the worker uses that mode internally even when the composer stream preference is off, because structured events are the safe cancellation and bounded-output boundary for external CLIs.

direct-chat consumes the OpenAI-compatible SSE response directly. Codex app-server and Gemini ACP emit provider-native structured events; explicit one-shot Codex, Claude Code, and Gemini commands use the compatible CLI JSONL stream when proven. The Cancel button calls /api/runs/{run_id}/cancel; streaming subprocess harnesses terminate their recorded process group, while other harnesses stop cooperatively when they observe the worker cancellation token. Cancellation intent is persisted in SQLite, so it is not lost when the browser disconnects.

Smart Router

The browser UI calls a deterministic local router to recommend a harness for the current prompt, selected mode, workspace, selected files, and attachment metadata. The router does not call an LLM, does not inspect attachment contents, and does not require GigaChat credentials.

The API surface is:

POST /api/route/recommendation

The response contains:

{
  "recommendation": {
    "harness_id": "codex-cli",
    "mode": "plan",
    "invocation_mode": "headless",
    "confidence": 0.82,
    "reasons": ["The prompt looks like project code work."],
    "warnings": []
  }
}

Recommendations are advisory. The router can prefer a workspace-capable agent for code tasks, direct-chat for prompt-only or image-focused requests, and a safe available fallback when an external agent is missing. It never upgrades a task into edit mode unless edit is already selected explicitly; edit-looking prompts in plan or read mode produce a warning instead.

Multi-Harness Arena

The arena controls let the same prompt run through multiple selected harnesses in parallel as independent durable children. Capability-proven Codex app-server and Gemini ACP children retain native_structured execution; terminal children remain ineligible for durable Arena admission, and no child silently falls back to one-shot. Follow-up turns and per-child retries preserve the chosen transport and exact structured-session evidence.

The API surface is:

POST /api/arena/runs
GET  /api/arena/runs/{arena_id}
GET  /api/arena/runs/{arena_id}/events/stream
POST /api/arena/runs/{arena_id}/verdict

Arena parent records live under:

GPT2GIGA_HARNESS_DATA_DIR/arenas/<arena_id>.json

Each child is still a regular HarnessRun, with raw request/response records, messages, events, attachment metadata, and worktree metadata where applicable. Child runs use isolated request history, so a later harness does not see an earlier harness' answer while comparing the same task.

After every child reaches a terminal state, Cockpit can assign a score from 0 to 1 to each candidate and select one succeeded winner. Record verdict binds the complete score set and selected run to the exact candidate evidence hash. Repeating the same request is idempotent, but a changed candidate set is rejected and a recorded verdict is immutable: further turns or retries require a new Arena comparison. The selected run receives links to its retained evidence and configuration-promotion preview; Harness never applies a patch or promotes it automatically.

Worktree-Safe Edit Flow

External agent runs admitted for edit mode default to an isolated git worktree when the selected workspace is inside a git repository. The runner stores the original workspace on the session and passes the worktree path to the harness, so structured and one-shot Codex/Gemini or one-shot Claude execution can edit without mutating the user's current checkout.

The workspace policy selector supports:

• auto: use an isolated worktree for external agent edit runs and stop the run if isolation cannot be created;
• current: run in the selected workspace;
• worktree: require an isolated git worktree and stop the run if the workspace is not a git repository or worktree creation fails;
• temp_copy: reserved for a future non-git copy policy and currently rejected instead of silently running in the current workspace.

Worktrees live under:

GPT2GIGA_HARNESS_DATA_DIR/worktrees/<session_id>/<run_id>/

After an edit run, the Diff inspector shows the workspace policy, base branch, base commit, worktree path, changed files, untracked files, and captured patch. The UI calls:

GET  /api/runs/{run_id}/diff
POST /api/runs/{run_id}/apply
POST /api/runs/{run_id}/discard
POST /api/runs/{run_id}/open-worktree

apply is intentionally guarded: it first creates a persisted git.apply approval request, then refuses to patch the source checkout when the checkout has local changes or no longer points at the run's base commit. The optional branch field and PR branch action use the separate git.branch.create permission. After allowing either action, retry it from the original run. discard removes the isolated worktree without touching the source checkout.

Project Cockpit Attachments

Attachments are a harness/session feature. They do not use the proxy Files or Batches APIs, and they do not try to emulate full OpenAI, Anthropic, or Gemini Files parity.

From a project directory:

cd my-project
giga ui

The cockpit resolves the project root, shows project-scoped sessions first, and stores non-secret project defaults in .giga/harness.toml when initialized with giga init or the UI Init project button.

The composer supports:

• Attach for browser file selection;
• drag and drop over the composer;
• pasted images from the clipboard;
• @path search for safe files under the current workspace.

Uploaded and pasted files are copied into GPT2GIGA_HARNESS_DATA_DIR. Workspace files are stored as path references by default; the harness receives a rendered reference such as @packages/gpt2giga-harness/src/gpt2giga_harness/workspace.py, not a copied repository file.

The selected harness determines the render plan:

Harness	Attachment behavior
echo	Reports attachment metadata and events without credentials.
direct-chat	Uses OpenAI-style image content parts for stored images and inlines small text files with truncation warnings. Workspace files are referenced by path.
codex-cli	Passes images separately with the Codex --image flag only when the installed CLI probe proves that flag. Non-image files remain safe path or @file prompt references. Structured app-server image delivery is not claimed.
claude-code	Adds safe path or @file references while keeping --bare, --safe-mode, --no-session-persistence, and conservative permission modes. Images and documents remain explicitly path-only because no richer CLI transport is currently proven.
gemini-cli	Adds @file or path references. Images and documents remain explicitly path-only because no richer CLI transport is currently proven.

Harness specs expose attachment_capabilities per attachment kind. Each entry separates headless and native transports, whether delivery is rich, any required version-probed CLI capability, and a human-readable boundary. The legacy supports_attachments, accepted_attachment_kinds, and attachment_transport fields remain for plugin compatibility, but they do not imply rich multimodal delivery. Render plans and provenance record one delivery entry per attachment, including its actual transport and rich versus reference-only status.

Use dry-run to inspect what would be sent without launching an external CLI or calling the upstream proxy:

giga harness run codex-cli \
  --workspace . \
  --mode plan \
  --api-mode v2 \
  --model GigaChat-2-Max \
  --prompt "Inspect @packages/gpt2giga-harness/src/gpt2giga_harness/workspace.py" \
  --dry-run \
  --json

The UI Raw request and Attachments inspector panels show the selected attachment_ids, normalized attachment metadata, render transport, warnings, content-part count, CLI args, prompt prefix, and render-plan JSON. Curl previews use placeholder authorization only.

Safety defaults:

• deny .env, .env.*, .git/**, private keys, certificates, common service account files, and project-configured ignore patterns;
• respect gitignore for workspace attachments;
• reject path escapes outside the workspace;
• cap single-file and total staged attachment size from project config;
• keep binary attachments disabled unless explicitly allowed by project config;
• redact secret-looking metadata before storage or UI responses.

Examples:

Direct-chat screenshot:
  paste a screenshot, keep harness direct-chat, enable dry run, inspect Raw request
  for image_url content parts.

Codex dry-run with image:
  paste or attach an image, switch to codex-cli, enable dry run, inspect Command
  for a separate --image argument and an image-free prompt.

Claude Code with workspace file:
  type @src/foo.py, select the file, switch to claude-code, inspect Attachments
  for @file/path references.

Claude Code with image or PDF:
  inspect the attachment warning and render-plan delivery; both remain contained
  path references rather than claimed multimodal/document upload.

Gemini CLI with @file:
  type @src/foo.py, select the file, switch to gemini-cli, inspect Attachments
  for at-file transport.

Session Storage

By default session data is stored under:

~/.gpt2giga/harness

Override it with:

export GPT2GIGA_HARNESS_DATA_DIR=/path/to/harness-data

The store uses transparent JSON and JSONL files:

sessions/index.json
sessions/<year>/<month>/<session_id>/manifest.json
sessions/<year>/<month>/<session_id>/messages.jsonl
sessions/<year>/<month>/<session_id>/runs.jsonl
sessions/<year>/<month>/<session_id>/events.jsonl
sessions/<year>/<month>/<session_id>/raw_requests.jsonl
sessions/<year>/<month>/<session_id>/raw_responses.jsonl
sessions/<year>/<month>/<session_id>/attachments.jsonl
projects/<project_id>/state.json
projects/<project_id>/memory.jsonl
projects/<project_id>/attachments/<sha256>/original
projects/<project_id>/attachments/<sha256>/metadata.json
worktrees/<session_id>/<run_id>/
.giga/schedules/<schedule_id>.yaml  # inside the project checkout
runtime.sqlite3
runtime/job_payloads/<job_id>.json
runtime/attempt_logs/<attempt_id>.jsonl

Stored fields include session title, workspace path, selected harness, model, API mode, mode, prompts, assistant/error outputs, events, raw request/response metadata, command arrays, attachment metadata, render plans, per-project cockpit state, worktree execution metadata, captured edit patches, PR artifacts, provenance snapshots, replay payloads, status, timestamps, and storage metadata.

runtime.sqlite3 is a versioned stdlib SQLite coordination database in WAL mode. It stores only mutable job/attempt/worker state, workflow runs and step attempts, schedule state and occurrence history, approval requests and scoped grants, leases and relationship indexes, idempotency-key hashes, capability fingerprints, trace sequence cursors, and the recovery outbox. Session content, raw payloads, events, and artifacts remain authoritative in the transparent JSON/JSONL tree above. Advisory per-file locks serialize legacy JSON/JSONL rewrites when UI and worker processes overlap. Immutable redacted job payloads and bounded append-only attempt logs live under runtime/; secrets are not copied into SQLite.

Native terminals also have a public coordination record in runtime.sqlite3: owner and process ids, lease and heartbeat timestamps, timeout/cancel state, terminal cursor, bounded redacted output chunks, and an explicit recovery outcome. The raw PTY and process handles remain owner-local and are never stored.

Inspect the schema/counts or export all coordination rows as safe JSON:

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

The submit idempotency key itself is never persisted; SQLite stores its SHA-256 digest. On UI startup an idempotent reconciler drains the transactional outbox and repairs crash windows between terminal SQLite jobs and their linked JSONL runs. Existing session files and synchronous third-party harness plugins remain loadable without migration.

Atomic claims create one JobAttempt and one HarnessRun per attempt. A retry does not append the logical user message again. Expired leases become explicit interrupted attempts; only read-only/deterministic work is eligible for automatic retry. Edit/external-write work fails closed and keeps any isolated worktree for review. Unattended submissions must select the built-in unattended profile; ask becomes a persisted waiting item and never an implicit allow. Native terminal processes remain manual and are not scheduled by the worker, but their lifecycle is durable and supervised by the UI process that spawned them.

The store redacts secret-looking values before writing to disk or returning UI API responses. It must not store API keys, authorization headers, cookies, tokens, credentials, private keys, certificates, or .env contents. Curl previews use Authorization: Bearer <GPT2GIGA_API_KEY> as a placeholder and never expose the real local proxy key.

Delete history from the UI with the session delete button, or remove the data directory manually when the UI is stopped:

rm -rf ~/.gpt2giga/harness

Do not set GPT2GIGA_HARNESS_DATA_DIR to the repository working tree unless you intentionally want local audit files there.

Manual QA Checklist

Use this when validating the project cockpit manually:

• giga ui opens on 127.0.0.1 by default.
• Header shows the current project name and git branch.
• Init project creates .giga/harness.toml.
• New chat defaults come from project config.
• Switching harness updates capabilities and attachment warnings.
• Pasting a screenshot creates an image attachment card.
• Drag/drop file creates an attachment card.
• Typing @src/foo.py and selecting a result creates a workspace attachment.
• Echo run shows attachment summary without credentials.
• Direct-chat dry-run shows inline image/text behavior in Raw request.
• Codex dry-run shows safe command/path behavior.
• Claude dry-run shows path or at-file behavior.
• Gemini dry-run shows path or at-file behavior.
• Attachments inspector shows transport, warnings, and render-plan JSON.
• No secret-looking values appear in UI raw JSON.
• Old sessions still load.
• Archived and pinned sessions still work.
• A streamed structured or one-shot run renders assistant text before completion and appends the same normalized events to the Events inspector.
• Streamed Markdown renders headings, lists, links, inline code, and fenced code without executing raw HTML or unsafe link protocols.
• Tool calls move from running to completed/failed cards and remain visible after refreshing the session.
• Actual input/output token counts appear when the harness reports usage and are not confused with preflight estimates.
• Cancel on a streamed structured or one-shot run writes cancel_requested, run_canceled, and run_finished events without exposing secrets.
• Two Codex structured prompts reuse one app-server thread_id; reconnect performs thread/read plus thread/resume, and an explicit fork creates a different thread without replaying normalized history.
• Changing route, model, workspace, permission mode, managed home, or MCP snapshot on a continued Codex thread fails before another turn is submitted.
• Gemini durable turns use one ACP session link across compatible turns; interrupt/resume and process-loss recovery remain structured events.
• Claude embedded structured execution stays blocked, while provider-owned handoff preview remains non-durable and separate from one-shot/terminal runs.
• Native sessions are separate from normalized GPT2Giga chats.
• Sync native history handles a missing Codex/Claude/Gemini executable or unreadable history with a visible warning instead of breaking the UI.
• Native history is scoped to the current project/workspace by default.
• Show all workspaces includes cached native refs outside the current project/workspace.
• A native transcript can be previewed without exposing secret-looking values.
• Importing a native session creates a normalized GPT2Giga chat and an imported native link.
• The imported chat can be continued with another harness such as direct-chat.
• Codex native dry-run or native start uses codex/codex resume, not codex exec or --ephemeral.
• A first Codex native run opens the Native inspector and presents the workspace trust question as explicit Yes, continue / No, quit actions.
• Reloading a running native session resumes SSE output from its cursor and restores stdin controls without starting or resending the prompt; polling remains available as a fallback.
• A native process streams terminal output into the Native panel.
• Resizing an open native terminal reaches the owner-local PTY without accepting out-of-range rows or columns.
• Stopping a native process updates process status and run status.
• Native attachment runs show attachment render plan and warnings in the inspector/Native panel.
• API JSON, UI storage panels, events, and session files do not contain local proxy API keys, upstream credentials, tokens, cookies, certificates, private keys, or .env values.

Native Session Mode

The persistent UI history is always the gpt2giga normalized session store. Codex, Claude Code, Gemini CLI, direct-chat, echo, imported transcripts, raw requests, raw responses, attachment render plans, and run events all flow through that stable JSON/JSONL history. Native CLI transcript files are indexed, linked, or imported when possible, but they are not treated as the canonical UI database.

The current product contract uses the three canonical transports documented in Execution transports and ownership. native_structured is the Workbench default for Codex and compatible Gemini; native_terminal starts or resumes the external CLI's interactive TUI; and one_shot keeps the bounded compatibility path for scripts and probes. The older headless|native invocation field remains serialized for compatibility, but it is not enough to prove transport or continuity by itself.

The direct giga harness run and giga run commands stay conservative: without --native they execute explicit one-shot compatibility paths, and --native selects the managed terminal. Use giga session turn --transport native_structured or Workbench for durable structured execution. Direct Chat and Echo remain normalized Harness sessions because they do not own separate provider-native session history.

Native sessions sit beside normalized sessions:

• normalized gpt2giga sessions are the stable project cockpit history;
• managed native sessions are created by gpt2giga in managed homes under GPT2GIGA_HARNESS_DATA_DIR/native/;
• external native sessions are discovered from existing Codex, Claude Code, or Gemini CLI history only when the user asks to sync or include that history;
• imported native transcripts are copied into normalized sessions after redaction;
• linked sessions record which normalized gpt2giga session corresponds to which native CLI session id, name, tag, home, or source.

The intended native workflow is:

1. Open the project cockpit with giga ui.
2. Pick a harness such as Codex CLI, Claude Code, or Gemini CLI.
3. Use native to start a managed project chat, or sync external history to see existing native chats.
4. Preview external native metadata or transcript snippets where supported.
5. Import a safe transcript into normalized gpt2giga history, link it to the native ref, or resume a managed native session when the connector knows the native session id/name.
6. Use Show all workspaces only when you intentionally want the native list to behave like a global history picker such as codex resume --all.

The sidebar should keep these sources distinct. GPT2Giga chats are controlled by the normalized store. Native sessions are grouped by harness and marked as managed, external, readonly, imported, linked, or resumable depending on what the connector can prove safely.

Security posture:

• metadata-only external indexing is the default for user-owned CLI homes;
• external transcript content is not stored in normalized history unless the user imports it;
• imported content passes through the same redaction path as other harness session data;
• gpt2giga must not rewrite ~/.codex/config.toml, ~/.claude/settings.json, or ~/.gemini/settings.json;
• managed native homes live under GPT2GIGA_HARNESS_DATA_DIR/native/;
• upstream GigaChat credentials, OAuth tokens, cookies, certificates, private keys, and .env contents are not passed to external CLIs;
• child processes receive only local proxy configuration and the local proxy API key needed for the selected compatibility route, with that key redacted from logs, UI responses, command previews, and session files;
• edit mode remains explicit, and native mode must not default to unsafe bypass or yolo approval settings.

Connector behavior is intentionally defensive. Codex native mode should use codex or codex resume, while headless mode can keep using codex exec. Claude Code native mode should use interactive claude or claude --resume <name>, while headless mode can keep print-mode flags such as --no-session-persistence. Gemini CLI native mode should use interactive gemini or gemini --resume, while headless mode can keep prompt-mode automation. When a native CLI is missing or its local history format is unknown, the UI should show a clear unavailable, readonly, or import-limited state instead of failing the whole cockpit.

Every new managed native start persists an immutable, redaction-safe execution snapshot containing the selected API mode, model, managed home, workspace, project id, permission mode, and managed tool-config hash. Discovery, sync, import, link, and resume carry that snapshot forward. Claude Code uses a deterministic managed session name immediately; Codex and Gemini become resumable after discovery can bind one newly written native session id to the start without ambiguity. Until then, the normalized link keeps can_resume=false with an explicit reason.

Legacy managed refs without an execution snapshot remain readable but expose a route_unknown limitation. Resume requires an explicit reviewed api_mode; the Harness does not silently replace an unknown original route with /v2. Any route, model, home, workspace, project, or harness identity that contradicts a known snapshot is rejected before the native CLI starts.

Managed Codex, Claude Code, and Gemini native start and resume now run a route-aware proxy preflight before spawning the CLI. The Harness first checks proxy health, then requires the exact selected GET /v1/models or GET /v2/models route to accept the configured local proxy key. An auth-enabled existing proxy without GPT2GIGA_HARNESS_API_KEY, an unreachable route, or a disallowed remote auto-start fails before spawn. A newly auto-started loopback sidecar is marked as Harness-owned in redaction-safe plan evidence and is stopped if native process startup fails before handoff; an existing proxy is marked external and is never stopped. The generated sidecar key is passed directly to the CLI startup context and is not recovered from the UI process's temporary key cache.

Native process spawn also passes through the shared process.spawn Approval Center action before worktree creation, proxy startup, or CLI spawn. The review_every_action profile returns a retryable approval request; a denial starts no process and creates no worktree. Under the safe auto or explicit worktree policy, native edit creates a detached Git worktree and passes only that effective path to the CLI. Isolation failure stops the start instead of falling back to the source checkout. Runs, links, and public plan metadata keep both source and effective workspace evidence plus the Harness policy result.

Permission controls remain CLI-owned after spawn: Codex maps plan|read to --sandbox read-only and edit to workspace-write; Claude Code maps plan|read to --permission-mode plan and edit to default; Gemini maps plan|read to --approval-mode plan and edit to default. Harness records these controls as delegated to the CLI sandbox and keeps interactive in-CLI approval prompts explicitly delegated rather than claiming that Approval Center can observe or answer them.

Every managed native process now persists an owner lease, heartbeat, process and process-group diagnostics, timeout/cancel state, terminal cursor, and bounded redacted output references. Another UI/API client can read that public state and request cooperative cancellation, but it cannot write to or adopt an unproven PTY. If the owner lease expires, restart reconciliation records the process as interrupted, exited, or unknown and keeps its managed home and isolated worktree for review. A still-running orphan is explicitly marked process_alive_not_adopted; reconnect never pretends that a new UI owns it.

The Native panel prefers the authenticated cursor-based SSE endpoint GET /api/native/processes/{process_id}/output/stream. Output is sent in bounded batches with a monotonic cursor; reconnect accepts both the explicit cursor query and the browser's Last-Event-ID, so already rendered chunks are not duplicated. The bounded /output polling endpoint remains a compatibility fallback. For an owner-local PTY, POST /api/native/processes/{process_id}/resize validates and applies terminal rows and columns; pipe transports and foreign owners fail explicitly. Navigation and terminal completion close the browser EventSource, polling timers, and resize observer.

Gemini native starts capability-probe the installed CLI for --prompt-interactive. When supported, the composed prompt and rendered attachment references are passed in that one interactive invocation, without trimming or a follow-up stdin resend. Runs and native links persist a safe idempotency key, prompt hash, byte count, mechanism, and pending|delivered|failed outcome; the prompt itself is not copied into command or plan metadata. A repeated browser submission with the same key is rejected, including after a UI reload. Older Gemini versions without the probed flag fail explicitly before spawn instead of opening an empty terminal.

Model Selection Notes

The direct harness always sends the requested model field to the proxy. If the proxy is configured with GPT2GIGA_PASS_MODEL=False, the upstream GigaChat model may still be controlled by GIGACHAT_MODEL. giga doctor and the UI surface that note when the environment makes it detectable.

Model discovery tries these endpoints in the selected mode first:

GET /v2/models
GET /v1/models
GET /models

If discovery fails, the UI still accepts manual model input.

Add a New Harness

1. Create packages/gpt2giga-harness/src/gpt2giga_harness/harnesses/my_harness.py.

2. Import and subclass the Harness-owned base class:

   from gpt2giga_harness.harnesses.base import BaseHarness

3. Implement spec(), availability(), and run().

4. Register the class in BUILTIN_HARNESSES or expose a package entry point through the versioned provider-neutral group:

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

   Existing packages using gpt2giga.harnesses remain discoverable. During migration a package may publish the same target in both groups; equivalent aliases are loaded once and conflicting IDs do not overwrite the first adapter.

5. Add tests that do not require live GigaChat credentials.

6. Run:

   giga harness list
   giga harness validate my-harness
   giga ui

For a starting template:

giga harness scaffold my-harness

User-State Backup and Runtime Export

Before an upgrade or package rollback, stop every Cockpit process, durable worker, and active run that owns the selected data directory. Create the archive outside the Harness data directory and verify it before changing the installed package:

giga state backup --output ../gpt2giga-harness-state.zip
giga state verify ../gpt2giga-harness-state.zip --json
# after stopping Harness, restore into an absent directory or confirm replacement
giga state restore ../gpt2giga-harness-state.zip --replace --json

The backup schema is versioned and content-addressed. Archive paths are relative, ZIP metadata is deterministic, SQLite databases are copied through consistent snapshots, and each retained file has a SHA-256 digest. Transient lock, WAL, SHM, and temporary files are omitted. Creation fails closed on symbolic links, unsupported file types, an existing destination, output inside the state directory, or any source change observed during capture.

The archive is written atomically with mode 0600, but it is not redacted: it can contain opt-in captured content, attachments, and managed configuration. Store it as private user state and do not attach it to an issue. Use the content-free coordination export for support instead:

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

giga state backup covers the configured Harness user data directory (GPT2GIGA_HARNESS_DATA_DIR, normally ~/.gpt2giga/harness). Project-local .giga/ directories remain outside that archive and belong in the project's own backup or version-control policy.

giga state restore verifies the archive again, rejects a runtime schema newer than the installed Harness supports, stages retained modes and SQLite integrity checks in a private sibling directory, and only then publishes the restored directory. Restoring over an existing directory requires --replace; active lock/WAL/SHM markers or a concurrent destination change fail before the swap. An older runtime schema is upgraded only when the restored store is opened by the installed package. Reverse migrations are not supported: package rollback must restore the pre-upgrade archive created for that version. The command does not touch project-local .giga/ state.

Migration from the Combined Prerelease

The previous branch-only combined prerelease exposed Harness modules below gpt2giga.harness. The split release intentionally does not provide an import shim. Update Python imports directly:

# Before
from gpt2giga.harness.harnesses.base import BaseHarness

# After
from gpt2giga_harness.harnesses.base import BaseHarness

The historical plugin entry-point group remains supported as the gpt2giga.harnesses compatibility alias. New adapters use agent_workbench.harness_adapters.v1; entry-point targets and Python imports continue to live under gpt2giga_harness.* until a separately gated namespace migration.

Remove the old combined wheel before installing the split packages so stale gpt2giga/harness files cannot mask a migration error:

python -m pip uninstall -y gpt2giga gpt2giga-harness
python -m pip install 'gpt2giga-harness==0.4.1a1'

For uv tool installations, recreate both tool environments:

uv tool uninstall gpt2giga
uv tool uninstall gpt2giga-harness
uv tool install --prerelease allow gpt2giga
uv tool install 'gpt2giga-harness==0.4.1a1'

The current gpt2giga-harness==0.4.1a1 metadata keeps gpt2giga==0.2.4a1 in the explicit gpt2giga optional extra.

This package migration does not move or rewrite Harness state. Existing ~/.gpt2giga/harness data and project-local .giga/ directories remain in place. Do not delete them as part of uninstall/reinstall.

Troubleshooting

Start with:

giga doctor .
giga doctor . --json

Common checks:

• proxy is reachable at GPT2GIGA_HARNESS_PROXY_URL or http://127.0.0.1:8090;
• if relying on auto-start, giga doctor reports Proxy / Auto-start: ready;
• GPT2GIGA_API_KEY or GPT2GIGA_HARNESS_API_KEY matches the proxy when API-key auth is enabled;
• GIGACHAT_CREDENTIALS is present for real upstream calls;
• the selected mode uses the intended explicit route: /v1/chat/completions or /v2/chat/completions;
• external CLI harnesses report missing until the matching executable is on PATH or configured in ~/.gpt2giga/harness/config.toml; invalid configured paths and startup errors from broken CLI installations are reported by giga harness inspect <id> and the run result;
• real external CLI harness runs perform proxy preflight before launching the CLI, so proxy auto-start errors are reported directly instead of being buried in agent stdout/stderr.
• native history sync and import commands share the browser UI's native index; use giga native sync --include-external --json when debugging why a native ref is not visible in the UI.
• if a managed native session cannot be resumed, inspect the session bundle's native_links metadata for resume_reason.

Current Limitations

The alpha runs direct Chat Completions plus Codex, Claude Code, and Gemini CLI through capability-proven structured, terminal, or one-shot paths. External agent behavior still depends on the installed CLI's reviewed version window, structured protocol flags, custom local API endpoints, native resume, and local history formats. Claude embedded structured execution remains blocked; its provider-owned handoff is not durable continuity. Use --dry-run --json for direct compatibility commands and giga harness inspect <id> --json before selecting a structured or terminal transport on a new workstation.

Attachment support is intentionally conservative. Document and binary transport through external CLIs is path/reference based unless local CLI behavior has been verified. Structured/one-shot events and native terminal output use separate persisted SSE contracts; native terminals retain bounded polling as a compatibility fallback. Harnesses or plugins that do not emit structured deltas still appear atomically when their run completes.