---
type: types/instruction.md
name: session-setup
description: Scope the wikitool iteration budget to the task by exporting a stable session id before the first tool call.
---

# Scope the session budget

Every `wikitool` call is counted against a per-session iteration budget. A "session" is keyed
by `WIKITOOL_SESSION_ID`, falling back to the parent process id when that variable is unset.

Without an explicit id, the budget is scoped to whichever shell happened to run the command,
so a task spanning several terminals is counted as several sessions - and one that reuses a
shell inherits an unrelated count.

## Steps

Run this **once per working session**, before the first `wikitool` call that changes anything:

```bash
export WIKITOOL_SESSION_ID="wiki-$(date +%s)"
tools/wikitool sync
```

Check the current state at any time with `tools/wikitool budget status`, which is never
counted against the budget itself and prints the id it is counting under.

**Why `sync` here, not just at publish time.** `publish` already pulls before it pushes, but a
session that runs many `wikitool` calls before its first `publish` (an ingest, a multi-page
update) would otherwise build all of that work against whatever the local clone happened to
hold when the session started - stale by however long the previous sync was, on a repo more
than one machine or session writes to. Running `sync` first shrinks that window to the start of
the session instead of discovering the drift only at the very end.

`sync` fetches the remote and fast-forwards or rebases automatically when that is safe; it
never commits and never pushes. **Exit 42 (rebase-review)?** Same as any exit 42 - read the
diff it prints, judge whether it conflicts with what you are about to do, summarize that to the
user, then `tools/wikitool sync --confirm-rebase <token>` before continuing. See
[gates.md](gates.md).

## Multi-unit runs

A task planned as several units - a tree ingest, where each unit produces its own source page
and its own `publish` - takes one id per unit, derived from the workshop's run key:

```bash
export WIKITOOL_SESSION_ID="ingest-documents-handbook/u3"
```

The run key, the workshop directory name and the session id are then the same string, so the
checklist in `work/<runkey>/README.md` and the budget state cannot disagree about where the
run stands.

A new id may only be taken at a unit boundary recorded in `plan.md` - never after a gate
refusal. See [gates.md](gates.md).

## Scope

Read-only retrieval (`wikitool search`) is exempt from the budget and needs no setup. This
matters only for commands that change the wiki.

The limits themselves, and what to do when one trips, are in [gates.md](gates.md).