instar 0.28.18 → 0.28.20

package/.claude/skills/setup-wizard/SKILL.md

@@ -142,25 +142,37 @@ If they type something else → interpret conversationally and route.
 
 #### If gh_status="auth-needed"
 
-Walk the user through auth FIRST:
+**MANDATORY — DO THIS BEFORE ASKING FOR AN AGENT NAME.** The discovery scan ran without GitHub access. The user may already have agents backed up to GitHub from another machine. You MUST offer to sign them in BEFORE proceeding to fresh-install prompts. Skipping this step has caused users to create duplicate agents instead of restoring existing ones.
 
-> Let me check if you have agents backed up on GitHub.
-> I need to sign you into GitHub — this opens your browser.
+Say:
+> Before we set up a new agent, let me check GitHub for any agents you've backed up from another machine. I need to sign you in — it takes about 30 seconds.
 
-```bash
-gh auth login --web --git-protocol https
-```
-
-After auth, re-scan and present results.
+Then follow the **GitHub Device-Code Auth Flow** below. After auth completes, re-run discovery (call `runDiscovery` via the setup CLI or re-invoke the wizard) and present the updated agent list. Only proceed to fresh-install if discovery still shows zero agents.
 
 #### If gh_status="unavailable"
 
-Ask:
-> Have you used Instar before on another machine?
+GitHub CLI isn't installed. With instar 0.28.18+ this should be rare — the prerequisite check auto-installs gh. If you somehow get here, ask:
+> Have you used Instar before on another machine? If so, I should install GitHub CLI so I can find your existing agents before we create a new one.
 
-If yes: Show install guidance for the platform. After install → auth → scan.
+If yes: Install gh (brew/apt), then follow the **GitHub Device-Code Auth Flow** below, then re-run discovery.
 If no: Continue to fresh install.
 
+#### GitHub Device-Code Auth Flow (use this everywhere `gh auth login` is needed)
+
+**DO NOT run `gh auth login` synchronously in Bash** — it blocks waiting for the user to visit a URL and the Bash tool buffer hides the prompt. The user will see a frozen command and have no idea what to do.
+
+Instead:
+
+1. Start `gh auth login --web --git-protocol https` with `run_in_background: true`.
+2. Poll the background output every 2 seconds (BashOutput tool) until you see a line matching `! First copy your one-time code: XXXX-XXXX` and a line containing `https://github.com/login/device`.
+3. Extract the code and URL, then present them to the user conversationally — NOT as raw Bash output:
+   > To sign in, visit **https://github.com/login/device** and enter this code: **XXXX-XXXX**
+   > I'll wait here until you're done.
+4. Poll `gh auth status` every 5 seconds (foreground, fast). When it exits 0, the user has finished. Stop polling the background process and let it complete on its own.
+5. Confirm: "You're signed in as <username>. Let me check for your agents now."
+
+If 5 minutes pass with no auth completion, ask the user if they want to keep waiting or skip GitHub for now.
+
 #### Normal fresh install options
 
 **If inside a git repo:**
@@ -1909,15 +1921,7 @@ Wait for user to install, then re-check.
 gh auth status 2>&1
 ```
 
-If not authenticated, walk them through it:
-
-> I need to connect to your GitHub account. This opens your browser for a secure sign-in.
-
-```bash
-gh auth login --web --git-protocol https
-```
-
-This is an interactive command that opens the browser — run it with `stdio: 'inherit'` so the user sees the auth flow. Wait for it to complete.
+If not authenticated, use the **GitHub Device-Code Auth Flow** described in Entry Point B (above). DO NOT run `gh auth login` synchronously — it blocks the Bash tool and the user will see a frozen command. Run in background, parse the device code and URL from output, present them conversationally, and poll `gh auth status` until success.
 
 **Step 3: Create private repo**
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "0.28.18",
+  "version": "0.28.20",
   "description": "Persistent autonomy infrastructure for AI agents",
   "type": "module",
   "main": "dist/index.js",

package/upgrades/0.28.10.md

@@ -0,0 +1,19 @@
+# Upgrade Guide — v0.28.10
+
+<!-- bump: patch -->
+
+## What Changed
+
+Job gate checks now retry up to 3 times with a 5-second delay between attempts before recording a skip. Previously, a single gate failure (e.g., health check returning non-zero during a brief server restart) would immediately skip the job. This caused guardian jobs scheduled at minute 0 to consistently miss their windows when the server restarts hourly at the same time.
+
+The existing `scheduleRetry` mechanism (1min, 5min, 15min escalating retries) remains as a second layer, but the in-gate retry handles the most common case: a health endpoint that's unavailable for a few seconds during restart.
+
+## What to Tell Your User
+
+- **More reliable scheduled jobs**: "Jobs that depend on health checks are now more resilient to brief server restart windows. If you've noticed guardian or monitoring jobs being skipped, they should start running consistently now."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Gate retry on transient failure | Automatic — no configuration needed |

package/upgrades/0.28.11.md

@@ -0,0 +1,19 @@
+# Upgrade Guide — v0.28.11
+
+<!-- bump: patch -->
+
+## What Changed
+
+The GET /context endpoint now includes the `contextDir` path in its response, making it possible for agents to verify that the server is looking in the same directory where their context files live. This helps diagnose the "0 bytes for all segments" issue that occurs when there's a path mismatch between the server's configured state directory and where hooks/sessions create context files.
+
+Response format changed from an array of segments to `{ contextDir: string, segments: [...] }`.
+
+## What to Tell Your User
+
+- **Better context diagnostics**: "If your context segments ever show as empty despite files being on disk, the context endpoint now shows the exact directory path the server is checking. This makes it easy to spot path mismatches."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Context directory path in response | GET /context now returns contextDir alongside segments |

package/upgrades/0.28.13.md

@@ -0,0 +1,11 @@
+## What Changed
+
+- **Prerequisites installer now auto-installs Homebrew on macOS.** Previously, on a fresh Mac without Homebrew, the installer would bail out and tell the user to install Homebrew manually. Now it offers to install Homebrew non-interactively using the official install script, then proceeds to install tmux via `brew install tmux`.
+
+## What to Tell Your User
+
+Nothing — this is a seamless improvement to the setup experience. Users on fresh Macs will now be prompted to install Homebrew automatically instead of being told to do it themselves.
+
+## Summary of New Capabilities
+
+- `npx instar` on a fresh macOS machine now handles the full dependency chain: Homebrew -> tmux -> Claude CLI, all with interactive prompts and no manual steps required.

package/upgrades/0.28.15.md

@@ -0,0 +1,11 @@
+## What Changed
+
+- **Fixed Homebrew installer failing on admin accounts.** The previous version used NONINTERACTIVE mode which prevented the sudo password prompt, causing installation to fail even on admin accounts with a misleading "needs to be an Administrator" error. Now stdio is inherited so the user can enter their password when prompted. Timeout also increased to 10 minutes to accommodate Xcode Command Line Tools installation.
+
+## What to Tell Your User
+
+Nothing — this is a fix to the setup experience. Installing on a fresh Mac will now correctly prompt for the password instead of failing silently.
+
+## Summary of New Capabilities
+
+No new capabilities — bug fix to Homebrew auto-install from 0.28.13.

package/upgrades/0.28.20.md

@@ -0,0 +1,19 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+
+## What Changed
+
+- **Setup wizard now offers GitHub sign-in BEFORE asking for an agent name.** Previously, when GitHub CLI was installed but not authenticated (or when the discovery scan ran without GitHub access), the wizard silently moved on to "what should we call your agent?" — even if the user already had agents backed up to GitHub from another machine. Users were creating duplicates instead of restoring. The Entry Point B branches in `setup-wizard/SKILL.md` for `gh_status="auth-needed"` and `gh_status="unavailable"` are now MANDATORY blocking steps with imperative language.
+- **GitHub Device-Code Auth Flow documented.** Running `gh auth login --web --git-protocol https` synchronously inside Claude Code's Bash tool blocks on the device-code prompt and the user sees a frozen command with no instructions. The skill now instructs the agent to: run gh auth in the background, poll its output for the device code and URL, present them to the user conversationally, then poll `gh auth status` until the user completes the sign-in. Same flow is referenced from Phase 4 (cloud backup) so there's one canonical pattern.
+
+## What to Tell Your User
+
+If you're setting up a fresh machine and you've used Instar before, the wizard will now offer to sign you in to GitHub first so I can find any agents you've backed up — instead of creating a duplicate. The sign-in itself is also smoother: I'll show you the code to enter at github.com/login/device right in our chat instead of leaving you staring at a stuck terminal.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Mandatory pre-name GitHub auth offer | Automatic during setup wizard |
+| Background device-code auth flow | Automatic during setup wizard |

package/upgrades/0.28.5.md

@@ -0,0 +1,17 @@
+# Upgrade Guide — v0.28.5
+
+<!-- bump: patch -->
+
+## What Changed
+
+- **Topic cleanup no longer closes explicitly-configured topics**: The startup topic cleanup was closing forum topics for on-alert and silent jobs even when those topics were explicitly configured in jobs.json or shared with other active jobs. Now only dynamically-created topic mappings are cleaned up, and only if no other job references the same topic.
+
+## What to Tell Your User
+
+- **"Your Telegram forum topics should stay open now"**: If your user noticed that certain Telegram topics kept getting closed after server restarts, that should be resolved. The system was incorrectly treating explicitly-configured topics as stale.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Safe topic cleanup | Automatic — explicitly-configured topics are preserved on restart |

package/upgrades/0.28.7.md

@@ -0,0 +1,24 @@
+# Upgrade Guide — v0.28.7
+
+<!-- bump: patch -->
+<!-- Valid values: patch, minor, major -->
+<!-- patch = bug fixes, refactors, test additions, doc updates -->
+<!-- minor = new features, new APIs, new capabilities (backwards-compatible) -->
+<!-- major = breaking changes to existing APIs or behavior -->
+
+## What Changed
+
+Added `PATCH /config` endpoint that all FeatureDefinition enable/disable actions reference. Previously, toggling features from the dashboard (evolution, threadline, publishing, tunnel, etc.) returned 404 because the endpoint didn't exist. The new endpoint deep-merges the request body into config.json with an allowlist of safe config keys, and updates runtime config.
+
+Also includes CI test fixes from previous commits (trust wiring, quota tracking, config validation, job scheduler edge cases).
+
+## What to Tell Your User
+
+- **Dashboard feature toggles now work**: "You can now enable/disable features from the dashboard — the toggle buttons actually persist your choice."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Config patch API | `PATCH /config` with JSON body — dashboard uses this automatically |
+| Feature toggle persistence | Toggle features on/off from dashboard, changes persist to config.json |

package/upgrades/0.28.8.md

@@ -0,0 +1,21 @@
+# Upgrade Guide — v0.28.8
+
+<!-- bump: patch -->
+
+## What Changed
+
+Fixed a bug where `loadConfig()` silently dropped many optional config fields — including `safety`, `evolution`, `agentAutonomy`, `externalOperations`, `autonomyProfile`, `notifications`, `responseReview`, `inputGuard`, `dashboard`, and `moltbridge`. These fields were defined in `InstarConfig` and written to `config.json` by subsystems like `AutonomyProfileManager.applyProfileToConfig()`, but were never read back because `loadConfig()` constructed its return object with only explicitly listed properties.
+
+The fix spreads `fileConfig` as the base object before applying explicit overrides, so all config fields pass through while preserving existing defaults and transformations.
+
+**Impact**: If you had manually set `safety.level` in your config or changed autonomy profile settings, those overrides were being silently ignored — the system always fell back to profile defaults. After this update, your config file settings will be respected.
+
+## What to Tell Your User
+
+- **Config settings now fully respected**: "If you've customized safety levels, autonomy settings, or other advanced configuration, those settings are now properly loaded. Previously they could be silently ignored — that's fixed now."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Config passthrough fix | Automatic — all config.json fields now properly loaded |

package/upgrades/NEXT.md

@@ -1,35 +1,17 @@
 # Upgrade Guide — vNEXT
 
 <!-- bump: patch -->
-<!-- Valid values: patch, minor, major -->
-<!-- patch = bug fixes, refactors, test additions, doc updates -->
-<!-- minor = new features, new APIs, new capabilities (backwards-compatible) -->
-<!-- major = breaking changes to existing APIs or behavior -->
 
 ## What Changed
 
-<!-- Describe what changed technically. What new features, APIs, behavioral changes? -->
-<!-- Write this for the AGENT — they need to understand the system deeply. -->
+<!-- placeholder -->
 
 ## What to Tell Your User
 
-<!-- Write talking points the agent should relay to their user. -->
-<!-- This should be warm, conversational, user-facing — not a changelog. -->
-<!-- Focus on what THEY can now do, not internal plumbing. -->
-<!--                                                                    -->
-<!-- PROHIBITED in this section (will fail validation):                 -->
-<!--   camelCase config keys: silentReject, maxRetries, telegramNotify -->
-<!--   Inline code backtick references like silentReject: false        -->
-<!--   Fenced code blocks                                              -->
-<!--   Instructions to edit files or run commands                      -->
-<!--                                                                    -->
-<!-- CORRECT style: "I can turn that on for you" not "set X to false"  -->
-<!-- The agent relays this to their user — keep it human.              -->
-
-- **[Feature name]**: "[Brief, friendly description of what this means for the user]"
+<!-- placeholder -->
 
 ## Summary of New Capabilities
 
 | Capability | How to Use |
 |-----------|-----------|
-| [Capability] | [Endpoint, command, or "automatic"] |
+| placeholder | placeholder |