## Purpose

Provide a reproducible repository-backed installation path for the prebuilt Codex App Server bridge while a private npm registry is unavailable.

## Requirements

### Requirement: Runnable package from immutable Git revision
The project SHALL support normal global npm installation from an immutable Git tag or full commit whose installed `codex-app-server-bridge` executable launches the compiled bridge without a source checkout, TypeScript compiler, local tarball, or package lifecycle scripts.

#### Scenario: install a pinned Git revision
- **WHEN** a user globally installs a supported Git repository URL pinned to a release tag or full commit on Node.js 24 or newer
- **THEN** npm installs a real package directory and `codex-app-server-bridge` resolves on the normal global PATH

#### Scenario: install without lifecycle scripts
- **WHEN** the pinned Git revision is installed with package lifecycle scripts disabled
- **THEN** installation succeeds because the selected revision already contains the compiled runtime required by the launcher

#### Scenario: reject an unbuilt revision
- **WHEN** a selected Git revision lacks the launcher or either declared compiled runtime file
- **THEN** Git-package verification fails before that revision is documented or installed

### Requirement: Source and committed runtime remain synchronized
The project SHALL provide a repeatable freshness check proving that the committed `dist/cli.js` and `dist/config.js` runtime matches the current TypeScript source while excluding all other generated output from Git distribution.

#### Scenario: fresh committed runtime
- **WHEN** a maintainer compiles from a clean indexed baseline and runs the freshness check
- **THEN** rebuilding produces no difference in either committed runtime file

#### Scenario: stale committed runtime
- **WHEN** TypeScript source changes without its corresponding compiled runtime update
- **THEN** the freshness check exits unsuccessfully and identifies generated runtime drift

### Requirement: Independent Git-install validation
The project SHALL provide a repeatable verifier that accepts exactly one supported Git package URL pinned to a release tag or full commit, installs it into an isolated global prefix with lifecycle scripts disabled and a dedicated cache, rejects temporary-cache links or missing runtime files, and exercises the installed executable without contacting a Codex App Server.

#### Scenario: valid Git-installed package
- **WHEN** the verifier installs a selected immutable Git revision
- **THEN** the package is independent of npm temporary clone paths and its installed executable reaches the expected unsupported-invocation contract

#### Scenario: invalid Git verifier input
- **WHEN** the verifier receives no package spec, multiple specs, a mutable branch, an abbreviated commit, an unsupported URL, or an unusable executable
- **THEN** it exits unsuccessfully with a diagnostic that does not expose repository credentials or configuration secrets

### Requirement: Documented Git installation lifecycle
The project SHALL document the canonical repository, Git access and default-branch preflight, immutable tag-or-commit selection, normal global installation, upgrade, rollback, removal, PATH verification, and unchanged agent-shell configuration.

#### Scenario: upgrade from tarball installation
- **WHEN** a user installs a newer verified Git release over the existing local-tarball package
- **THEN** npm replaces the package while the executable name and Emacs `CODEX_PATH` integration remain valid

#### Scenario: roll back Git installation
- **WHEN** a user reinstalls a previously verified Git revision or tarball
- **THEN** npm restores that version without requiring an agent-shell configuration change

#### Scenario: activate the replacement bridge
- **WHEN** the globally installed Git release has been verified
- **THEN** new agent-shell launches resolve the replacement PATH executable while existing bridge processes and the shared App Server remain unmanaged