Repository navigation
0.3.0 - 2026-10-31
Release Notes
Added
-
Before a session opens, Tenaz estimates its first request: the prompt
at 3 bytes per token, plusharnessReserveTokens(default 8192) for the
harness's own prompt and tools. Over the budget of the role's model,
the run blocks with a reason that startsprompt too large:, names the
role, the task if any, the model and its window, and says what to
change; no session runs. A card's own token budget and the engine's
capacity cap do not count here. Over the Digger 3D run of 2026-10-29
the estimate was 2.2k to 4.5k tokens high, never low. See ADR 0012. -
diffShare(default 0.25) sizes the diff a reviewer is shown by its
own model's context budget, under the engine's capacity cap when there
is one, counted at 3 bytes per token, withdiffLimitBytes(40000)
still the most. A reviewer on a 65536 window atcontextBudget0.65
gets about 32 KB; one on 131072 gets 40 KB, as before. In the Digger 3D
run of 2026-10-29 the reviewer's first request was 30245 of its 42598
tokens before it read a file, half of it the diff. A run.json without
diffShareloads with the default. See ADR 0012. -
tenaz init --model-for ROLE=IDgives a role another model than
--model, for example a reviewer of another model family, served by the
same engine. It is repeatable, one role each, and
--context-window-for ROLE=Nsets that model's window (default: the
run's). The map is kept inrun.jsonunderconfig.roleModels;
tenaz statusnames the roles it covers and gives the builder's context
budget, andstatus --jsonhasrole_models. An unknown or repeated
role, the run's own model, and a window for a role with no model of its
own are refused, and so are one model given different windows for two
roles and a map with--harness pi.fx is launched with each session's model, and the session's context
budget is thecontextBudgetshare of that model's window; the
session's journal record hasmodel. Planners size cards for the
builder's model. After the engine runs out of memory, the lowered budget
is raised toward the largest model's budget. See ADR 0011. -
With
--model-for, every model of the run must be loaded before the
first session. Tenaz loads those that are not, as it does the run's
model, andtenaz runstops and names any it could not load. Around an
image job or a heavy job the lease frees every model and loads them all
back; a generic engine's stop and start commands run once for all of
them. A generic engine that serves only some of the run's models is not
started a second time:tenaz runstops and names the others. -
A builder whose task needs work too heavy for a session (a render, a
long build) writes.tenaz/jobs/<TASK>.jsonwith the command, its time
limit and why, and stops. Tenaz runs the command between sessions of the
same attempt, with the engine's request gate closed and the LLM unloaded
where the engine can, for at mostjobMinutes(60); a fresh session
then gets its exit code, duration and the end of its log, in
.tenaz/private/jobs/. The job does not cost an attempt. An attempt
may havejobsPerAttempt(3) job files; one past them is removed unread
and the attempt is judged. The journal getsjob-startedand
job-finishedrecords. A file that is not valid runs nothing and the
next session is told why. A stop during the job pauses the run, and on
resume the job runs again before any session; a report no session has
read yet is kept inrun.jsonacross a pause. A crash costs the
attempt: the job file it left is removed unrun. After a job the LLM
serves again before the next session; one that does not come back
blocks the run as "engine unavailable".jobMinutes=0turns jobs off:
a job file is removed unread and the attempt is judged. In the Lotion
Pump run a 25-minute Blender render next to the model's engine failed
for memory, and so did the engine; the operator had to run it with the
run blocked. See ADR 0010. -
A builder session rerun after the engine ran out of memory is told why
and asked not to leave heavy work running in the background, but to
declare it as a job. Other roles, other engine errors and runs with
jobMinutes=0get no such note. See ADR 0010. -
A builder whose task cannot pass without changing a check of a done task
writes.tenaz/conflicts/<TASK>.mdnaming those checks and stops. Tenaz
blocks the task at once, without more attempts or a split, journals a
conflictrecord, and starts a replan that is shown the conflict. The
replan may add a card withamends: [<check IDs>], naming only checks a
conflict names; its builder may change those checks and no others, and
its reviewer judges each change against the spec. A conflict with the
task's own checks, or with a task that is not done, does not stand: the
attempt fails as before and the next builder is told why. A builder that
declared a conflict is not asked for a passing check, and a conflict
belongs to the attempt that declares it: the file is removed when an
attempt starts. In the Lotion
Pump run the builders of T016b measured that their card and a check of
T016a could not both pass, and no session was allowed to change the
check. The builder prompt no longer promises a replan for any other
task that cannot be done. See ADR 0009. -
Without the sandbox, a write tool that names a file outside the project,
the temporary directories, on macOS the per-user cache, and
sandboxAllowWriteis noted: a line in
orchestrator.log,outside_writesand anoutside-writewatchdog
event in the session's journal record, and one steer telling the session
its files belong in the project. A bootstrap step that is not accepted
says where the files went. The write is not stopped, and shell commands
are not checked. See ADR 0008.
Changed
- These apply to every run, with or without
--model-for:- A session whose context budget is already under the cap a memory
failure set (a card that asks for a small budget, for example) no
longer counts toward raising the cap: it did not test it. - After an image job or a heavy job, a generic engine's start command
is skipped when the engine still serves the model. - When the run's model is not served before the first session,
tenaz runsaysModel <id> is not being served at <url>, with why
loading it failed, instead ofthe LLM could not be loaded: ...
(Model <id> is not being served (<error>)when the engine does not
answer, as before). - When freeing the LLM for an image or a heavy job fails and the engine
still answers without it, Tenaz loads it back at once (a generic
engine's start command runs) instead of leaving it to the engine
retry.
- A session whose context budget is already under the cap a memory
- On macOS the sandbox lets the agent and
verifywrite the per-user cache
(getconf DARWIN_USER_CACHE_DIR), as they could already write the
temporary directory beside it. Metal keeps its compiled shaders there:
without it every program that draws with Metal compiles them again on
each start, and in a Blender benchmark each./blendercall took about
10 s longer (a small render took 11 s instead of 0.9 s). - In the failure history a split is shown, an attempt whose
verify
failure repeats the one before word for word says so and names the
attempt that has the text, instead of repeating it. In the Lotion Pump
run the split of T016b read the same 1.5 KB ofverifyoutput three
times.run.jsonkeeps that failure ascurrent.verify_failure
(attempt,text). - A builder whose previous attempt failed
verifyword for word as an
earlier one is told so. Ifverifyreports a measurement, nothing done
since moved it: change the approach; or, when the card cannot pass
without changing a check of a done task, declare the conflict (see
"Added"); or say in the notes why the card cannot be done, and stop. In
the Lotion Pump run the three attempts of T016b each left the scene at
its starting numbers. The task is not escalated any sooner: a check
that only saysexit 1reads the same while real work goes on. - The release builds the macOS archive on GitHub's
macos-15runner
instead ofmacos-14, whose retirement GitHub set for 2026-11-02. The
binary's minimum macOS should not change (11.0, Rust's default for
Apple silicon).
Fixed
- The builder of a split task may write the notes of the tasks it was
split from:T021ddmay correct.tenaz/notes/T021d.mdand
.tenaz/notes/T021.md. Tenaz reverted those edits, so a card the split
wrote to fix a parent's stale handover could never pass. See ADR 0013. - A builder session after one whose writes Tenaz reverted is told which
paths were reverted, why, and where a builder may write. Only the
bootstrap was told before, so the builders of a task could write the
same forbidden file on every attempt without learning whyverify
never saw it.run.jsonkeeps the paths ascurrent.reverteduntil
the task ends. - A session paused with Ctrl-C keeps its continuation until a session
that continues it ends. A rerun after an engine error or a lowered
context budget is told it continues the paused work, and so is the
session after--resumewhen the run blocks because the harness refused
its prompt, or the engine or capacity retries ran out. Tenaz used to
clear the continuation before the first session, so these started the
work afresh with the paused session's changes in the tree. - A prompt the harness refuses as larger than the model's window (fx's
ContextCapacityExceededbefore any reply) blocks the run at once, with
a reason that startsprompt too large:, names the session, its role,
its model, the model's window and the prompt's size, and says what to
change. The same error after a reply is rerun as before. Tenaz used to
send the same prompt again up toengineRetriestimes and then block as
"engine unavailable": in the Digger 3D run of 2026-10-29 that took seven
sessions and about 45 minutes. A builder whose prompt is refused is not
charged the attempt. See ADR 0012. - mlx-serve's refusal of a prompt that "does not fit in GPU memory" is
treated as the engine running out of memory, rather than as an unnamed
engine error: the session's log line saysfailed (engine out of memory), and a builder's rerun gets the memory note when jobs are on.
For any engine out of memory, the rerun's log line, the notice at the
first rerun, and the run's reason once the retries run out say to free
memory or reload the model. The journal'scausestaysengine. In
the Digger 3D run of 2026-10-29 mlx-serve refused a reviewer this way
seven times; the waits did not help, a reload of the model did. See
ADR 0012. - A list of changed files put in a prompt is clipped to
statClipBytes
(8000 bytes, a new parameter), at a whole line, with the number of lines
left out. Such lists went in whole: the reviewer's (ahead of a diff
clipped todiffLimitBytes) and its list of changed images, the files
an earlier bootstrap session left, and a retried builder's changes so
far. In the Digger 3D run of 2026-10-29 a task had committed 3,265
node_modulesfiles: their list alone was about 200 KB, and fx refused
the review before sending it, as over the reviewer model's 65,536-token
window. Every rerun sent the same prompt. - With fx, an engine that runs out of memory part way through a reply is
reported as such. Sushi sends the error inside a stream that started
with status 200, which the proxy ignored, so the session read as a
harness exit:failed (toolUse)in the log andcause: harnessin the
journal. The proxy now reads anerrorsent in adata:chunk of the
stream and reports it as it arrives; the session's log line says
failed (engine out of memory)and the rerun's log line says another
program may be using the GPU. In the Lotion Pump run seven sessions
ended this way while Blender rendered on the same GPU. Pi reports
engine errors itself, without the proxy; an out-of-memory error it
reports is named the same way. - Any engine error stated before the harness exits now journals the
rerun ascause: enginerather thanharness: the exit follows the
error. The journal'scausekeeps its two values; out of memory is
engine. - A harness that dies in a later prompt of its session, such as the one
that asks a builder for its task's checks or the note that resumes an
interrupted turn, is rerun without charging an attempt, as one that
dies in the first prompt is. The session counted as settled from its
first answer, so the crash failed the attempt: in the Lotion Pump run
fx lost its engine connection while T016b's builder was adding its
check, and the task lost attempt 2. - The preflight no longer fails an engine that does not report cached
prompt tokens. LM Studio 0.4 reuses the prompt prefix but leaves
cached_tokensout of its usage, which looked like no cache and needed
--allow-weak-engine. Such an engine now passes with a warning, and
tenaz statussays its prompt cache is "not reported" instead of 0 %;
run.jsonhaspreflight.cache_reportedandtenaz status --jsonhas
prompt_cache_reportedandprompt_cache_percent. An engine that
reports 0 cached tokens still fails. Needs the engine proxy. See ADR 0007. - A task out of attempts keeps its notes. Its work was reverted with the
notes in it, so the split never saw what the builders had measured and
ruled out, and wrote cards that retried it: in the Lotion Pump run the
split of T016b blamed a cause its builder had already disproved. The
notes now survive the revert, the split's prompt shows them under
"Builder notes from the failed attempts", and a blocked task keeps them.
Install tenaz 0.3.0
Install prebuilt binaries via shell script
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/aartiles/tenaz/releases/download/v0.3.0/tenaz-installer.sh | shInstall prebuilt binaries via Homebrew
brew install aartiles/tap/tenazDownload tenaz 0.3.0
| File | Platform | Checksum |
|---|---|---|
| tenaz-aarch64-apple-darwin.tar.gz | Apple Silicon macOS | checksum |
| tenaz-x86_64-unknown-linux-gnu.tar.gz | x64 Linux | checksum |
Verifying GitHub Artifact Attestations
The artifacts in this release have attestations generated with GitHub Artifact Attestations. These can be verified by using the GitHub CLI:
gh attestation verify <file-path of downloaded artifact> --repo aartiles/tenazYou can also download the attestation from GitHub and verify against that directly:
gh attestation verify <file-path of downloaded artifact> --bundle <file-path of downloaded attestation>