Web Choices review and persistence: practical reference

Human-in-the-loop choice workflow using the skill-local web app, optional Oracle-generated JSON, a tmux-hosted server, local and Funnel API checks, phone review, and saved submissions as durable decision state. Includes setup commands, prompts, job…

Agent Setup Prompt

Set up the web-choices HITL workflow for this project before asking for any choice or feedback.

1. Inspect `~/.agents/skills/web-choices/SKILL.md` and use the skill-local implementation at `~/.agents/skills/web-choices`. Confirm `bun`, `tmux`, `tailscale`, and `jq` are available.

2. In `~/.agents/skills/web-choices`, run `bun run build` and confirm the Bun + Vite + Svelte + mdsvex app builds successfully. Do not replace it with a generated HTML form, Markdown page, or one-off UI. Oracle-generated choices must stay JSON data, not compiled Svelte/mdsvex content.

3. From the project directory, configure runtime state:
`export WEB_CHOICES_SKILL_DIR="$HOME/.agents/skills/web-choices"`
`export HITL_OUT_DIR="$PWD/.hitl-choice"`
`export HITL_HOST="127.0.0.1"`
`export HITL_PORT="8877"`

4. Start the skill-local server in tmux:
`bun "$WEB_CHOICES_SKILL_DIR/src/cli/web-choices.ts" server --out-dir "$HITL_OUT_DIR" --host "$HITL_HOST" --port "$HITL_PORT" --tmux`

5. Confirm `$HITL_OUT_DIR/.token` exists and is non-empty. Read it as `TOKEN="$(cat "$HITL_OUT_DIR/.token")"` but do not print or paste the token except inside the final phone URL.

6. Confirm the local server is alive:
`bun "$WEB_CHOICES_SKILL_DIR/src/cli/web-choices.ts" status --out-dir "$HITL_OUT_DIR" --url "http://127.0.0.1:$HITL_PORT" --token-file "$HITL_OUT_DIR/.token"`

7. Generate the choice job as strict JSON. If project context matters, use `$oracle-packx` first and wait for Oracle to finish before continuing. Ask Oracle for a job with `jobId`, `title`, `description`, `createdAt`, and `options`; each option should include stable `id`, `title`, `description`, `tags`, `risk`, `suggestedProofCommands`, and `expectedEvidence`. Save the result as `./web-choices-job.json`.

8. Validate the JSON parses cleanly and has the expected fields. Before pushing, inspect current status. If an active job already exists, report its `jobId` and do not use `--replace` unless replacement is explicitly approved.

9. Push the validated job:
`bun "$WEB_CHOICES_SKILL_DIR/src/cli/web-choices.ts" push ./web-choices-job.json --url "http://127.0.0.1:$HITL_PORT" --token-file "$HITL_OUT_DIR/.token"`

10. Confirm the local API returns the expected job and option count:
`curl -fsS "http://127.0.0.1:$HITL_PORT/api/jobs/current?token=$TOKEN" | jq '{jobId:.jobId, optionCount:(.options | length)}'`

11. Start Tailscale Funnel only after local checks pass:
`tailscale funnel --bg --yes "$HITL_PORT"`
`tailscale funnel status`

12. Use the HTTPS hostname from `tailscale funnel status` as `PUBLIC_BASE`. Verify the tailnet URL returns the same `jobId` and option count:
`curl -fsS "$PUBLIC_BASE/api/jobs/current?token=$TOKEN" | jq '{jobId:.jobId, optionCount:(.options | length)}'`

13. Only after the local and tailnet checks match, report the phone URL as `$PUBLIC_BASE/?token=<HITL_TOKEN>`, the active `jobId`, the out dir path, and that the tmux server will stay running while drafts and submissions are saved server-side.

14. Wait locally without a timeout unless told otherwise:
`bun "$WEB_CHOICES_SKILL_DIR/src/cli/web-choices.ts" wait --job "<jobId>" --out-dir "$HITL_OUT_DIR"`

15. After submission, inspect `$HITL_OUT_DIR/submissions.jsonl` and `$HITL_OUT_DIR/submissions/<submissionId>.json`. Report the submission id, selected option ids and titles, selected count, per-option feedback, overall feedback, and the exact saved submission path. Continue only from that saved JSON file, not chat memory.

16. Privacy and safety expectations: do not expose sensitive choices through Funnel without explicit approval. Treat the token as a short-lived gate, not full authentication. Do not paste secrets, cookies, private endpoints, API keys, raw config dumps, or full environment output into the job. Do not commit `.hitl-choice`, `.token`, drafts, or submissions unless explicitly asked and reviewed.

17. Cleanup expectations: leave the tmux server running while review is active. When finished or asked to clean up, report what is still running, stop Funnel, stop the tmux server if appropriate, and preserve `$HITL_OUT_DIR/current-job.json`, `drafts/`, `submissions.jsonl`, and `submissions/<submissionId>.json` as durable decision state.

18. If something fails, preserve state first. For tunnel issues, keep the same server, job, and token, restart Funnel, and recheck the public API. For server issues, inspect `$HITL_OUT_DIR` before restarting with the same out dir. If submission seems stuck, check `submissions.jsonl`, `submissions/`, server logs, and `http://127.0.0.1:$HITL_PORT/api/jobs/<jobId>/submissions/status?token=$TOKEN`.

Big Idea

Use $web-choices when the agent can generate useful options, but the next move needs an intentional pick, ranking, or written feedback before implementation continues.

The workflow turns agent-generated choices into a small Svelte/mdsvex web app, serves it from the local machine, opens it through Tailscale Funnel, waits while a phone or browser submits a decision, then resumes from saved JSON.

This is especially useful when the agent is running unattended and a quick phone review is enough to unblock it.

Skill Reference Or Files To Inspect

  • skills/web-choices/SKILL.md
  • common local install: ~/.agents/skills/web-choices
  • runtime state folder: $PWD/.hitl-choice

The skill-local app owns the UI. Project work should provide the context, generated choices, and follow-up action.

When To Reach For This

Use it when:

  • several implementation strategies are plausible and one needs a human pick
  • a generated variation matrix needs selection, rejection, or comments
  • a risky refactor needs a short approval checkpoint before edits
  • a design or CLI UX direction needs ranking before coding
  • phone review is faster than switching back to the development machine

Good software-project choice sets:

  • billing webhook idempotency strategies
  • auth/session rotation designs
  • cache invalidation plans
  • migration sequencing options
  • CLI command naming and help text variants
  • retry/fallback policies for model outages

How This Used To Work

The agent would usually paste a numbered list in chat and wait. That works for tiny decisions, but it is easy to lose context, hard to review on a phone, and awkward when feedback belongs on individual options.

With $web-choices, the choice state is durable:

  • the current job is JSON
  • drafts are saved server-side
  • submissions are appended
  • the agent resumes from the saved submission file

The Mental Model

generate options -> serve a choice UI -> open phone URL -> wait -> read saved JSON -> continue

The agent is not guessing from chat memory. It should inspect the submitted JSON and treat that file as the next instruction packet.

Oracle Pairing

Pair $oracle-packx with $web-choices when choices should be grounded in repo context.

Ask Oracle for strict JSON:

Use $oracle-packx to inspect the relevant code and produce a strict JSON web-choices job.
Generate 6-10 concrete options for solving the billing webhook double-processing issue.
Each option should include id, title, description, tags, risk, suggestedProofCommands, and expectedEvidence.
Do not implement yet. After the job is served through $web-choices, wait for my saved choice and feedback.

Oracle generation is blocking. The agent should wait for Oracle to finish, read the local Oracle output, validate the JSON shape, then push the job into Web Choices.

If the selected option fails later, ask Oracle again with a Prior-State Ledger that includes the selected option, the failure, logs, proof commands, and what has already been tried.

Command Shape

Start the skill-local server from any project:

export WEB_CHOICES_SKILL_DIR="$HOME/.agents/skills/web-choices"
export HITL_OUT_DIR="$PWD/.hitl-choice"
export HITL_HOST="127.0.0.1"
export HITL_PORT="8877"

bun "$WEB_CHOICES_SKILL_DIR/src/cli/web-choices.ts" server \
  --out-dir "$HITL_OUT_DIR" \
  --host "$HITL_HOST" \
  --port "$HITL_PORT" \
  --tmux

The server writes or reuses a token:

TOKEN="$(cat "$HITL_OUT_DIR/.token")"

Confirm the local server is alive:

bun "$WEB_CHOICES_SKILL_DIR/src/cli/web-choices.ts" status \
  --out-dir "$HITL_OUT_DIR" \
  --url "http://127.0.0.1:$HITL_PORT" \
  --token-file "$HITL_OUT_DIR/.token"

Push a generated job:

bun "$WEB_CHOICES_SKILL_DIR/src/cli/web-choices.ts" push ./web-choices-job.json \
  --url "http://127.0.0.1:$HITL_PORT" \
  --token-file "$HITL_OUT_DIR/.token"

Use --replace only after checking the active job and confirming replacement is intentional.

Phone Workflow

Start Tailscale Funnel for the local port:

tailscale funnel --bg --yes "$HITL_PORT"
tailscale funnel status

Use the Funnel hostname reported by tailscale funnel status:

PUBLIC_BASE="https://<your-tailnet-host>.ts.net"
curl -fsS "$PUBLIC_BASE/api/jobs/current?token=$TOKEN" \
  | jq '{jobId:.jobId, optionCount:(.options | length)}'

Share the phone URL only after the public API returns the expected job and option count:

https://<your-tailnet-host>.ts.net/?token=<HITL_TOKEN>

Keep the tmux server running while the phone page is open. Tailscale Funnel makes the local UI reachable, but the development machine and Tailscale connection still need to stay online.

Wait And Resume

Wait locally:

bun "$WEB_CHOICES_SKILL_DIR/src/cli/web-choices.ts" wait \
  --job "<jobId>" \
  --out-dir "$HITL_OUT_DIR"

After submission, inspect and summarize:

  • submission id
  • selected option ids and titles
  • per-option feedback
  • overall feedback
  • saved submission path

Then continue from the saved JSON file.

Durable State Files

File Purpose
$HITL_OUT_DIR/current-job.json active choice job
$HITL_OUT_DIR/drafts/ server-side in-progress feedback
$HITL_OUT_DIR/submissions.jsonl append-only submission log
$HITL_OUT_DIR/submissions/<submissionId>.json exact submitted decision packet

Ask The Agent This

Use $oracle-packx and $web-choices.
Pack the relevant auth/session code and generate a strict JSON choice job with 8 options for the refresh-token rotation strategy.
Serve the choices with the bundled Web Choices skill, expose it through Tailscale Funnel, give me the phone URL, and wait for my saved submission.
After I submit, read the saved submission JSON and continue only with the selected direction and feedback.
Use $web-choices for this CLI UX decision.
Generate 6 command naming options, serve them through the phone-friendly choice UI, and wait for my saved choice before editing code.
Use $web-choices as a review checkpoint.
Turn the three migration plans into selectable options with risk and proof commands.
Give me a Tailscale URL, wait for feedback, then resume from the saved submission JSON.

What To Confirm / How To Know It Worked

  • bun run build passes in the Web Choices skill directory
  • the server is running in tmux
  • $HITL_OUT_DIR/.token exists
  • the local API returns the expected jobId
  • the Tailscale URL returns the same jobId and option count
  • the phone page can select options, save drafts, and submit
  • submissions.jsonl and submissions/<submissionId>.json exist after submission
  • the agent reports the saved JSON path before continuing

If It Goes Wrong

If the tunnel fails, keep the same server, job, and token when possible. Restart Funnel, check tailscale funnel status, then retry the public API check.

If the server dies, inspect $HITL_OUT_DIR first. Restart with the same out dir and verify current-job.json, drafts, and submissions are still present.

If the phone says submitted but the wait command has not returned, inspect submissions.jsonl, submissions/, server logs, and:

curl -fsS "http://127.0.0.1:$HITL_PORT/api/jobs/<jobId>/submissions/status?token=$TOKEN"

If the choices are sensitive, do not expose them through Funnel without an explicit approval. The token is a gate, not a full authentication system.

References And Resources

  • skills/web-choices/SKILL.md
  • skills/oracle-packx/SKILL.md
  • Tailscale Funnel status and hostname from tailscale funnel status

Source references