instar 1.2.11 → 1.2.12

package/upgrades/1.2.12.md

@@ -0,0 +1,82 @@
+# Upgrade Guide — v1.2.12 (hybrid wizard for Codex runtime)
+
+<!-- bump: patch -->
+<!-- patch = bug fixes, refactors, test additions, doc updates -->
+
+## What Changed
+
+**New: hybrid setup wizard for Codex-runtime installs.**
+
+`npx instar` → pick Codex CLI at the runtime prompt → now reaches
+an actual conversational walkthrough. Before this release, Codex
+ignored the wizard skill's behavioral contract and executed the
+entire setup non-interactively, leaving the user with a generic
+agent identity they never got to shape.
+
+The fix is a two-layer architecture under
+`src/commands/setup-wizard/`:
+
+1. **State machine** owns the conversation flow. Each state has a
+   structural prompt printed verbatim by instar, a deterministic
+   transition function, and (for action states) a side effect call
+   to existing CLI commands. Order is fixed in TypeScript code; no
+   LLM can drift it.
+
+2. **Codex driver** drives the state machine turn-by-turn. For each
+   conversational state, the driver runs `codex exec -s read-only
+   -m gpt-5.3-codex --ephemeral` with a tightly-constrained prompt
+   asking Codex to generate ONE warm 2-3 sentence intro paragraph.
+   The structural prompt is printed by instar; readline reads the
+   answer. Codex cannot use tools, cannot reword the question,
+   cannot decide to execute the setup itself.
+
+3. **Telegram setup phase** hands off to Codex as a full agentic
+   session (sandbox bypass + Playwright access) — driving the
+   browser is execution, which is Codex's strength.
+
+Claude-runtime users see no change. The Claude path keeps the
+existing `/setup-wizard` slash-command spawn.
+
+Settings the user picks during the wizard (agent name, focus,
+autonomy level, messaging channel) can all be changed later just
+by chatting the agent. The farewell text and the autonomy step's
+narrative both surface this affordance.
+
+Spec: `specs/dev-infrastructure/hybrid-wizard.md`.
+ELI16: `specs/dev-infrastructure/hybrid-wizard.eli16.md`.
+Side-effects review: `upgrades/side-effects/feat-hybrid-wizard.md`.
+
+## What to Tell Your User
+
+The setup wizard now walks you through identity, autonomy, and
+messaging conversationally, regardless of which runtime you picked.
+On Codex, the wizard runs as a state machine in instar itself with
+Codex generating the warm narrative for each step; on Claude it
+runs the same way it always has. Anything you set up can be
+changed later just by chatting your agent — no need to re-run setup.
+
+## Summary of New Capabilities
+
+- New module: `src/commands/setup-wizard/` (state machine + Codex
+  driver + model constants).
+- New CLI behavior: `npx instar` → pick Codex CLI → conversational
+  wizard with per-step narrative from Codex.
+- Existing CLI surface unchanged.
+
+## Evidence
+
+Reproduction prior to fix: ran v1.2.11 install via bareword `npx
+instar` → picked Codex. Codex received the wizard skill prompt and
+executed the entire setup non-interactively. Full log captured at
+`setup-logs.md` in the test project — 2940 lines, zero
+conversational walkthrough.
+
+After fix:
+- 12 new state-machine unit tests cover the choice resolver, graph
+  integrity, identity-answer threading, messaging branching, and
+  the post-server completion chain.
+- 5 updated canary tests cover the dispatch contract: setup.ts
+  imports `runCodexWizard` for codex-cli, no codex exec argv with
+  the wizard skill prompt remains in setup.ts, the driver's codex
+  exec spawns still pin `-m WIZARD_CODEX_MODEL`.
+- End-to-end re-test on the Codex install path pending on publish.

package/upgrades/side-effects/feat-hybrid-wizard.md

@@ -0,0 +1,122 @@
+# Side-effects review — Hybrid wizard
+
+Per L6. Seven dimensions.
+
+## 1. Over-block / under-block
+
+Before: UNDER for Codex-runtime users. The bareword runtime prompt
+let users pick Codex, which then spawned Codex with the wizard skill.
+Codex ignored the skill's conversational contract and executed setup
+non-interactively. Generic agent identity, no walkthrough.
+
+After: precisely targeted. instar's state machine owns the
+conversation flow; Codex is restricted per-turn to narrative-only
+generation. Claude users see zero change (they keep the existing
+SKILL.md-driven spawn). API-key Codex users keep the same auth
+posture they had before. The agentic Telegram phase still uses
+Codex with full sandbox bypass — that's the right tool for browser
+automation.
+
+## 2. Level-of-abstraction fit
+
+A new directory `src/commands/setup-wizard/` holds three files:
+- `state-machine.ts` — pure data + transition functions, no I/O.
+- `codex-driver.ts` — I/O (codex spawn, readline, CLI subcommands).
+- `model-constants.ts` — single constant import target.
+
+setup.ts adds one dispatch branch (~12 LOC). It dynamically imports
+the codex driver only when the user picks Codex, keeping the
+setup.ts module load lightweight.
+
+The state machine is intentionally a flat record of states; no
+class hierarchy, no event emitters. Drivers consume it via simple
+lookups. Adding a state is one edit.
+
+## 3. Signal vs Authority compliance
+
+- The user's runtime choice from the bareword prompt remains an
+  operator-intent SIGNAL flowing into `enabledFrameworks` and the
+  wizard dispatch.
+- The state graph's transition functions are deterministic AUTHORITIES
+  for "what state comes next" given a user answer. Codex never sees
+  the transition function and cannot influence routing.
+- `WIZARD_CODEX_MODEL` is the AUTHORITY for which Codex model the
+  narrative spawns use, drawn from the existing empirically-probed
+  availability table at `src/providers/adapters/openai-codex/models.ts`.
+- The agentic Telegram phase respects the existing AUTHORITY for
+  Telegram bot creation (BotFather / OpenAI Codex's tool access /
+  Playwright MCP).
+
+## 4. Interactions with adjacent systems
+
+- **v1.2.1 runtime prompt** (`promptForFramework`): unchanged. Still
+  reads `1`/`2`/`codex` and returns the chosen runtime.
+- **`checkFrameworkPrerequisite`**: unchanged. Still validates the
+  chosen runtime's binary is detected.
+- **`ensureSecretBackend`** (Phase 2.5): unchanged in v1.2.12. Still
+  spawns the chosen framework with `/secret-setup` for the secret
+  backend choice. A future PR can route secret-setup through the
+  state machine too, but for v1.2.12 we keep that scope bounded.
+- **Existing wizard SKILL.md**: unchanged. Still owned by the Claude
+  path; the Codex path uses it ONLY as a reference target for the
+  Telegram-agentic phase prompt.
+- **CLI subcommands the wizard calls** (`init`, `user add`, `server
+  start`, `autostart install`): unchanged. The driver calls them via
+  `execFileSync('npx', ['instar', ...])` the same way the existing
+  SKILL.md tells Claude to call them.
+- **PR #299's canary**: updated. Previously asserted every `codex exec`
+  in setup.ts carries `-m WIZARD_CODEX_MODEL`. v1.2.12 asserts setup.ts
+  no longer has codex exec spawns (they moved into codex-driver.ts),
+  setup.ts dispatches via `runCodexWizard`, and the driver's codex
+  exec spawns still carry `-m WIZARD_CODEX_MODEL`.
+
+## 5. Rollback cost
+
+Low. Three new files in a new directory plus one ~12-LOC dispatch
+branch in setup.ts. The old `codex exec` argv shape in setup.ts is
+removed; reverting reintroduces it. Claude path untouched.
+
+`git revert` restores the v1.2.11 broken-on-Codex behavior. No state
+migration; no agent-installed-files changes; no `PostUpdateMigrator`
+work needed.
+
+## 6. Backwards compatibility / drift surface
+
+Fully backwards-compatible.
+
+- Claude-runtime users: zero change.
+- Codex-runtime users: now get a working conversational wizard
+  driven by instar with Codex-generated narrative. Previously got
+  broken non-interactive setup.
+- API-key Codex users: auth posture unchanged. `CODEX_MODEL` env
+  still overrides the wizard's `-m` flag if they prefer a different
+  model.
+- No config schema change. No agent file template change. No hook
+  change.
+
+Drift surface: the state graph and per-turn narrative prompts. Both
+are flat data structures, so drift is visible in PR diffs. The
+canary covers the dispatch shape; manual review covers narrative
+prompt quality.
+
+## 7. Authorization / Trust posture
+
+No new authority. The per-turn narrative codex spawns use `-s
+read-only` (a strictly lower-privilege sandbox than the
+`--dangerously-bypass-approvals-and-sandbox` the existing wizard
+spawn uses). The Telegram-agentic phase keeps the existing sandbox-
+bypass posture so it can drive Playwright. The action states call
+`execFileSync('npx', ...)` for `init`, `user add`, `server start`,
+`autostart install` — the same CLI surface the existing wizard
+calls.
+
+No new auth, no new gate, no new privilege.
+
+## Outcome
+
+Ship. Closes the broken-on-Codex install experience that the v1.2.11
+instar-codey log surfaced. Per-framework specialization preserves
+each runtime's strengths (Claude's reliable skill-following, Codex's
+strong execution mode for agentic phases). Structure-as-guarantee
+prevents the regression class. Canary in CI guards the dispatch
+contract.