Benchflow Traj Upload

Submit a trajectory

The human copied a line into this chat so you would do the work. They should not run BenchFlow commands. You find a local session, open the viewer, wait until they like it, then you upload.

Do not print broker URLs, Azure blob URLs, or a "run this yourself" command. Those leak private inbox paths and turn a paste-to-agent flow back into a CLI.

For operating, testing, or debugging the upload pipeline itself (dry runs, manifests, promotion checks), use benchflow-traj-upload-ops instead.

Workflow

1. setup     → ensure the latest benchflow is installed
2. discover  → list recent local Claude / Codex / trial sessions
3. pick      → user chooses one (or confirms your recommendation)
4. view      → open the viewer with --confirm and give them the localhost URL
5. confirm   → wait for the Approve button (or their chat reply)
6. submit    → you upload; report Submitted / Already submitted + digest
7. persist   → if this repo has no local copy of this skill, write one

Step 1 — Setup

Always make sure the latest BenchFlow is installed before anything else — bench traj setup and the session-JSONL viewer only exist in 0.7.1+:

uv tool install --python 3.12 --upgrade benchflow

If uv reports Executables already exist, rerun with --force. Verify that bench --version reports at least 0.7.1. If the installed CLI lacks bench traj setup or cannot open a session JSONL in the viewer, upgrade first rather than working around it.

Step 2 — Discover

Prefer the listing the CLI already knows how to make:

bench traj setup --list

If that command is missing, search these locations and skip nested subagents/ files unless the user asks:

• Claude Code: ~/.claude/projects/**/*.jsonl
• Codex: ~/.codex/sessions/**/*.jsonl and ~/.codex/archived_sessions/*.jsonl
• Cursor: agent transcripts at ~/.cursor/projects/*/agent-transcripts/**/*.jsonl
• OpenCode: newer versions keep sessions in a SQLite database at ~/.local/share/opencode/opencode.db (run opencode db path to confirm); older versions used JSON files under ~/.local/share/opencode/storage/session/
• BenchFlow trials: jobs/**/trajectory/ or a directory with turn*.txt

If the user described a time window or topic (for example, sessions from the last 72 hours on a specific project), prefer sessions matching that description.

Show the 8 most recent with mtime, path, and the first user-prompt snippet. Skip sessions that clearly contain private or proprietary work unless the user names them. If the user already named a file or folder, skip discovery.

Step 3 — Pick

Recommend one. Ask which to open if more than one is plausible. Do not upload yet — the viewer is how they decide the session is the one they meant.

Step 4 — View

First stage a dry run so you can show the user what upload-time redaction would mask for them (nothing is uploaded):

bench traj upload /path/to/session.jsonl --dry-run

Its output ends with a plain Masked for you: ... line (for example Masked for you: 2 API keys, 1 bearer token, or Masked for you: nothing — no secrets detected). Extract the text after Masked for you: — call it the masking summary.

Then open the viewer with the in-page confirm bar and tell the user the URL, passing the masking summary so it renders next to the Approve button:

bench eval view /path/to/session.jsonl --confirm --port 8889 \
  --redaction-summary "2 API keys, 1 bearer token"

The viewer shows the ORIGINAL session (it does not redact); the --redaction-summary note tells the reviewer what the upload step will mask. If the installed CLI rejects --redaction-summary (older than 0.7.2), drop the flag and state the masking summary in chat instead.

That path may also be a trial directory. If the port is taken, pick another.

With --confirm the page shows an Approve & submit / Not this one bar. When the user clicks, the server prints one line to stdout — DECISION: approved or DECISION: rejected — and exits (exit code 0 on approve, 3 on reject). Run the command so you can wait on that output: either start it in the background and poll its output for the DECISION: line, or run it blocking with a generous timeout.

If the installed CLI predates --confirm (bench --version below 0.7.2), run the plain bench eval view /path/to/session.jsonl in the background instead and rely on the chat confirmation in Step 5.

Step 5 — Confirm

Ask them to review the page and click a button in the viewer:

• DECISION: approved (exit 0) → they approved; proceed to Step 6.
• DECISION: rejected (exit 3) → they want a different session; go back to pick.
• If they answer in chat before clicking anything, kill the viewer process and honor the chat answer.
• Without --confirm (older CLI), wait until they say in chat that it looks good.

Do not upload until one of those signals says the session is right.

The upload is tagged with the repository the session was about: the CLI reads the session's recorded working directory (only the session's own cwd — never the directory you run the upload from), resolves its git origin remote, and stores repo/<owner>/<name> as the source id (it prints Repo: owner/name (from session cwd /path; use --no-repo to omit) — the local path is terminal output only; run --dry-run to see the tag beforehand). Sessions recorded outside a git repo upload untagged. Mention the detected repo when you ask for confirmation — "This session will be tagged repo/owner/name; say the word if you want it omitted" — so they can opt out for private repos.

Before upload, remind them not to submit secrets, and repeat the masking summary from the Step 4 dry run when asking for approval — "Before upload, BenchFlow masks: 2 API keys, 1 bearer token; originals never leave this machine" — so they know exactly what redaction handles for them. The CLI masks detected secret values locally before anything leaves the machine (the server independently rescans and rejects any survivor), but redaction is a safety net, not a license to upload credentials.

Step 6 — Submit

You run the upload. The CLI infers GitHub username and email from gh / git; when identity resolves, the upload runs without prompts. If inference fails, ask for both in chat and pass --github-id / --email. Do not tell the user to re-run a command.

bench traj upload /path/to/session.jsonl

If the user declined the repo tag in the confirm step, add --no-repo.

If the first request times out, run the same upload again. Retries are safe because the digest is content-addressed. Report Submitted or Already submitted, plus the digest.

Step 7 — Persist the recipe

If this project does not already have .agents/skills/benchflow-traj-upload/SKILL.md (or a .claude/skills / .codex/skills copy), write this skill there so the next agent does not rediscover the loop. Do not overwrite a newer local copy.