[Feature]: Make Needle an installable, opt-in companion for Codex

[JJordan0C]

Problem

Needle's primary product path already includes a Codex plugin, lifecycle hooks, the internal @@need semantic interrupt protocol, a local resolver, SQLite persistence, role profiles, and an embedded web control plane. However, these components currently form a source-development workflow rather than a usable product experience.

A user must build the frontend and Rust workspace, initialize a data directory, understand role-profile creation and activation, decide whether to run the resident server, and manually reason about plugin or MCP integration.

The intended hook-based behavior is already present: Codex receives the Needle protocol at session start, emits an internal @@need request when repository evidence is required, and the Stop hook resolves that request before Codex continues. The user should not need to know that this protocol exists.

Needle currently lacks the installation, explicit activation, first-run configuration, on-demand startup, and user-facing status needed to make this flow practical.

The normal product path should not require users to configure MCP, start a process manually, create role-profile revisions, or write @@need markers.

Expected outcome

A new user can:

1. install Needle once from a downloadable Windows artifact or a documented PowerShell/cmd installation command;
2. enable or disable Needle for the current repository through a small CLI or local UI;
3. open Codex normally;
4. submit ordinary repository tasks;
5. let Codex request Needle evidence automatically through the internal hook protocol;
6. receive the completed Codex response without configuring MCP, starting a process manually, creating role-profile revisions, or seeing @@need as a user-facing response.

When Needle is disabled, it adds no protocol context, starts no resolver, and leaves native Codex behavior unchanged.

The intended user experience is:

Install Needle once
-> enable it for a repository
-> open Codex
-> work normally

### Product area

Runtime or lifecycle orchestration, Codex adapter or worker execution, Web control plane, Packaging or compatibility, Documentation

### Proposed scope

### Installation and packaging

- Produce a release-ready Windows installer and portable archive containing the `needle` binary, product plugin, license, and integrity metadata.
- Provide a documented PowerShell/cmd installation path using the same versioned artifacts.
- Verify artifact integrity before installation.
- Detect the compatible native Codex executable without storing credentials.
- Ask for explicit permission before registering or modifying Codex plugin configuration.
- Report unsupported or incomplete environments with actionable diagnostics.
- Keep GitHub release publication a separate human-owned action.

### Activation model

Add a persistent activation state exposed through:

```text
needle enable
needle disable
needle status
needle ui

• needle enable enables Needle for the current repository.
• needle enable --global explicitly enables it for all compatible repositories.
• needle disable disables Needle without deleting configuration, profiles, cache, or evidence.
• needle status reports installation, activation scope, Codex compatibility, selected worker profile, and runtime health.
• needle ui opens the existing local control plane.
• Repository-specific disablement overrides global enablement.
• Activation changes are explicit, local, audited, and stored through an additive checksummed migration.

First-run configuration

On the first needle enable:

• detect Codex and the current repository;
• ask only for settings that cannot be safely inferred, primarily worker model and bounded cost policy;
• create and activate a safe default explorer role profile;
• default to read-only tools and filesystem access, denied network access, disabled test execution, no repair, and native fallback;
• run compatibility and isolation preflight;
• leave Needle disabled if setup or preflight fails;
• provide an actionable explanation for every failed requirement.

Advanced role-profile editing remains available, but it is not required for normal onboarding.

Transparent hook routing

• Use the product lifecycle-hook plugin as the default integration.
• Do not require MCP configuration for the normal product path.
• At SessionStart, inject the Needle protocol only when activation applies to the current repository.
• Allow Codex to emit an internal typed @@need block when repository evidence is required.
• Intercept the marker through the Stop hook, resolve it once, and continue the same Codex task with bounded Needle context.
• Do not expose the marker as the completed user-facing assistant response.
• Start the resolver on demand.
• Do not require a manually started needle serve process for ordinary read-only resolution.
• Use the resident runtime when available and preserve the bounded local fallback.
• Fail open to native Codex discovery when Needle is unavailable, disabled, incompatible, or unable to validate evidence.
• Do not weaken cache validation or automatically promote capability authority to manufacture a cache hit.

Local UI

Reuse the embedded control plane through needle ui.

The initial view should prioritize:

• enabled or disabled state;
• activation scope and repository;
• Codex compatibility;
• selected worker profile;
• runtime state;
• recent Needle outcomes such as hit, worker, bypass, or fallback;
• access to advanced settings.

CLI and UI must operate on the same activation and configuration state.

Documentation

Add a user-oriented onboarding guide that begins with installation and normal Codex usage.

Keep the existing source-development setup as a separate contributor workflow.

The guide must state clearly that:

• users do not write @@need;
• MCP is an optional alternative transport, not the default plugin path;
• disabled Needle does not alter Codex behavior;
• Needle remains a pre-alpha developer preview with unstable interfaces.

Non-goals

• Making MCP the default integration.
• Running or publishing provider-backed benchmarks.
• Supporting non-Codex agent hosts.
• Claiming stable installation, API, configuration, or storage compatibility.
• Automatically enabling trusted test execution.
• Automatically promoting semantic capabilities.
• Requiring an always-running background service.
• Publishing a GitHub release as part of the implementation contribution.

Alternatives considered

Keep the current source-development workflow

This exposes internal build, database, runtime, and role-profile concepts before a user can evaluate the product. It remains appropriate for contributors, not onboarding.

Require MCP configuration

MCP provides a structured tool boundary, but requiring users to configure a server and understand its tools does not match the intended transparent plugin experience. MCP should remain available for explicit integrations and testing.

Keep the plugin always active

Always injecting the protocol would add context overhead and alter Codex behavior without repository-level user intent. Activation must be explicit and reversible.

Require an always-running background service

The resolver can use a resident runtime when available and fall back locally. Ordinary read-only use should start on demand. A resident process should be needed only for the control plane, approvals, or operational visibility.

Build a separate desktop application first

The existing embedded React control plane can provide the first local UI without introducing a second configuration system or a new desktop framework. A native desktop shell can be evaluated separately.

Compatibility, safety, and performance impact

• Installation and Codex plugin registration require explicit user authorization.
• Needle must not silently rewrite unrelated global Codex configuration.
• Repository-scoped activation is the safe default; global activation is explicit.
• Disabled sessions receive no Needle protocol and start no Needle process.
• Credentials remain outside SQLite, configuration exports, logs, and installer state.
• First-run defaults preserve read-only workers, denied network access, disabled tests, bounded execution, and native fallback.
• Activation persistence requires an additive checksummed migration and explicit scope-precedence rules.
• On-demand startup adds latency to the first resolved request. Status and diagnostics should distinguish startup, cache lookup, worker execution, and fallback.
• Packaging must not claim platform support beyond the current compatibility and evidence boundary.
• Installer, setup, UI, and validation must not make provider calls.
• Existing MCP, hook, cache, proof, and security contracts must remain compatible unless explicitly documented otherwise.

Acceptance evidence

• A clean Windows environment can install a versioned Needle artifact and verify its integrity.
• Installation registers the product plugin only after explicit confirmation.
• needle enable, needle disable, needle status, and needle ui have process-level tests covering exit status, stdout, stderr, and persistent state.
• Repository and global activation precedence has deterministic coverage.
• First enable creates exactly one valid active explorer profile and remains idempotent.
• Failed setup or preflight leaves Needle disabled and reports the exact reason.
• A disabled SessionStart injects no protocol context.
• A disabled Stop hook performs no resolution and preserves native Codex behavior.
• An enabled deterministic Codex fixture emits a valid marker, invokes the resolver once, receives bounded context, and continues the original task.
• Duplicate, malformed, disabled, unsupported, and failed resolutions preserve native fallback behavior.
• The internal marker is not retained as the completed user-facing response in the supported hook fixture.
• An eligible validated cache fixture can resolve with zero workers without weakening promotion or freshness requirements.
• needle ui and the CLI read and mutate the same activation state.
• Installer and portable-package smoke tests verify the executable, embedded web assets, product plugin, license, and integrity metadata.
• User documentation covers installation, enablement, disablement, normal Codex use, status, and uninstall behavior.
• Existing Rust, frontend, plugin, MCP, and offline integration suites remain green.
• No provider-backed run is required or authorized by this issue.

Additional context

Related work:

• Add top-level --help and --version support to the Needle CLI #29
  • Adds top-level --help and --version; complementary to this onboarding flow.
• Define the explicit OS, toolchain, host, API, configuration, and storage support policy #8
  • Defines the broader compatibility policy; this request remains a Windows-first developer-preview slice.
• https://github.com/IASolutionOrg/needle/blob/main/docs/DEVELOPER_SETUP.md
• https://github.com/IASolutionOrg/needle/blob/main/docs/RUNTIME_AND_WEB_CONTROL_PLANE.md
• https://github.com/IASolutionOrg/needle/blob/main/docs/ARCHITECTURE.md
• https://github.com/IASolutionOrg/needle/blob/main/PROJECT_STATUS.md

This request does not claim that Needle is release-ready, production-supported, statistically validated, or compatible with every Codex, operating-system, API, configuration, or storage version.

Submission checks

• I checked PROJECT_STATUS.md and docs/ROADMAP.md for the current boundary.
• I searched existing issues for the same request.
• I understand that an accepted request is not a release, support, performance, or provider-backed evidence claim.
• This request contains no credentials, private source, sealed benchmark material, or vulnerability details.