Skip to content

0.3.0 - 2026-10-31

Choose a tag to compare

@github-actions github-actions released this 31 Oct 14:12

Release Notes

Added

  • Before a session opens, Tenaz estimates its first request: the prompt
    at 3 bytes per token, plus harnessReserveTokens (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 starts prompt 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, with diffLimitBytes (40000)
    still the most. A reviewer on a 65536 window at contextBudget 0.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
    diffShare loads with the default. See ADR 0012.

  • tenaz init --model-for ROLE=ID gives 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=N sets that model's window (default: the
    run's). The map is kept in run.json under config.roleModels;
    tenaz status names the roles it covers and gives the builder's context
    budget, and status --json has role_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 the contextBudget share of that model's window; the
    session's journal record has model. 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, and tenaz run stops 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 run stops and names the others.

  • A builder whose task needs work too heavy for a session (a render, a
    long build) writes .tenaz/jobs/<TASK>.json with 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 most jobMinutes (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 have jobsPerAttempt (3) job files; one past them is removed unread
    and the attempt is judged. The journal gets job-started and
    job-finished records. 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 in run.json across 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=0 turns 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=0 get no such note. See ADR 0010.

  • A builder whose task cannot pass without changing a check of a done task
    writes .tenaz/conflicts/<TASK>.md naming those checks and stops. Tenaz
    blocks the task at once, without more attempts or a split, journals a
    conflict record, and starts a replan that is shown the conflict. The
    replan may add a card with amends: [<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
    sandboxAllowWrite is noted: a line in
    orchestrator.log, outside_writes and an outside-write watchdog
    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 run says Model <id> is not being served at <url>, with why
      loading it failed, instead of the 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.
  • On macOS the sandbox lets the agent and verify write 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 ./blender call 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 of verify output three
    times. run.json keeps that failure as current.verify_failure
    (attempt, text).
  • A builder whose previous attempt failed verify word for word as an
    earlier one is told so. If verify reports 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 says exit 1 reads the same while real work goes on.
  • The release builds the macOS archive on GitHub's macos-15 runner
    instead of macos-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: T021dd may correct .tenaz/notes/T021d.md and
    .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 why verify
    never saw it. run.json keeps the paths as current.reverted until
    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 --resume when 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
    ContextCapacityExceeded before any reply) blocks the run at once, with
    a reason that starts prompt 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 to engineRetries times 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 says failed (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's cause stays engine. 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 to diffLimitBytes) 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_modules files: 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 and cause: harness in the
    journal. The proxy now reads an error sent in a data: 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 as cause: engine rather than harness: the exit follows the
    error. The journal's cause keeps 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_tokens out of its usage, which looked like no cache and needed
    --allow-weak-engine. Such an engine now passes with a warning, and
    tenaz status says its prompt cache is "not reported" instead of 0 %;
    run.json has preflight.cache_reported and tenaz status --json has
    prompt_cache_reported and prompt_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 | sh

Install prebuilt binaries via Homebrew

brew install aartiles/tap/tenaz

Download 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/tenaz

You 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>