2618f0d244
Track each active run's resolved workspace alongside its cancel function in a single runner.active struct map. A new request key is now refused only when an already-active run is changing the same resolved workspace; the refusal names the conflicting run id and advises waiting or using a different workspace. Workspace resolution is unchanged (default cwd, absolute request workspace, EvalSymlinks), so two spellings of one directory still compare equal. The conflict check and registration stay inside the existing r.mu critical section, so concurrent starts for one workspace cannot both pass. Idempotent repeats of an active request key and the restart-recovery guard are unchanged. Add concurrency_test.go covering concurrent different-workspace runs, same-workspace refusal, symlink/default-cwd equivalence, idempotent repeats, restart recovery and retry workspace scoping; strengthen the runner_test.go refusal assertion. Update docs/cli.md, docs/first-version-testing.md and the packaged operations skill reference to describe per-workspace concurrency. Assisted-by: DeepSeek V4.1 Flash
152 lines
8.6 KiB
Markdown
152 lines
8.6 KiB
Markdown
# First-version tester walkthrough
|
|
|
|
Pipelines is a **single-user preview**, like other personal terminal tools—not a
|
|
multi-user service. The goal is useful, supervised workflows with inspectable
|
|
history. It is not a guarantee that a model completes every task correctly.
|
|
|
|
## Before installing
|
|
|
|
- Use a Git checkout (including `.git`) so Docker setup can stamp its build identity.
|
|
- **Native host installation is the default** (`./install`/`--native`); the
|
|
[Docker installation](install.md) is explicit with `./install --docker` and needs
|
|
Docker Compose and Python 3. Docker setup builds the Go CLI/TUI clients on the host
|
|
only when Go 1.27+ is available.
|
|
- Docker setup starts services, asks for ntfy passwords, opens provider sign-in,
|
|
and then saves **two separate model defaults** (the interactive harness model and
|
|
the new-pipeline model) in two fuzzy pickers. Signing in to a provider is
|
|
separate from those saved defaults. Setup makes a small billable
|
|
provider-validation call and sends a setup alert. Docker provider sign-in is
|
|
separate from your host OpenCode login. Reopen login or the saved defaults later
|
|
with `./install --opencode` or `./install --pi`.
|
|
- Start with a **disposable repository with no valuable files or secrets**. Stage
|
|
tools can read/edit files and execute commands. Permissions and snapshots are not
|
|
an OS sandbox; an automatically mounted home directory is not isolation.
|
|
- The Pipelines API is unauthenticated. Use your own machine/trusted network only;
|
|
do not expose it to the Internet. No multi-user setup is required.
|
|
|
|
## Install and identify the build
|
|
|
|
From the checkout, run `./install` for the native host installation, or
|
|
`./install --docker` for the Docker server + ntfy installation, then restart any
|
|
existing TUI. The installer requires a Git checkout; a standalone source archive
|
|
cannot self-install.
|
|
Follow [installation](install.md) for PATH and provider setup.
|
|
Do not start a native server alongside your Docker server.
|
|
|
|
Host Go is **optional** and only needed for native host CLI/TUI binaries. Without
|
|
host Go you can still run the Docker-contained TUI/CLI against the running server.
|
|
Run Compose from the checkout with `--project-directory` (so it finds
|
|
`compose.yaml`) and `--workdir "$PWD"` (so the container keeps the actual
|
|
disposable workspace):
|
|
|
|
```sh
|
|
# TUI (allocate a TTY)
|
|
docker compose --project-directory /absolute/path/to/pipelines exec --workdir "$PWD" pipelines pipelines
|
|
# Plain CLI command (no TTY)
|
|
docker compose --project-directory /absolute/path/to/pipelines exec -T --workdir "$PWD" pipelines pipelines <command>
|
|
```
|
|
|
|
Any host client targets the mapped host port with
|
|
`--url ws://127.0.0.1:<actual-mapped-port>/connect`, reading the port from
|
|
`docker compose --project-directory /absolute/path/to/pipelines port pipelines 8080`.
|
|
The server listens on container port **8080**; only the default host mapping is
|
|
**8081**. Prefer the installer-saved configured endpoint when present; never
|
|
replace it with a guessed default.
|
|
Configuration, provider credentials, drafts, run history and ntfy data live in
|
|
Docker volumes and are reused across reinstalls/reconfigures; the visible flow
|
|
remains draft → validate → explicit publish → run → inspect. Developer/legacy
|
|
native-server instructions stay in the [installation guide](install.md) rather
|
|
than competing with first use.
|
|
|
|
```sh
|
|
pipelines version --json
|
|
pipelines ping --json
|
|
pipelines status --json
|
|
```
|
|
|
|
`version` identifies the client; `pong.build` identifies the running server.
|
|
The full commit is the primary identity. `-dirty` means uncommitted source was
|
|
included; two dirty builds at the same commit need not contain the same changes.
|
|
Missing `build`, `commit: "unknown"` or `dirty: null` is not an identifiable release.
|
|
Capture this information before reporting issues. `--url` and `PIPELINES_URL`
|
|
override the saved endpoint; check that you are connected to the intended server.
|
|
|
|
## First supervised run
|
|
|
|
1. Create a disposable repository, then launch `pipelines` **from that directory**.
|
|
Docker must see the same absolute path; repositories on another computer are
|
|
not uploaded automatically.
|
|
2. Use `:templates` and create the **summary** starter. Review its name and publish
|
|
explicitly. A fresh database is empty; templates are never auto-published.
|
|
3. Open the pipeline and use `:run` with a small task, such as summarizing a short
|
|
passage included in the task itself. Review the execution confirmation.
|
|
4. Read the retained report and recorded visits. For an editing workflow, inspect
|
|
File changes as well as actual file contents and any verification commands.
|
|
Model-written claims alone are not verification.
|
|
5. Create/edit a draft with `:new` or `:drafts`; validate it, then choose whether to
|
|
publish. Editing alone must not change the published definition.
|
|
6. Optionally exercise `:export` and `:import`. Identical definitions skip; differing
|
|
existing names offer keep existing, keep both, or use imported as a new version.
|
|
7. Quit with `:quit`; `q` intentionally does not quit. Reopen to inspect history.
|
|
|
|
Phone reception is a separate manual check. Install/subscribe in the ntfy app and
|
|
confirm receipt before depending on it. The installer confirms publishing, not
|
|
delivery to your phone. A summary starter does not send alerts automatically.
|
|
|
|
## Known boundaries
|
|
|
|
- Sequential stages within a run; no parallel branches or built-in
|
|
human-approval stages. Independent runs in different workspaces do execute
|
|
concurrently.
|
|
- Cancellation/retry is **not rollback**. Retry starts from the entry stage with
|
|
fresh sessions and the pinned definition; earlier side effects can repeat.
|
|
- Diffs are bounded stage-start/stage-end observations, not full backups or proof
|
|
of exclusive authorship. Partial/missing captures must not mean “no edits.”
|
|
- ZIP bundles transfer definitions only. They do not back up history, drafts,
|
|
repositories, OpenCode credentials/sessions or ntfy storage. Preserve persistent
|
|
volumes/data; never use `docker compose down -v` as a routine reset/update.
|
|
- Token/USD budgets use reported usage and may overshoot in-flight. Prefer provider
|
|
account spending limits too; do not interpret these as a guaranteed bill ceiling.
|
|
- Live reference evidence is dated and narrow. An existing real run7
|
|
(2026-10-11) executed both configured harnesses, OpenCode 2.0.26 and Pi 1.1.0,
|
|
with `opencode-go/deepseek-v4.1-flash` stages, and both steps succeeded
|
|
(retained captures under `tmp/friend-ui-verification`); a current-source TUI
|
|
inspection of that run recorded actual 80x30 and 120x36 renderings. The earlier
|
|
[2026-10-10 OpenCode v2.0.20 trial](reference-workflow-results.md) remains the
|
|
previous dated evidence. The dated 2026-10-11 final install then completed the
|
|
new-source installer and installed-authoring verification: the runtime was
|
|
actually installed and used, with run17 executing both real harness stages (see
|
|
[installation verification](installation-verification.md)). Other providers, real
|
|
outages/long-stream interruption, fresh OAuth and phone delivery are still
|
|
pending and are not established by these runs. See
|
|
[dated results](reference-workflow-results.md), not just test pass counts.
|
|
- Windows-native installation, screen-reader accessibility and every Linux/macOS
|
|
terminal combination are not tested. This is not a stability promise for all hosts.
|
|
|
|
## Report a useful problem
|
|
|
|
Include client `version --json`, server `ping --json`, OS/architecture, install mode,
|
|
the exact command or key sequence, expected/actual behavior, and a minimal sanitized
|
|
definition/input. For a run failure include its ID and relevant inspect evidence.
|
|
Describe whether it reproduced in a disposable repository. Redact tokens, credentials,
|
|
private paths/prompts, file contents and patches before sharing; inspection output
|
|
is not automatically safe to post publicly. Do not export your database or OpenCode
|
|
credential/session storage as a bug report.
|
|
|
|
## Maintainer checks without inference or deployment
|
|
|
|
```sh
|
|
go test -race -count=1 ./...
|
|
go vet ./...
|
|
python3 -m unittest discover -s scripts -p 'test_*.py'
|
|
python3 scripts/smoke-first-install.py
|
|
```
|
|
|
|
The developer-only smoke check builds source binaries and installs the skill into a disposable directory,
|
|
starts an isolated loopback server/database, checks build identity, empty initial
|
|
state, five starters, draft/validate/publish, identical ZIP import and restart
|
|
persistence, then shuts it down and removes only its temporary directory. It does
|
|
not call models, send alerts, update your installed clients or deploy Docker services.
|
|
It does not replace real-provider, terminal interaction or fresh Docker-install tests.
|
|
Live inference remains [explicitly opt-in](reference-workflows.md).
|