hankweave
Docs
Southbridge
You're reading the 0.10.0 archive.
Docs/Start here

Upgrade Hankweave without upgrading blind

Upgrading a runtime that executes agent work is riskier than upgrading a library. A new Hankweave binary can reject a hank that the old one accepted, and a resumed execution can keep a model-resolution plan that no longer matches your intent. Neither failure is obvious until a run is already underway and spending money.

The safe order is: validate the hank with the new binary before any execution, repair what it reports, then decide deliberately between a fresh execution and a resume. The sections below walk that sequence for 0.10.0, then work backward through the migration boundaries at 0.9.0 and 0.8.0, the model-spelling drift that can appear after any release, and the older changes that matter if your hank has crossed several versions at once.

Validate before the new runtime spends a run#

The first check costs nothing and runs no codons. Point the new runtime at your hank:

⌁ Terminal
bunx hankweave@0.10.0 --validate ./my-project/hank.json

Run the command from a location where ./my-project/hank.json exists, then fix every reported error and repeat until it passes. A codon is a configured unit of agent work; validation checks the configuration, authored paths, required environment, SDK availability, and model catalog without running codons or making a model-generation self-test call. A successful validation prints ✓ Configuration is valid!, a GOOD TO RUN! box, and exits 0:

Output
✓ Configuration is valid!

╭──────────────────────────────────────────────────────────────────────────────╮
│  Minimal single provider v1.0.0                                              │
│  1 codon • 0 loops                                                           │
╰──────────────────────────────────────────────────────────────────────────────╯

└─ [1] summarize-notes (Summarize the notes)
      model: haiku │ mode: fresh │ prompts: 1 (13 lines)
      checkpointedGlobs: 1

╭─ GOOD TO RUN! ─────────────────────────────────────────────────────╮
│  1 codons • 1 prompts • 0 system prompts • 0 rigs • 1 checkpoints  │
╰────────────────────────────────────────────────────────────────────╯

The summary box confirms what the runtime loaded: one codon, its model and mode, and the checkpoint globs it will honor. If your hank has more codons, each appears in the same listing, which makes this output a quick way to spot a codon resolving to a model you did not expect.

Validation is not a read-only or universally offline operation. At 0.10.0 it can add $schema to the hank and write a temporary validation log; telemetry is emitted, and Bedrock credential discovery can probe instance metadata. Runtime startup is a different phase: its provider health checks can call generateText("Hi", maxOutputTokens: 16) against available registry providers, not only the models selected by your hank. Those calls can be billable and are outside the tracked-codon capture total. See authentication and models for the two model-selection planes.

Once validation passes, choose whether the execution should be new or resumed. This choice matters more after an upgrade than it does day to day, because a resume preserves the originally resolved model plan:

  • For an upgrade rehearsal, use a fresh execution:

    ⌁ Terminal
    bunx hankweave@0.10.0 ./my-project --start-new -y

  • Resume only when the old hank was accepted with -y and the resolved model plan is still the plan you want. If the hank hash changed, non-interactive mode without -y can stop with Operation cancelled by user; -y accepts the changed hank, but it does not re-resolve a persisted model plan.

  • If you changed a codon's model, use --start-new. A resume preserves the originally resolved model, so neither --model nor an edited hank re-resolves a failed codon's model in that resumed execution.

For the fresh run, look for the Hankweave Server Started box, then verify that each codon.completed event has "success":true and that the run ends with RunCompleted:

Output
══════════════════════════════════════════════════
  Hankweave Server Started
  WebSocket: ws://localhost:<port>
══════════════════════════════════════════════════
JSON
{"id": "<id>", "timestamp": "<ts>", "type": "codon.completed", "data": {"codonId": "summarize-notes", "success": true, "cost":"<n>", "duration":"<n>", "exitStatus": {"type": "success"}}}
{"id": "<id>", "timestamp": "<ts>", "type": "state.transition", "data": {"transitionType": "RunCompleted", "runId": "<id>", "transition": {"type": "RunCompleted", "data": {"runId": "<id>"}}, "resultingState": {"currentRunId": null, "runCount": 1, "totalCost":"<n>", "currentRunCost":"<n>"}}}

Check-it: the validation command exits 0 only after the configuration is accepted and prints the two success markers above. After the fresh run, inspect its output or event stream for the startup box, successful codon completion, and terminal RunCompleted; these are separate checks, not proof that validation ran a codon.

Move paths and models before 0.10.0 loads#

If validation fails after the upgrade, the most likely cause at 0.10.0 is the new path contract. Authored references in hank.json – promptFile, appendSystemPromptFile, globalSystemPromptFile, rigSetup.copy.from, and string sentinel references – must be portable relative POSIX paths inside the hank directory. Absolute paths, backslashes, NULs, drive-letter paths, symlink traversals, and a .. climb that leaves the hank root are rejected. A relative .. step that remains inside the hank root is allowed; a shared file outside that root must be copied into the hank instead.

The repair is usually to make an in-hank reference explicit:

JSON
{
  "promptFile": "./prompts/review.md"
}

Copy a file referenced as /workspace/project/prompts/review.md into ./prompts/review.md; copy a shared file outside the hank into the hank rather than retaining ../shared/prompt.md. rigSetup.copy.from has two additional limits: it may not name the hank directory itself, including ., sub/.., or a symlink spelling, and its entire source tree must contain only regular files and directories. A symlink, FIFO, socket, device, or other special file at any depth is a load-time violation.

For all file-reference rules, see the hank.json reference. Do not rely on an editor accepting the JSON: run --validate after moving the files.

Paths are not the only new load-time check. 0.10.0 also performs Pi catalog preflight at startup: every Pi-routed model must be present in Pi's catalog, and a model known to the registry but not servable by Pi fails at configuration load with a diagnostic that lists available models for that provider. This is different from a misspelled registry model. See model resolution for the diagnostic and resolution stages.

Harness choice is late-bound. harnessOverride: "pi" forces the embedded Pi harness even when the model would otherwise use the Claude Agent SDK. On resume, a legacy persisted pi pseudo-provider is reverse-mapped to the real provider; an old plan that forced an Anthropic model onto Pi is re-routed to the Claude Agent SDK. The change preserves model identity instead of turning every model into a Pi provider spelling.

The published schema also now recognizes the root requirements and globalSystemPrompt* fields, and sentinel file references resolve relative to each sentinel config's own directory rather than the first config directory.

Check-it: put an absolute reference or a source-tree special file in a disposable copy of the hank, then run the pinned --validate command. The load must fail with a path-policy or regular-file diagnostic before a codon runs; use the hank.json path contract for the exact rule that applies.

Make CI trust copy-failure exit codes (0.9.0)#

One version back, the change that matters most is in CI rather than in the hank. If your pipeline treats a nonzero process status as the run-failure signal, 0.9.0 fixed the important edge case: an outputFiles beforeCopy or copy failure now fails the run and exits 1. In older versions that failure could be logged while the process continued toward an apparently completed run with exit 0. Remove log-scanning workarounds that existed only to compensate for that old exit behavior, and keep the exit-code contract in errors and exit codes.

0.9.0 also added AWS Bedrock codons and sentinels, with credential rules and permanent-failure classification; use the dedicated AWS Bedrock reference for credential scope and limitations. It introduced npm trusted publishing and provenance, with npm audit signatures as the documented verification command, and added repository and license metadata as well.

Check-it: make the output-stage command fail in a controlled CI test and assert the process status is 1, rather than asserting on a log line. The runtime's output-stage failure path is the backing contract; do not treat a successful codon event as a successful run when output copying failed.

Rewire compaction, keys, and harnesses for 0.8.0#

Treat 0.8.0 as the larger migration boundary. Several defaults and integrations changed at once:

  • Opt into compaction per codon. autoCompact is now false by default. If a codon previously crossed its context window because the harness silently compacted, add "autoCompact": true to that codon. With compaction off, the provider's context-overflow error is surfaced; terminateOn: contextExceeded now recognizes overflow results and compact boundaries.

  • Rename Google's key. Replace GOOGLE_API_KEY with GEMINI_API_KEY, including HANKWEAVE_SENTINEL_GEMINI_API_KEY for the sentinel-scoped form. The old name is not read.

  • Remove shim assumptions. There are two in-process harnesses: the Claude Agent SDK for Anthropic models and the embedded Pi agent for everything else. The gemini-cli, codex, and opencode subprocess shims are gone. Existing opencode/<provider>/<model> spellings are rewritten to pi/<provider>/<model> at load; verify that the resulting model is the one you intend.

  • Update authentication. Anthropic OAuth tokens and Codex-CLI session pickup are no longer supported. The ChatGPT subscription route is the embedded Pi path through pi login; API-key routes use the current provider key names.

  • Recheck the init shape. --init now scaffolds four codons rather than three. Inspect the complete scaffold and choose its authentication setup in the first-run guide.

  • Review retries and execution location. Network failures are classified with the common retriable/permanent taxonomy; see errors and exit codes. HANKWEAVE_RUNTIME_EXECUTION_BASE_DIR is the effective environment variable for moving the managed execution root; hankweave.json's executionBaseDir field is informational only. Pi sessions are hermetic and do not inherit personal ~/.pi/agent settings.

Keep the harness change in mind when auditing old model names: a model is routed through one of the two in-process agents rather than through a subprocess shim wrapping an external CLI. Check the current routing rules in model resolution.

Check-it: in CI, unset GOOGLE_API_KEY, set GEMINI_API_KEY, and run the validation/self-test for the affected configuration. The code-derived assertion is that the old name cannot satisfy the Gemini requirement while the new name can; do not use an old shim command as the test.

Recheck model spellings after every release#

Model data can change independently of your hank, so this check applies after every upgrade, not only at the migration boundaries above. Inspect pinned full IDs and confirm them against the current registry. A pinned ID that worked in 0.8.x may be retired in 0.10.0; the shortcuts haiku, sonnet, and opus are the stable choices for the corresponding current families.

For the current GPT shortcut, bare gpt-5.6 resolves to gpt-5.6-sol; gpt-5.6-high and gpt-5.6-xhigh resolve to the same base with their effort suffixes preserved. Kimi's current flagship is kimi-k3. Older kimi-k2.x IDs such as kimi-k2.5 and kimi-k2.7-code are still catalog-listed at 0.10.0, and kimi-k2.7-code resolves in the current model data; keep a pinned Kimi ID only if it still resolves, confirming with --validate after any spelling change. For the full shortcut and resolution tables, use model resolution.

For a structural test, we can use a stable shortcut, then pin only when the deployment requires a specific identity. That avoids silently retaining a retired dated ID across upgrades. Check the exact-resolution policy in the reference before choosing a pin.

Check-it: after editing a pinned ID, run --validate and read the resolved model shown for each codon. If the ID is absent from the current catalog or Pi catalog, repair the spelling.

Account for changes before 0.8.0#

If your hank predates 0.8.0, start with the versions it has crossed and follow the details you actually use:

  • 0.7.x: Braintrust/Langfuse trace upload arrived through hankweave-trace and HANKWEAVE_TRACE_*; 0.7.0 added self-test failure classes so launch, missing-binary, authentication, check, and unknown failures can be diagnosed separately; 0.7.3 added headless fail-fast behavior for retriable failure under onFailure: "abort" and a 30-second shutdown watchdog. Continue in observability.
  • 0.6.1: the budget system arrived, including maxDollars, maxTimeSeconds, maxOutputTokens, maxContextTokens, onExceeded, and loop allocation. Continue in budgets.
  • 0.5.6–0.5.7: --replay, rig.output streaming, and HANKWEAVE_RUNTIME_SHOW_COSTS arrived. Continue in the CLI reference and the runbook.
  • 0.3.0: the welcome wizard appeared for bare invocation. For the current first-touch behavior, use first run.

Check-it: identify the oldest runtime that created your hank, then check each applicable row's owner before changing configuration. The exit-code and retry contracts are version-sensitive; use the current error reference instead of inferring behavior from an old log.

Compare features across versions before upgrading#

Work through the sections above version by version, applying each breaking or migration-relevant change your hank has crossed. There is no generated version-to-version compatibility matrix for 0.10.0. For the authoritative release list, read the changelog; for the pinned configuration target, use hank.json.

A modern hank shape is available in the quote-template-unification example: its $schema targets 0.10.0, authored references use relative POSIX paths, sentinel references are present, and codons carry budgets and retry configuration. Use it as a shape to inspect, not as a compatibility table or a replacement for validating your own hank.

There is no captured end-to-end N→N+1 upgrade behind this page. The supplied runs are same-version 0.10.0 captures, so the migration actions here are derived from the changelog, schema, and shipped source rather than from a rehearsal of a live cross-version upgrade. Validate your own hank and start a fresh execution when changing a frozen model plan.

Check-it: compare your hank's $schema target and authored path spellings with the 0.10.0 contract, run bunx hankweave@0.10.0 --validate, and record any repair before starting a fresh execution. Do not report the same-version validation capture as proof of a completed N→N+1 rehearsal.

Made by SouthbridgeNeed a hand? →