# Smoke testing

[Documentation index](../README.md)

These are maintainer acceptance checks for behavior that benefits from a real
Pi/Herdr boundary.

Use disposable workers and exact-ID cleanup. Do not disturb unrelated user
workspaces or agents.

## Preconditions

Verify:

```sh
node --version
pi --version
herdr --version
herdr integration status
```

The supported repository contract requires:

- Node `>=22.19.0`
- Pi `>=0.84.2 <0.85.0`
- Herdr `>=0.8.0`
- Herdr Pi integration version `2` or newer

Run the repository validation gate first.

## Fresh worker

Assign a small read-only task to `scout`.

Verify:

- one managed worker starts;
- the task is acknowledged;
- the worker completes;
- exactly one result reaches the owner;
- one-shot cleanup removes the worker.

## Reusable worker

Start with `reusable: true`.

After completion, verify `subagent list` reports `ready`.

Assign a second task by the exact label.

Verify:

- same live worker/session is reused;
- no prompt/start reconstruction occurs;
- second task produces one new correlated result.

## Historical session resume

Use an exact saved session path or full UUID.

Verify:

- saved definition and cwd are respected;
- optional cwd assertion must match;
- current effective agent override values are used when a non-live session is
  restored;
- the exact session continues.

## Fork

Assign a fresh agent with `fork` pointing to an exact saved session.

Verify:

- a new worker/session is created;
- the fork source is explicit;
- the current supervisor session is not implicitly used.

## Inferred delegation

Use a bundled parent definition whose source `tools` list does not explicitly
contain `subagent`, such as the current `implementer`.

Ask it to delegate one bounded scout task.

Verify:

- the real Pi worker can call `subagent`;
- child result reaches the parent;
- parent integrates it once;
- all one-shot workers clean up.

This proves effective-definition inference reaches Pi launch policy rather than
only metadata.

## Body reference expansion

Create a temporary global definition with a whole-line body reference:

```markdown
---
name: worker
bodyMode: append
---

@../temporary-policy.md
```

Use a distinctive instruction in the referenced file.

Verify the worker obeys that instruction through the expanded private prompt.

Afterward remove the temporary definition and referenced file, confirm discovery
no longer lists the temporary definition, and verify no repository file changed.

## `ask_owner` round trip

Give a worker a task whose correct continuation requires an owner choice.

Verify:

1. worker calls `ask_owner` alone;
2. owner receives one question;
3. worker becomes `blocked`;
4. owner replies with exact `subagent reply`;
5. same assignment/session resumes;
6. worker produces exactly one final result;
7. no worker/mailbox leak remains.

## Delegated-parent natural waiting

Ask a parent to delegate required reconnaissance when no useful independent
local work remains.

Inspect the actual transcript and verify the parent:

- ends its turn normally after the assignment;
- does not poll `subagent list`;
- does not sleep or use a separate wait mechanism;
- wakes when the child result is delivered;
- integrates the result into one final parent outcome.

## Useful concurrency

Give a parent one delegated task A and independent local task B.

Verify it can work on B while A is active, then ends its turn when no useful
independent work remains and integrates A after result delivery.

## Root `/subagents` commands

In a root session with UI:

### `/subagents agents`

Verify:

- one readable themed overview;
- correct definitions;
- model/thinking when configured;
- tools and skills shown in the definition overview;
- direct `subagents` shown;
- overridden/custom state clear;
- bundled source paths hidden in human output;
- override/custom paths discoverable;
- narrow panes remain width-safe.

Structured `subagent list` should still retain exact deterministic metadata.

### `/subagents overrides`

Set and reset model/reasoning on a disposable override.

Verify:

- unrelated frontmatter and body remain unchanged;
- reset removes only the selected line;
- fresh starts/resumes use the current effective value;
- running workers are not mutated.

### `/subagents placement`

Query, change to the alternate value, verify, then restore the original value.

### `/subagents stop`

With disposable owned workers, verify the owned tree closes while an unrelated
Herdr agent remains untouched.

## Failure diagnostics

Use a disposable invalid resource/start configuration only when safe.

Verify startup failure:

- settles within the bounded budget;
- reports the stage and best available diagnostic;
- performs exact ownership-safe rollback;
- does not leave a false successful worker.

## Cleanup checklist

After every smoke:

- `subagent list` has no unintended managed workers;
- temporary global definitions are removed;
- temporary prompt/body files are removed;
- disposable Herdr resources are closed by exact ID;
- no repository source file changed unless the smoke explicitly required it.