instar 0.9.47 → 0.9.49

package/.claude/skills/secret-setup/skill.md

@@ -0,0 +1,182 @@
+---
+name: secret-setup
+description: Focused micro-skill for secret management setup. Explains options, guides through Bitwarden installation/login/unlock, configures backend. Exits when done.
+---
+
+# Secret Management Setup
+
+You are guiding a user through choosing and configuring how their Instar agent stores secrets (API tokens, bot credentials, etc). This is a **focused conversation** — your ONLY job is to get secret management configured, then exit.
+
+## CRITICAL RULES
+
+### 1. No Interactive CLI Commands — WILL HANG FOREVER
+
+**Claude Code's Bash tool CANNOT handle stdin prompts.** Any command that asks for a password, confirmation, or any input will hang until timeout. There is NO workaround — you cannot type into a running command.
+
+**UNDERSTAND THIS ABOUT `--raw`:** The `--raw` flag ONLY changes the output format. It does NOT prevent interactive prompts. `bw unlock --raw` STILL prompts for a password and WILL HANG. The password must ALWAYS be passed as a POSITIONAL ARGUMENT before any flags.
+
+**Commands that WILL HANG (never run these):**
+```
+bw unlock --raw                    # HANGS — no password argument
+bw unlock                          # HANGS — prompts for password
+bw login --raw                     # HANGS — no email/password
+bw login                           # HANGS — prompts for credentials
+echo "text" && bw unlock --raw     # HANGS — bw still prompts
+read -s VARIABLE                   # HANGS — waits for hidden input
+```
+
+**Commands that WORK (use ONLY these patterns):**
+```
+bw unlock "ACTUAL_PASSWORD_HERE" --raw    # Returns session key immediately
+bw login "EMAIL" "PASSWORD" --raw         # Returns session key immediately
+bw status --raw                           # Returns JSON, never prompts
+which bw 2>/dev/null                      # Checks if installed, never prompts
+bw --version                              # Returns version, never prompts
+```
+
+**THE RULE:** You MUST have the user's password as text BEFORE running any unlock/login command. Ask the user, get their answer, THEN construct the command with their password as a positional argument.
+
+### 2. No Multi-Choice for Text Input
+
+AskUserQuestion multi-choice is for DECISIONS (pick A or B or C).
+NEVER use it to collect free-text input (passwords, emails, tokens).
+When you need text, ask a plain question and wait for the user's response.
+
+### 3. No Assumptions About What's Stored
+
+Do NOT assume the user has any specific credentials in Bitwarden. They might have Bitwarden but have never stored anything in it for Instar. Only check what's actually there — never tell the user "I need to restore your Telegram token" unless you've confirmed it exists.
+
+### 4. Terminal Display Rules
+Keep text short. 2-3 sentences max per paragraph. No sentences over ~100 characters.
+
+### 5. No Commands in User-Facing Text
+Never show CLI commands to the user. You run everything. The user's only job is answering your questions.
+
+## The Conversation Flow
+
+### Step 1: Introduce Secret Management
+
+Start with a brief, friendly explanation:
+
+> Your agent will need to store sensitive things — like API tokens and bot credentials.
+>
+> I'd recommend setting up a password manager so these are backed up securely. That way if you ever reinstall or move to a new machine, everything restores automatically.
+
+Then present the choice via AskUserQuestion (this IS a decision — multi-choice is correct here):
+
+1. **"Bitwarden (Recommended)"** — Description: "Free, open-source password manager. Secrets sync across machines and survive reinstalls."
+2. **"Local encrypted store"** — Description: "AES-256 encrypted on this machine. Good if you only use one computer."
+3. **"I'll manage secrets manually"** — Description: "You'll paste tokens each time. Not recommended."
+
+### Step 2: Handle the Choice
+
+#### If Bitwarden:
+
+**Step 2a: Check if `bw` CLI is installed:**
+```bash
+which bw 2>/dev/null && bw --version 2>/dev/null
+```
+
+**If NOT installed — install it yourself:**
+Tell the user: "Let me install the Bitwarden CLI for you."
+```bash
+npm install -g @bitwarden/cli
+```
+If that fails, try `brew install bitwarden-cli` on macOS.
+If installation fails entirely, fall back to local encrypted store and exit.
+
+**Step 2b: Check vault status:**
+```bash
+bw status --raw 2>/dev/null
+```
+Parse the JSON response. Three possible `status` values:
+
+- **`"unlocked"`** — Already good! Skip to Step 2d.
+- **`"locked"`** — Need master password. Go to Step 2c.
+- **`"unauthenticated"`** — Need email + password login. Go to Step 2c.
+
+**Step 2c: Get credentials from user and unlock:**
+
+If unauthenticated, ask TWO separate questions:
+1. "What email address do you use for Bitwarden?" (wait for response)
+2. "What's your Bitwarden master password?" (wait for response)
+
+Then run (substituting THEIR ACTUAL ANSWERS):
+```bash
+BW_SESSION=$(bw login "user@example.com" "their_actual_password" --raw 2>&1)
+echo "RESULT:$BW_SESSION"
+```
+
+If locked (already logged in), ask ONE question:
+1. "What's your Bitwarden master password?" (wait for response)
+
+Then run (substituting THEIR ACTUAL ANSWER):
+```bash
+BW_SESSION=$(bw unlock "their_actual_password" --raw 2>&1)
+echo "RESULT:$BW_SESSION"
+```
+
+**CHECK THE RESULT:** If `BW_SESSION` is empty or contains "Invalid" or "error":
+> "That didn't work — the password might be wrong. Want to try again?"
+
+Allow up to 3 retries. After 3 failures, offer to fall back to local store.
+
+**Step 2d: Verify and save session:**
+```bash
+export BW_SESSION="the_session_key_from_above"
+bw sync --session "$BW_SESSION" 2>/dev/null
+```
+
+Save the session for the main wizard to pick up:
+```bash
+mkdir -p "$HOME/.instar/secrets"
+echo "$BW_SESSION" > "$HOME/.instar/secrets/.bw-session"
+chmod 600 "$HOME/.instar/secrets/.bw-session"
+```
+
+Tell the user:
+> "Bitwarden is unlocked and ready. Your agent's secrets will be stored securely."
+
+**Step 2e: Check for existing Instar secrets (optional, don't assume):**
+```bash
+bw list items --search "instar" --session "$BW_SESSION" --raw 2>/dev/null
+```
+
+If results are found, tell the user what's available. If nothing is found, that's fine — just move on. Do NOT say "I couldn't find your Telegram credentials" — they might not have any.
+
+#### If Local Encrypted Store:
+
+No user interaction needed. Tell the user:
+> "Local encrypted store is ready. Your secrets are AES-256 encrypted on this machine."
+
+#### If Manual:
+
+Tell the user:
+> "Got it. You'll paste tokens when prompted during setup."
+
+### Step 3: Save Backend and Exit
+
+Write the backend preference:
+```bash
+mkdir -p "$HOME/.instar/secrets"
+cat > "$HOME/.instar/secrets/backend.json" << 'JSONEOF'
+{"backend":"CHOSEN_BACKEND","configuredAt":"CURRENT_ISO_DATE"}
+JSONEOF
+```
+
+Verify it was saved:
+```bash
+cat "$HOME/.instar/secrets/backend.json"
+```
+
+Tell the user this step is done and the main setup will continue automatically.
+
+**Then exit.** Do not continue into other setup phases. Your job is done.
+
+## Edge Cases
+
+- **"What is Bitwarden?"** — Free, open-source password manager. End-to-end encrypted. Widely trusted. Bitwarden can't read your secrets.
+- **"I use 1Password/LastPass"** — Instar specifically integrates with the Bitwarden CLI. Offer local encrypted store as alternative.
+- **"Skip everything"** — Allow it, but note they'll paste tokens manually each reinstall.
+- **`bw` command times out** — Retry once. If still failing, offer local fallback.
+- **Two-factor auth** — If login returns a 2FA error, ask the user for their authenticator code, then: `bw login "EMAIL" "PASSWORD" --method 0 --code "CODE" --raw`

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

@@ -602,83 +602,21 @@ Or for short messages:
 Strip the `[telegram:N]` prefix before interpreting the message. Respond naturally, then relay. Only relay your conversational text — not tool output or internal reasoning.
 ```
 
-## Phase 2.5: Secret Management — Protecting Credentials
+## Phase 2.5: Secret Management — HANDLED BY SETUP.TS
 
-**Before Telegram setup**, configure how the agent stores sensitive data. This determines whether Telegram tokens (and other secrets) survive agent deletion and reinstall.
+**DO NOT handle secret management here.** The setup launcher runs a dedicated `/secret-setup` micro-session BEFORE this wizard starts. By the time you're reading this, `~/.instar/secrets/backend.json` already exists.
 
-### Why This Comes Before Telegram
+Check the prompt context for `SECRET_BACKEND_CONFIGURED`. If present:
+- Secret management is DONE — do not re-configure it
+- Do not attempt to unlock Bitwarden — the micro-session already handled that
+- Do not prompt the user about secret storage options
+- If `BW_SESSION is available` appears in context, Bitwarden is already unlocked and the env var is set
 
-When a user reinstalls an agent, the Telegram bot token and chat ID are the hardest things to recover. If we set up secret management FIRST, we can:
-1. Auto-restore Telegram credentials on reinstall (no re-setup needed)
-2. Back up tokens before nuke (transparent to user)
-3. Share credentials across machines (via Bitwarden)
+**If `SECRET_BACKEND_CONFIGURED` is NOT in context** (edge case — user ran the wizard directly), check `~/.instar/secrets/backend.json`. If it exists, skip this phase. If it truly doesn't exist, tell the user to run `npx instar` which will handle secret setup properly.
 
-### Step 2.5a: Check for Existing Secret Backend
+**Credential restoration**: If the backend is Bitwarden and BW_SESSION is available, you MAY check for existing credentials. But do NOT assume any specific credentials exist — check first, then only mention what you actually find. Never say "I need to restore your Telegram token" unless you've confirmed it's there.
 
-First, check if this agent already has a secret backend configured:
-
-```bash
-# Check if backend preference exists
-cat "$HOME/.instar/secrets/backend.json" 2>/dev/null
-```
-
-If a preference exists and it's not `manual`, tell the user and move on:
-> "Your secrets are backed up using [Bitwarden / local encrypted store]. Any saved credentials will be auto-restored."
-
-Then try to restore Telegram credentials:
-```javascript
-import { SecretManager } from 'instar';
-const mgr = new SecretManager({ agentName: '<name>' });
-mgr.initialize();
-const telegram = mgr.restoreTelegramConfig();
-// If telegram is not null, we have token + chatId
-```
-
-If Telegram credentials are restored and valid (verify with `getMe` API call), **skip Phase 3 entirely** and tell the user:
-> "Telegram credentials restored and validated! Bot @[username] is ready."
-
-### Step 2.5b: Configure Secret Backend (Fresh Install)
-
-If no preference exists, present the choice conversationally:
-
-> **How should your agent store sensitive data?**
->
-> Things like Telegram tokens and auth keys need to be stored securely. This choice persists across reinstalls.
-
-Present these options via AskUserQuestion:
-
-1. **"Bitwarden (Recommended)"** — Description: "Cross-machine. Cloud-backed. Install any agent on any machine with just your master password."
-2. **"Local encrypted store"** — Description: "AES-256 encrypted on this machine. macOS Keychain for password-free access. Survives reinstalls."
-3. **"I'll manage secrets manually"** — Description: "You'll paste tokens each time you install."
-
-**If Bitwarden selected:**
-```bash
-# Check if bw CLI is available
-which bw 2>/dev/null
-```
-If not available, tell them how to install it and fall back to local:
-> "Bitwarden CLI isn't installed yet. You can set it up later. For now, I'll use the local encrypted store."
-
-**If Local selected (or Bitwarden fallback):**
-The local store auto-initializes using macOS Keychain (no password needed) or a machine-derived key. No user interaction required — just initialize it silently:
-```javascript
-const mgr = new SecretManager({ agentName: '<name>', backend: 'local' });
-mgr.initialize();
-```
-Tell the user:
-> "Local encrypted store initialized. Your secrets are AES-256 encrypted and will survive reinstalls."
-
-**If Manual selected:**
-> "Got it. You'll need to provide tokens manually during setup and after reinstalls."
-
-### Step 2.5c: Save Backend Preference
-
-Write the backend preference so it persists:
-```javascript
-mgr.configureBackend(chosenBackend);
-```
-
-This saves to `~/.instar/secrets/backend.json` — it survives agent deletion since it's outside the agent directory.
+**CRITICAL — No Interactive CLI Commands**: If you ever need to run `bw` commands, the password MUST be a positional argument: `bw unlock "PASSWORD" --raw`. The `--raw` flag does NOT prevent interactive prompts — it only changes output format. `bw unlock --raw` WILL HANG FOREVER.
 
 ---
 

package/dist/scaffold/templates.js

@@ -537,7 +537,7 @@ I run with \`--dangerously-skip-permissions\` — meaning I have full access to
 
 **"Present Options"** — If I know the next steps, they're not suggestions — they're my job.
 
-**"Interactive CLI Commands"** — Claude Code's Bash tool CANNOT handle commands that wait for stdin. Commands like \`bw unlock\` (no args), \`read -s\`, \`npm init\` (interactive), or any tool with password/confirmation prompts will HANG FOREVER. Always use non-interactive equivalents: pass arguments directly, use \`--raw\`, \`--yes\`, \`-y\`, \`--non-interactive\` flags. Collect user input via conversation FIRST, then pass it as command arguments.
+**"Interactive CLI Commands"** — Claude Code's Bash tool CANNOT handle stdin prompts. Any command that waits for input HANGS FOREVER. IMPORTANT: the \`--raw\` flag does NOT prevent prompts — it only changes output format. \`bw unlock --raw\` STILL HANGS because it still prompts for a password. The password must be a POSITIONAL ARGUMENT: \`bw unlock "PASSWORD" --raw\`. Same for all CLI tools: collect input from the user via conversation FIRST, then pass it as arguments to the command. Never run a command hoping it will prompt the user.
 
 **"Multi-Choice for Text Input"** — AskUserQuestion multi-choice is for DECISIONS (pick A or B). Never use it to collect free-text input (passwords, emails, tokens). It makes "Skip" look like the default and buries the actual input. Ask a plain question and wait instead.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "0.9.47",
+  "version": "0.9.49",
   "description": "Persistent autonomy infrastructure for AI agents",
   "type": "module",
   "main": "dist/index.js",
@@ -51,7 +51,8 @@
     "dashboard",
     "upgrades",
     "src/templates",
-    ".claude/skills/setup-wizard"
+    ".claude/skills/setup-wizard",
+    ".claude/skills/secret-setup"
   ],
   "license": "MIT",
   "engines": {