# Superadmin releases from an AI session

The session sidebar provides **Commit and push** and **Merge and deploy** for configured
development projects. The platform `superuser` role is required by the server, not just the UI.
Licence-scoped assistant projects cannot issue releases.

## User flow

1. Finish the AI turn and inspect the changes. Select the files and enter a commit message.
2. **Commit and push** commits only those files. A detached conversation receives a named
   `ai/session-<conversation-id>` branch. Other staged files remain staged. A clean session
   offers **Push commit**, including recovery after a successful commit followed by failed push.
3. With the session clean, choose **Merge and deploy** and confirm the displayed source commit.
   The independent runner fetches current remote main, constructs an isolated merge, runs the
   configured checks, pushes without force, deploys that exact merged commit, and verifies its
   deployment receipt. Concurrent advancement of remote main can refuse the push.
4. Progress and the resulting commit survive page reconnects and an IIS recycle. A failed
   deployment after push explicitly says main was already updated. Conflicts and failed checks
   leave remote main unchanged. Failed build folders remain available for diagnosis.

The primary checkout is preserved, including unfinished work. A successful merge updates
**remote main**; it does not reset or overwrite a dirty local main checkout. Update that checkout
with the normal reviewed Git workflow after its outstanding work is preserved.

## Execution and authorization

`AiReleaseService` takes the conversation row lock and a repository advisory lock before
queuing a request. Active AI turns on the primary repository prevent a release, and queued
releases prevent new turns on that repository. The UI disables editing and archiving while
its release is active. External editors are not controlled by these application locks;
stop external edits while releasing. Head and content fingerprints reject changed reviews.

The web application writes requests and reads results. A separate scheduled process, running
under a configured release account, owns deployment privileges and serializes release jobs.
Its executable, scripts and configuration are operator-owned. Each request must match a
committed `audlog` record, including actor, action, source fingerprint and files; the runner
also verifies that the actor still holds the active superadmin role. A writable request file
alone is insufficient to authorize execution.

Results and approval receipts are under the queue's `results` directory; source and release
evidence remain under `builds` and `prepared`. Request audit records retain each submitted
action. The sidebar displays the latest action. Raw process errors are not sent to the browser.

A runner interrupted mid-action records `Interrupted` and creates `results/recovery-required`.
It refuses further execution until an operator reconciles Git, deployment journals and any
surviving child processes, then explicitly removes that marker. Do not replay an unknown
deployment outcome automatically. An absent runner heartbeat disables new submissions.

## Deployment adapters

**Sibyla:** the adapter uses `Prepare-Deploy.ps1`, then the deployment module's WhatIf and
Execute paths. Existing candidate fingerprints, renewal guard, schema privilege proof, IIS
backup, rollback and twelve health checks remain. The explicit superadmin UI approval replaces
the console confirmation only for this routine deployment path. The privilege query uses the
existing application's database connection for a read-only catalog check, so it needs no
PostgreSQL administrator password in the browser. The ordinary console launcher still works.
This implements the owner's 2026-09-09 request to execute releases inside the UI session.

**IdentityServer:** validates the solution, publishes into a new release directory, preserves
host configuration and the existing application-pool identity, links existing uploaded logos,
backs up IIS, changes the site path, and checks OIDC discovery/signing keys. A failed health
check restores the prior site path. Existing releases and shared identity data are retained.
Automatic production database migrations are not part of these adapters; schema changes must
meet each application's release prerequisites.

Athena, Medusa, Calypso and Skill Build can use Commit and push from their base folders.
The sample config supplies deployment adapters only for Sibyla and IdentityServer. Project
keys must match the actual AI Projects configuration; the sample keys are examples.

## One-time host setup

1. Choose a release account with Git push access, build/test prerequisites, permission to read
   the existing web secrets, and the Windows privileges required by the deployment tooling.
   The existing Sibyla deployment module requires an elevated administrator token. Use a
   dedicated task account; the IIS application pool stays unprivileged.
2. Adapt `local/release/runner.example.json` to the actual project keys and paths. Adapt
   `validation.example.json` to the installed Preview database credentials, Skill Build source
   and Playwright installation. These JSON files contain paths, not embedded credentials.
3. In an elevated console, install with a new installation directory:

   ```powershell
   $releaseAccount = Get-Credential
   .\local\release\Install-ReleaseRunner.ps1 `
       -ConfigurationPath .\local\release\runner.example.json `
       -ValidationConfigurationPath .\local\release\validation.example.json `
       -Credential $releaseAccount -RegisterTask
   ```

   The task runs once per minute under its own stored Windows logon. Git authentication must
   work noninteractively for that account. The installer refuses an existing installation.
4. Merge the generated `web-configuration.json` fragment into the web host configuration,
   preserving every existing setting. Deploy the feature through the existing operator release
   process once. Further releases can then originate in the session UI.
5. Verify the runner heartbeat and perform an approved end-to-end release before treating this
   as production accepted. The feature does not self-install or deploy the current worktree.

`Sibyla.ReleaseRunner --check-config <runner.json>` performs a read-only database authorization
query without consuming queued requests. No schema migration is required for this feature.

## Validation scope

The automated Git tests use local bare remotes and disposable directories. Deployment commands
are substituted in those tests: they exercise merge/push ordering, source binding, conflict and
validation failures, and the receipt requirement without activating production. Renderer tests
cover role visibility, pending controls and offline recovery. Desktop/mobile component captures
verify the established stylesheet stack; they are not full authenticated end-to-end acceptance.

Verification on 2026-09-09: solution build passed with zero warnings/errors; 15 focused Platform
tests, four release renderer tests and two existing session lifecycle tests passed (21 total).
The PowerShell preparation-safety checks and script parsing passed. The runner's read-only
authorization query succeeded against the configured host database. No production deployment
or runner installation was performed during implementation. The subsequent GPT-6 Astra catalogue
fix passed all seven Codex harness tests.