Metadata-Version: 2.4
Name: gpt2giga-harness
Version: 0.5.0a1
Summary: Local agentic control plane for gpt2giga
Author-email: Ruslan Yakupov <rusyak1999@gmail.com>
License-Expression: MIT
Requires-Python: <3.15,<4,>=3.10
Requires-Dist: anyio<5,>=4.10
Requires-Dist: fastapi<1,>=0.133.0
Requires-Dist: pydantic<3,>=2.12.0
Requires-Dist: pyjwt[crypto]<3,>=2.12.0
Requires-Dist: python-dateutil<3,>=2.9.0
Requires-Dist: pyyaml<7,>=6.0
Requires-Dist: starlette<2,>=1.1
Requires-Dist: textual<9,>=8.2.8
Requires-Dist: tomli<3,>=2.0; python_version < '3.11'
Requires-Dist: uvicorn<1,>=0.41.0
Provides-Extra: claude-sdk
Requires-Dist: claude-agent-sdk<0.3,>=0.2.122; extra == 'claude-sdk'
Provides-Extra: gpt2giga
Requires-Dist: gigachat<0.3.0,>=0.2.2a1; extra == 'gpt2giga'
Requires-Dist: gpt2giga==0.2.5a1; extra == 'gpt2giga'
Description-Content-Type: text/markdown

# gpt2giga-harness

Local agentic control plane for the `gpt2giga` compatibility gateway. The
distribution provides the `giga` and `gpt2giga-harness` commands, the
`gpt2giga_harness` Python namespace, a durable local worker, and the packaged
Project Cockpit web UI.

> **Alpha preview:** the `0.4.x` storage, API, adapter, and automation contracts
> are stabilizing but may still change between prereleases. Use supervised local
> workflows first. The package metadata in the current checkout is the source of
> truth for the supported gateway requirement.

## Install the current preview

Install the published prerelease from your package index:

```sh
uv tool install 'gpt2giga-harness==0.5.0a1'
giga doctor
giga --version
giga
giga ui
```

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

```sh
uv tool install 'gpt2giga-harness[gpt2giga]==0.5.0a1'
```

The standard install includes the terminal workbench. Start it from the project
you want to manage:

```sh
giga
```

The default TUI mode composes the existing Harness application in-process: it
does not open a browser or start FastAPI/uvicorn. It provides keyboard-first
project and session navigation, session creation/resume, and an explicit
provider/Harness/model/transport readiness panel. Use `giga --attach
http://127.0.0.1:8091` only when an existing Harness UI/worker already owns the
runtime. Attach mode uses the same cookie/bootstrap-authenticated REST contracts
as Cockpit and never falls back silently to in-process mode. English and Russian
presentation catalogs are available through `--locale en|ru`.

Bare `giga` is the canonical TUI entry point; `giga tui` remains a compatibility
alias but is not a separate product surface. Root `--help`, `--version`, and TUI
options are owned by the same low-overhead TUI entry point without importing
Textual for metadata-only requests. On a supported interactive terminal, `chat`,
`run --agent`, and `session list|show|create|turn` deep-link into that same TUI
with their workspace, session, Harness, model, mode, transport, and prompt intent
preserved. There is no parallel transcript renderer.

| Command shape | Owner |
| --- | --- |
| bare `giga`, `giga tui`, human `chat`, `run --agent`, and selected `session` actions | built-in TUI |
| `--non-interactive`, `--json`, `--dry-run`, redirects, pipes, CI, admin commands, and session event/approval inspection | non-interactive CLI |
| `giga open ...` | explicit external handoff |

Machine routes never initialize Textual, prompt, or emit terminal control
sequences. `TERM=dumb` and unsupported terminals fail closed for an explicitly
requested TUI; redirected human commands retain their established CLI bytes,
schemas, exit codes, and stdout/stderr behavior.

## Prefix native agent commands

Add exactly `giga` before a Codex CLI, Claude Code, or Gemini CLI command:

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

There is no common `exec` verb: everything after `codex`, `claude`, or `gemini`
remains provider-owned. This includes `--help`, `--version`, stdin, stdout,
stderr, JSON/JSONL, `--`, signals, and exit status. On an admitted human TTY,
known session workflows may open the canonical Workbench; structured-version
drift degrades visibly to a provider-owned terminal handoff and never disables
otherwise valid native passthrough.

Generate conservative root completion without copying upstream parsers:

```sh
giga completion bash
giga completion zsh
giga completion fish
giga completion powershell
```

The generated scripts complete only the stable Harness boundary. Provider
suffixes, including unknown future flags and `--`, are left to the provider and
the shell's default completion behavior. `giga doctor --json` reports each
runtime's executable, version, L0/L1/L2 state, structured transport,
degradation, and remediation without storing prompts or provider output.

If you installed the earlier optional-TUI prerelease, upgrade the existing tool;
do not keep or add a `[tui]` extra:

```sh
uv tool install --force 'gpt2giga-harness==0.5.0a1'
giga --version
giga
```

Rollback uses the exact previously reviewed version, for example `uv tool
install --force 'gpt2giga-harness==<previous-version>'`. Remove the preview with
`uv tool uninstall gpt2giga-harness`; runtime state remains under the user-owned
Harness data directory and is not deleted by package uninstall.

For development or when the prerelease is not yet mirrored by your package
index, run it from a source checkout:

```sh
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 ui
```

Keep that environment active when you `cd` to the project you want to manage.
On Windows PowerShell, activate `.venv\Scripts\Activate.ps1` instead.

The current `gpt2giga-harness==0.5.0a1` metadata keeps
`gpt2giga==0.2.5a1` in the `gpt2giga` optional extra. Installing only
`gpt2giga` never adds Harness commands or the `gpt2giga_harness` namespace.

The provider-neutral base Harness install is intentionally limited to nine
reviewed direct runtime distributions. A clean installed-artifact audit fails
if the resolved environment grows beyond 64 distributions or pulls in the
`gpt2giga`/GigaChat provider preset, Office document libraries, remote-channel
SDKs, external client frameworks, or sandbox-provider SDKs. Those capabilities
must arrive through an explicit extra, separately installed provider, or
Harness plugin; they are not silently enabled by the base package. Release CI
runs the audit plus installed terminal-command smoke on clean Python 3.10–3.14
environments across Linux, macOS, and Windows:

```sh
python -I -m gpt2giga_harness.base_install --json
```

Run that command in a clean base-install environment. An environment where you
deliberately installed an optional provider is expected to report it as
`present` and fail the base-only policy check. The source-checkout development
sync above includes repository development extras and is therefore not a base
footprint measurement.

## First local run

From a disposable project directory:

```sh
giga init
giga doctor .
giga doctor . --json
giga ui
```

The doctor reports `ready`, `degraded`, and `blocked` checks for the local
proxy and routes, configured models, adapter CLI versions, workspace and Git,
the durable worker, Harness-managed homes, and managed MCP snapshots. JSON
evidence is redacted and omits absolute workspace paths; every degraded or
blocked first-run prerequisite includes a safe remediation command. Runtime
worker state is inspected read-only. The report also includes exact package,
Python, and platform metadata. Use `--fail-on blocked` (or the stricter
`--fail-on degraded`) for CI exit code 1, and `--output harness-doctor.json` to
atomically write a canonical mode-0600 issue attachment while keeping stdout
available.

Every CLI/UI run preflight also projects those checks onto the selected
execution plan before process spawn. Its redacted `readiness` section covers
only the chosen harness, invocation mode, API route/model, workspace policy,
and synchronous or durable delivery path. Missing required capabilities block;
degraded capabilities include the same bounded remediation commands as doctor.
Unrelated proxy, external-CLI, or worker failures do not block the independent
local Echo path.

## Review bootstrap and execution contracts

The first-run bootstrap is a separate reviewed workflow from `giga init`.
Preview is side-effect-free and returns an exact `plan_id`; apply accepts only
that current plan and the explicitly selected reversible steps:

```sh
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
```

Rollback removes only unchanged files and directories created by that
application. It fails closed if the workspace, data root, or generated content
has changed.

Before model-backed compatibility tests, run the bounded offline guardian:

```sh
giga compatibility check --json
```

It validates the reviewed native CLI windows, native protocol admissions,
Adapter and Integration SDK/schema versions, and marketplace source contracts
without starting a provider or installing an integration. A blocked fixture
returns exit code 1.

Every CLI and Workbench preflight also includes a content-free permission
simulation for the exact Harness, route, transport, workspace policy, and
selected extensions. It distinguishes allowed, approval-required, denied,
unknown, runtime-dependent, and provider-owned actions; a denial blocks startup
instead of relying on a later provider failure.

Runs Center can create a Trace-to-Replay comparison by changing exactly one
model, provider, Harness, or extensions axis. Preview binds the source evidence
and unchanged dimensions to a manifest hash; the replay starts in a new session
and never applies changes automatically. For a transfer that should not execute
the target, create a truthful handoff capsule:

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

The capsule contains bounded task/evidence identities, environment state,
pending approvals, and explicit continuity limits. It does not copy secrets,
start either Harness, or claim that provider-owned history can be resumed.

For a credential-free tour, copy the
[first-run demo](../../examples/harness/first-run-demo/README.md). It keeps
runtime state inside the disposable copy and verifies `giga init`, the local
Echo read path, and the generated smoke eval without starting a proxy or an
external agent CLI.

For the first model-backed north-star flow, copy the
[issue-to-reviewed-patch example](../../examples/harness/issue-to-reviewed-patch/README.md).
It packages reviewed agent profiles, a durable isolated-worktree workflow, and
a post-apply eval while keeping apply, commit, push, and hosted writes explicit.

For unattended compatibility evidence, copy the
[nightly compatibility guardian](../../examples/harness/nightly-compatibility-guardian/README.md).
It packages a pinned Codex/Claude/Gemini eval, exact baseline dimensions, a
read-only triage workflow, and a durable schedule that runs without the UI and
raises Attention only after a tested contract regresses.

For parallel evidence-backed review, copy the
[cross-harness review team](../../examples/harness/cross-harness-review-team/README.md).
It fans out read-only explorer, security, tests, and maintainability roles
across Codex, Claude, and Gemini, then synthesizes retained child artifacts
without introducing a shared writable workspace.

Open `http://127.0.0.1:8091/`. `giga ui` starts a durable local worker when
needed; pass `--no-start-worker` when another supervisor owns that lifecycle.
The default loopback binding is intentional. Remote binding requires explicit
single-issuer OIDC configuration plus `--allow-remote`; incomplete identity
configuration, plain HTTP public origins, unmapped subjects, and untrusted
proxy headers fail closed. Configure and deploy that boundary only behind the
reviewed HTTPS/proxy controls described in the remote UI identity ADR.

Validate deployment-owned identity configuration without contacting the
issuer, or revoke every remote session from the OS-local CLI:

```bash
giga ui-identity validate --json
giga ui-identity revoke-all --confirm --json
```

The root URL opens Cockpit V2. During its release-level rollback window, the
previous no-build cockpit remains available at `http://127.0.0.1:8091/legacy`
without migrating or rewriting Harness runtime state.

After the first run starts, Workbench reveals a compact Run → Evidence → Review
→ Reuse path. Once the run reaches a terminal state, the exact retained trace
is available in Runs; prompts, responses, and workspace paths are not copied
into the transition summary. For a retained isolated patch, the Review tab
opens that run's diff while apply and approval remain separate explicit
operator actions. An eligible successful run exposes its existing provenance
and promotion state under Reuse. Promotion preview/apply and later scheduling
remain separate explicit actions.

Retained assistant messages expose a Copy action that fetches the complete
stored response instead of copying a bounded read-model preview. For structured
and one-shot runs, only the latest retained user message exposes a pencil
action. Resubmitting that edit replaces the active turn and its following
assistant response in Workbench, while the superseded run remains retained in
Runs for audit. Native terminal sessions do not expose the pencil because a
retained interactive process cannot be rewound safely.

Useful orientation commands:

```sh
giga config path
giga project info
giga harness list
giga harness inspect codex-cli --json
giga session list
giga native list
giga worker status
```

## Review Git and GitHub changes

For a session backed by a Git workspace, TUI and Cockpit show a bounded
environment snapshot: worktree identity, branch and HEAD, staged, unstaged, and
untracked counts, upstream readiness, and optional read-only GitHub pull-request
and checks/runs status. The snapshot never includes diff contents, remote
credentials, or raw `git`/`gh` output.

Workbench can create one exact staged commit, perform one non-force push, and
create one GitHub pull request. Each mutation is two phase: first review the
HEAD/diff or local/remote-bound preview, then approve that exact action in the
Inbox and apply it. A changed checkout, moved remote, detached HEAD, repository
mismatch, stale approval, or unsupported hosted state fails closed. The TUI
exposes the same flows through `/commit`, `/push`, and `/pr`; it does not stage
files, force-push, merge, or bypass provider-owned branch protection.

Git inspection and local commits require `git`. Read-only GitHub enrichment and
pull-request creation require an authenticated `gh` executable for the exact
repository derived from the configured remote. Authentication and permission
failures are projected as content-free reason codes.

## Review Arena candidates

After all Arena candidates finish, Cockpit can score each result from 0 to 1 and
select one succeeded candidate. **Record verdict** binds those scores and the
winner to the exact candidate evidence-set hash. The verdict is immutable:
follow-up, retry, or changed evidence requires a new comparison. Harness exposes
promotion links for the selected run, but never applies its patch or promotes
configuration automatically.

## Provider-neutral routes

Cockpit Settings and `giga provider` manage reference-only profiles for
OpenAI-, Anthropic-, and Gemini-compatible endpoints. A profile owns its
protocol dialect, base URL, route prefix, authentication reference, enabled or
offline state, and model defaults for coding, titles, evaluation, and fallback.
Credential values are never accepted by the settings API or returned to the
browser; they are resolved only at the owning request/subprocess boundary.

```sh
giga provider list --json
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 show openai-production --json
```

Use `giga provider test` or `discover` for an explicit bounded check; failures
remain content-free and never trigger a silent provider fallback. Migrate old
proxy/API-mode/model defaults only after previewing the forward-only plan and
choosing a pre-upgrade backup outside the Harness data directory:

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

Rollback means stopping Harness and restoring that verified archive; reverse
migration is intentionally unsupported.

## Built-in adapters

- Direct Chat through the local gateway;
- Codex CLI through durable `native_structured` app-server sessions, a managed
  native terminal, or an explicit one-shot compatibility run;
- Gemini CLI through durable `native_structured` ACP sessions, a managed native
  terminal, or an explicit one-shot compatibility run;
- Claude Code through an explicit one-shot run or managed native terminal,
  plus a separate provider-owned Remote Control/Desktop handoff preview;
- Echo for deterministic smoke tests.

Workbench and `giga session turn` use the canonical transport names
`native_structured`, `native_terminal`, and `one_shot`. Codex and compatible
Gemini installations default to structured durable sessions. Claude embedded
structured execution remains unavailable; its provider handoff is explicitly
non-durable and does not become a Harness-owned session. Inspect the exact
capability and blocker before execution:

```sh
giga harness inspect gemini-cli --json
giga session turn <session-id> --transport native_structured --prompt "Inspect"
```

External CLIs are discovered on `PATH`. Non-standard absolute paths belong in
the user-owned `~/.gpt2giga/harness/config.toml`:

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

Manage these values without editing TOML directly:

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

Configured paths take precedence over `PATH`, must be absolute, and are checked
for executable capabilities before a structured, terminal, or one-shot run
starts.

External CLI execution is supported only when both the bounded help probe and
the declared version window pass: Codex CLI `>=0.144.0,<0.145.0`, Claude Code
`>=2.1.0,<2.2.0`, and Gemini CLI `>=0.46.0,<0.47.0`. Inspect
`compatibility.version_contract` with `giga harness inspect <id> --json`.
Older or capability-incomplete binaries are `unsupported`; newer or
unparseable versions are `degraded` and remain fail-closed until their fixtures
and support window are reviewed.

## Storage and safety boundaries

- User-level coordination state: `~/.gpt2giga/harness/`;
- project configuration and references: `<project>/.giga/`;
- vendor-owned Codex, Claude, and Gemini homes: read or imported only through
  adapter-specific contracts; Harness must not rewrite them;
- edit runs: isolated worktrees with lease and policy checks;
- risky native spawn, remote access, apply, and secret operations: explicit
  approvals.

The control plane stores redacted metadata by default. Content capture and
secret materialization are opt-in and should have explicit access, retention,
and cleanup policies.

### Read-only skills.sh metadata proxy

`giga-skills-catalog-proxy` is an independently deployable, metadata-only
boundary for the authenticated `https://skills.sh/api/v1/` catalog. It exposes
only bounded GET list, search, detail, and health routes, strips detail file
contents, never accepts an arbitrary upstream URL, and resolves
`VERCEL_OIDC_TOKEN` inside each upstream request without persisting or logging
the bearer value.

Safe local configuration keeps the listener private by default:

```sh
export VERCEL_OIDC_TOKEN='<request-scoped token supplied by Vercel>'
export GIGA_SKILLS_PROXY_HOST=127.0.0.1
export GIGA_SKILLS_PROXY_PORT=8092
export GIGA_SKILLS_PROXY_RATE_LIMIT=120
giga-skills-catalog-proxy
```

Binding to `0.0.0.0` is explicit and should be done only behind an HTTPS
reverse proxy with its own access controls. The service never installs catalog
entries and does not grant installation authority.

Point Cockpit search at that fixed proxy origin when starting the UI:

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

### Federated Skills and MCP lifecycle

Cockpit's **Plugins** area and `giga integration list --json` read the same
offline-first inventory. `skills-sh` supplies hosted Skill metadata through the
proxy above; `neuraldeep` supplies public Skill and MCP metadata. Source health,
popularity, curation, and presence never authorize installation. The catalog
keeps its last good state on source failure, and a NeuralDeep MCP card can only
correlate with an exact official MCP Registry identity without replacing the
official immutable version or integrity.

The **Skills**, **Plugins**, and **MCP** pages expose **Add Skill**, **Add
Plugin**, and **Add MCP** respectively. Git Skill import accepts public GitHub
repository and `/tree/<ref>` URLs, pins the resolved commit, lets the operator
choose one bounded `SKILL.md`, and shows its instructions before approval.
Native Plugin/Extension import requires a reviewed `integration-package.json`;
raw MCP import accepts an exact stdio or HTTP descriptor. Shared root Skills
from `~/.agents/skills` and provider-specific Skill homes appear in inventory
and can be filtered by Codex, Claude, Gemini, or Harness. Override shared roots
with the OS-path-separated `GIGA_ROOT_SKILLS_DIRS` variable.

System bundles already shipped by OpenAI are projected as read-only Plugins
with an OpenAI source badge, bundled Skill names, default prompts, and their
`@name` invocation hint. Type `@` in Work to choose one; for Codex CLI runs the
composer translates that selection to the native `$name` Skill invocation.
Every federated result also retains its source badge. The canonical NeuralDeep
GigaChat Image MCP page is
[NeuralDeep GigaChat Image MCP](https://neuraldeep.ru/mcp/gigachat-image).

An external Skill must match its reviewed immutable reference and content hash
before bounded `SKILL.md` validation and target projection. A normalized MCP
candidate likewise keeps exact package integrity, argv, origins, secret
references, permissions, and native-consent boundaries in the preview. Review
and operate one target with:

```sh
giga integration preview --source catalog --catalog-id <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
```

For **Install to all Harnesses**, use `group-preview`, `group-apply`,
`group-status`, `group-recover`, and `group-rollback`. Skills expand to Codex,
Claude, and Gemini; MCP expands to those managed native homes plus the
Harness-managed MCP inventory. Every child preview must pass before mutation.
Cross-root apply is a durable compensating transaction: partial failure rolls
back owned verified children or records exact recovery actions. Updates require
a new immutable pin, preview, and approval. Federated discovery never implies
Plugin installation or network authority; Plugin execution requires an exact
reviewed manifest, and real user homes are never the default mutation scope.

Portable Extension Packs combine one reviewed Skill and one reviewed MCP catalog
entry under an exact pack id/version. Preview computes a per-provider
compatibility matrix and expands only supported Codex, Claude, Gemini, and
Harness-managed targets into one recoverable compensating transaction:

```sh
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
```

An incompatible provider is reported and excluded, never silently coerced.
Apply remains bound to the previewed children, permissions, immutable package
integrity, and exact MCP configuration; recovery and rollback use the normal
group lifecycle.

The equivalent API begins at `GET /api/integrations`, with single-target flows
under `/api/integrations/flows` and grouped flows under
`/api/integrations/groups`.

## Plugin contract

Third-party adapters register through the versioned, provider-neutral
`agent_workbench.harness_adapters.v1` entry-point group, while import targets
live outside the gateway namespace:

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

The legacy `gpt2giga.harnesses` group remains a compatibility alias. Packages
may advertise the same target through both groups during migration; equivalent
duplicates are loaded once, while conflicting adapter IDs fail without
overwriting the first registration.

Use `giga harness scaffold`, `giga harness validate`, and
`giga harness inspect` to develop and diagnose an adapter. Pass
`--output <directory>` to scaffold a complete out-of-tree package with a
versioned, content-free manifest, neutral entry points, a fake provider fixture,
and a hermetic conformance test. After installing the package, run
`giga harness conformance <adapter-id> --json`.

SDK API v1 reports execution, sessions, approvals, attachments, integrations,
recovery, history, telemetry, and packaging separately. A capability passes
only when the manifest declares it and a corresponding behavioral probe passes;
omitted claims remain `unsupported` and are never inferred from legacy adapter
metadata.

## Back up user state

Stop the Cockpit, durable workers, and active runs before taking an offline
backup. Write the archive outside `~/.gpt2giga/harness` and verify it before an
upgrade or package rollback:

```sh
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 versioned archive preserves Harness-owned files and consistent SQLite
snapshots with deterministic hashes. It excludes transient lock, WAL, SHM, and
temporary files, rejects symbolic links, and fails if source state changes
during capture. The archive is created with mode `0600`, but it may still
contain opt-in captured content, attachments, or managed configuration; treat
it as private state, not as a support bundle. Project-local `.giga/` directories
remain separate and should stay in the project backup or version-control plan.

`giga state restore` verifies the archive again, rejects a runtime schema newer
than the installed Harness supports, stages every file with its retained mode
and SQLite integrity check, then publishes the directory through an offline
sibling swap. An existing destination is never overwritten without
`--replace`, and active lock/WAL/SHM markers or a concurrent state change fail
before publication. Older runtime schemas are migrated only by the next normal
Harness startup; there is no reverse migration. For rollback, restore the
pre-upgrade archive after reinstalling the package version that created it.

`giga runtime export` remains the redaction-safe coordination export for issue
reports.

## Upgrade from the combined prerelease

Uninstall both old distributions before installing the split packages. Do not
delete `~/.gpt2giga/harness/` or project `.giga/` state during the package
migration:

```sh
uv tool uninstall gpt2giga
uv tool uninstall gpt2giga-harness
uv tool install 'gpt2giga-harness==0.5.0a1'
giga doctor
```

## Documentation

- [Unified Harness guide](https://ai-forever.github.io/gpt2giga/harness)
- [Harness architecture](https://ai-forever.github.io/gpt2giga/architecture/harness)
- [Configuration and security](https://ai-forever.github.io/gpt2giga/harness#configuration)
- [Native sessions](https://ai-forever.github.io/gpt2giga/harness#native-session-mode)
- [Troubleshooting](https://ai-forever.github.io/gpt2giga/harness#troubleshooting)
- [Changelog (RU)](https://github.com/ai-forever/gpt2giga/blob/main/packages/gpt2giga-harness/CHANGELOG.md)
- [Changelog (EN)](https://github.com/ai-forever/gpt2giga/blob/main/packages/gpt2giga-harness/CHANGELOG_en.md)

## Package verification

From the repository root:

```sh
uv sync --all-packages --all-extras --dev
uv run pytest tests/harness -q
uv build --package gpt2giga-harness --no-sources
```
