Hankweave v0.6.2

Installation

Via npm:

npm install -g hankweave
# or
npx hankweave --init

Via Standalone Executable:
Download the binary for your platform below, make it executable, and run it.

What's Changed

[0.6.2] - 2026-03-19

Added

• Exported public types and schemas — server/exports/types.ts and server/exports/schemas.ts expose a stable set of runtime types and Zod schemas for use by external consumers. A dedicated tsconfig.exports.json and updated build script generate the exports bundle.

Changed

• Updated model data — Refreshed models-dev-data.json with latest provider model entries (March 2026). (ENG-225)
• Codex shim API key logic consolidated — resolvedApiKey, apiKeySource, and isAuthConfigured are now readonly getters on CodexShim, replacing scattered utility functions. Key priority order is explicit and tested: OPENAI_API_KEY > CODEX_API_KEY > ~/.codex/auth.json. Unit and integration tests cover all priority combinations.

Fixed

• Codex shim falls back to SDK bundled binary when codex not on PATH — resolveCodexPath() previously called writeStartupError if which codex failed, blocking the SDK's own findCodexPath() from running. In CI, codex is not on PATH but is available via npm platform packages. Now passes null to the Codex constructor so it can resolve the binary itself; self-test also tries tryFindSdkBundledCodex() as a fallback.
• Codex shim WebSearch defers tool_use emission until item.completed — WebSearch items arrive with query: "" at item.started; the real query only appears in later streaming chunks. Deferring emission ensures transcript logs record a non-empty query.
• Codex warnings no longer thrown as errors — The shim previously threw on any non-fatal warning message from Codex, causing spurious failures. Warnings are now logged and ignored.
• Codon failure classification reads msg.result instead of msg.error — ResultMessage has no error field; error text lives in msg.result. Reading msg.error always yielded undefined, so every error result was classified as { type: "unknown", retriable: false }, including retriable timeouts and rate-limit errors.
• Loop codons funded via hank proportional shares now route correctly — When a hank used proportional allocation with a named share for a loop but the loop had no explicit budget field, loopContext.loopBudget was undefined. The routing condition fell through to resolveHankScopedLimits, which looked up shares by codon ID instead of loop ID, yielding a $0 allocation. Now synthesizes an implicit loopBudget: {} so the correct loop-scoped path is taken.

Platform-Specific Instructions

macOS

• Apple Silicon (M1/M2/M3): hankweave-darwin-arm64
• Intel: hankweave-darwin-x64

After downloading:

xattr -d com.apple.quarantine hankweave-darwin-arm64
chmod +x hankweave-darwin-arm64
./hankweave-darwin-arm64 --help

Linux

• x64: hankweave-linux-x64
• ARM64: hankweave-linux-arm64

chmod +x hankweave-linux-x64
./hankweave-linux-x64 --help

Windows

• x64: hankweave-windows-x64.exe

.\hankweave-windows-x64.exe --help

Hankweave v0.6.1

Installation

Via npm:

npm install -g hankweave
# or
npx hankweave --init

Via Standalone Executable:
Download the binary for your platform below, make it executable, and run it.

What's Changed

[0.6.1] - 2026-03-12

Added

• Execution budget system — Per-codon and per-hank cost, time, and token limits with automatic enforcement. Four budget currencies: maxDollars (cost cap), maxTimeSeconds (wall-clock cap), maxOutputTokens (cumulative output token cap), and maxContextTokens (context window high-water mark cap). Budgets are declared in hank.json under a budget object at the hank level, loop level, or codon level.
• Budget allocation modes — Three strategies for distributing a global budget among codons: shared (default, first-past-the-post — each codon draws from the full remaining pool), proportional (share-based with explicit percentages via a shares map; unspent budget flows back to the pool), and proportional-strict (share-based but unspent budget evaporates). Allocation mode is set on the parent container's budget.allocation field.
• --max-cost and --max-time CLI flags — Runtime-level budget overrides. --max-cost 5.00 caps the entire run at $5; --max-time 3600 caps it at 1 hour. CLI values act as a ceiling — they cap but never raise hank-declared limits.
• onExceeded budget policy — Configurable behavior when a limit is hit: "complete" (default) marks the codon as completed and moves on, "fail" marks it as failed and triggers the codon's failure policy. Set per-codon or as a container default.
• Loop-level budgets — Loops can declare their own budget with maxDollars, maxTimeSeconds, allocation mode, and shares. Codon caps within loops are per-iteration (not cumulative across iterations).
• Active watchdog timer for time budgets — A 1-second interval timer checks wall-clock elapsed time independently of cost events, ensuring maxTimeSeconds is enforced even when the model is silently thinking with no token events.
• Budget preflight validation table — --validate now displays a table showing the resolved budget for each codon: ceiling source, allocation mode, per-codon limits, and any warnings (e.g., shares that don't sum to 1.0, unknown codon IDs in shares maps).
• End-of-run budget summary table (budget.summary event) — When a run completes, a summary table is emitted showing per-codon budget vs. actual usage (dollars, time, output tokens), codon status, and whether any limits were exceeded. The TUI renders this inline before the shutdown summary.
• Budget hydration on resume — When resuming a run, the budget system hydrates prior spending and elapsed time from completed runs so allocation calculations account for money and time already spent.
• Pi agent harness shim (shims/pi/) — New shim enabling hanks to run on the Pi agent. Includes session management, provider auth, a translator for the Hankweave message protocol, idle watchdog, and debug recording.
• OpenCode agent harness shim (shims/opencode/) — New shim enabling hanks to run on the OpenCode agent. Includes agent orchestration, model resolution, prompt building, tool handling, and self-test.
• Shared shim common package (@shims/common) — Extracted arg parsing, message protocol types, session management, idle timeout logic, and tool definitions into a shared package used by all shims.
• OpenCode codon in --init template — hankweave --init now scaffolds an OpenCode codon alongside the existing Haiku, Gemini, Codex, and Pi codons.
• Package sanity check in release script — The release dry-run now runs npm pack --dry-run and validates file count (<500), unpacked size (<30MB), and checks for node_modules leaking into the tarball. Catches packaging errors before they reach npm.

Changed

• Codex shim rewritten — The codex shim has been substantially rewritten to use the shared @shims/common package, with full source and build infrastructure (rebuild.sh, TypeScript sources, docs). Includes improved Windows support with vendored codex.exe discovery from npm global installs.
• Passthrough provider model validation uses real capabilities — When a model is routed through a passthrough shim (e.g., opencode/anthropic/claude-haiku-4-5), the model validator now resolves the underlying model from the registry to get real capabilities (context limits, cost data, modalities) instead of using generic defaults.
• Budget fields nested in budget object — Codon-level budget fields (maxDollars, maxTimeSeconds, maxOutputTokens, maxContextTokens, onExceeded) are now nested inside a budget: {} object in hank.json, rather than being top-level codon fields. Hank-level and loop-level budget config follows the same pattern.
• maxDurationSeconds renamed to maxTimeSeconds — For consistency across the budget spec. Applies to both hank-level and codon-level config.
• maxCost renamed to maxDollars — Clearer naming that distinguishes dollar cost from other budget currencies.
• Codon budget caps are per-iteration in loops — A codon's maxDollars inside a loop applies fresh to each iteration, not cumulatively across the entire loop.
• Shared allocation uses first-past-the-post — In shared mode, each codon gets access to the entire remaining pool (not a uniform split). When the pool is exhausted, whoever is running gets stopped.

Fixed

• npm publish failed due to shim node_modules in tarball — The Pi and Codex shims' node_modules/, src/, tests/, and build files were being included in the published npm package (36,575 files, 542MB). Added .npmignore exclusions for shims/*/node_modules/, shims/*/src/, shims/*/tests/, and other build-time-only files. Only the bundled index.js per shim is shipped.
• Loop budgets in proportional allocations — Proportional share resolution now correctly accounts for loop-scoped budgets when computing per-codon allocations.
• Loop time aggregates — Fixed time tracking aggregation for loops where elapsed time was not correctly summed across iterations.
• Codon maxDollars zeroed when no explicit share and shares sum to 1.0 — When all shares were explicitly assigned (summing to 1.0) and a codon had no share entry, its computed allocation was $0. Now correctly falls through to the unallocated pool calculation.
• Codon maxDollars caps (not overrides) proportional share allocation — A codon's explicit maxDollars now acts as a ceiling on its proportional share, rather than replacing it entirely.
• Loop-scoped resolution dropping hank dollar limits when loop has no maxDollars — When a loop had no maxDollars of its own, the hank-level dollar limit was not propagated to codons inside the loop. Fixed to carry the hank ceiling through.
• Budget validation table and preflight warnings — Fixed alignment and content issues in the --validate budget table display.
• TUI label for context token breaches — The TUI now correctly labels context token budget breaches (was showing wrong currency name).
• maxContextTokens shown in budget table — The preflight and summary tables now include the context token limit column.
• Pi shim conflict detection before session prep — Explicit wait conflict detection (idle timeout vs requested silence) now runs before Pi SDK session initialization, avoiding unnecessary SDK startup on known configuration errors.
• Pi shim path resolution — Fixed shim entry point path to use ./index.js instead of dist/index.js.

Platform-Specific Instructions

macOS

• Apple Silicon (M1/M2/M3): hankweave-darwin-arm64
• Intel: hankweave-darwin-x64

After downloading:

xattr -d com.apple.quarantine hankweave-darwin-arm64
chmod +x hankweave-darwin-arm64
./hankweave-darwin-arm64 --help

Linux

• x64: hankweave-linux-x64
• ARM64: hankweave-linux-arm64

chmod +x hankweave-linux-x64
./hankweave-linux-x64 --help

Windows

• x64: hankweave-windows-x64.exe

.\hankweave-windows-x64.exe --help

Hankweave v0.5.7

Installation

Via npm:

npm install -g hankweave
# or
npx hankweave --init

Via Standalone Executable:
Download the binary for your platform below, make it executable, and run it.

What's Changed

[0.5.7] - 2026-03-07

Added

• Rig output streaming (rig.output event) — Rig setup commands now emit real-time rig.output events with stdout/stderr lines, throttled to 1 event per second per stream. The TUI displays rig output inline and uses the last output line as a hint in the activity heartbeat spinner. Enables clients to show rig setup progress instead of a silent wait.
• Context-aware TUI activity spinner — The "Working..." heartbeat now shows phase-specific labels: "Rig running" during rig setup, "Model thinking" during agent execution, and "Completing sentinels" during sentinel drain. The last rig output line is shown as a hint alongside the spinner.

Changed

• TUI cost display is now opt-in — Cost data (dollar amounts, token totals) is hidden in the TUI by default. Set HANKWEAVE_RUNTIME_SHOW_COSTS=1 to display costs.
• Updated model data — Refreshed models-dev-data.json with latest provider model entries (March 2026).

Fixed

• Resume without --data used CWD instead of original data path (ENG-196) — When resuming via --execution without an explicit --data flag, the data source path is now read from execution-meta.json instead of defaulting to the current working directory. Prevents hash mismatches when resuming from a different directory.
• Server hung on resume when killed execution had no checkpoints (ENG-196) — A guard condition prevented starting a fresh run when a failed execution thread had no checkpoints to roll back to. The server now starts fresh instead of hanging indefinitely.
• Replay flow-control decisions lived in wrong module (ENG-196) — Moved replay-specific startup logic from replay.ts into HankweaveRuntime, where other flow-control decisions live.
• Rig output flush interval leaked on command error — The 1-second flush interval for rig output throttling was not cleared when the spawned command errored, causing a timer leak.

Platform-Specific Instructions

macOS

• Apple Silicon (M1/M2/M3): hankweave-darwin-arm64
• Intel: hankweave-darwin-x64

After downloading:

xattr -d com.apple.quarantine hankweave-darwin-arm64
chmod +x hankweave-darwin-arm64
./hankweave-darwin-arm64 --help

Linux

• x64: hankweave-linux-x64
• ARM64: hankweave-linux-arm64

chmod +x hankweave-linux-x64
./hankweave-linux-x64 --help

Windows

• x64: hankweave-windows-x64.exe

.\hankweave-windows-x64.exe --help

Hankweave v0.5.6

Installation

Via npm:

npm install -g hankweave
# or
npx hankweave --init

Via Standalone Executable:
Download the binary for your platform below, make it executable, and run it.

What's Changed

[0.5.6] - 2026-03-02

Added

• Replay mode (--replay flag) — Deterministic re-execution of a previous run from its JSONL logs, without making real LLM API calls. Pass --replay <execution-dir> to replay any completed execution. The original execution directory is copied to a temp location (preserving the source as read-only), hank config and data paths are auto-discovered from execution-meta.json, and rig setup and sentinels are skipped since the copied directory already has post-setup state. Replay uses timestamp-based inter-message pacing (capped at 5s) for realistic output timing. Useful for debugging, demos, and testing TUI/client integrations without API spend.
• Timestamps in LLM log entries — Every JSONL message written by ClaudeAgentSDKManager and ShimProcessManager now includes an ISO 8601 timestamp field. Enables the replay mode's realistic timing and improves log forensics.
• BaseProcessManager base class — Extracted shared context-exceeded detection logic (detectContextExceeded(), emitExit()) into a common base class. ClaudeAgentSDKManager, ShimProcessManager, and the new ReplayProcessManager all extend it. No behavior change; internal cleanup.

Changed

• Context overflow detection unified — ClaudeAgentSDKManager previously had its own inline context-exceeded check that only matched a subset of failure patterns. All process managers now use the shared isContextExceeded() function via BaseProcessManager, fixing cases where context overflow was not correctly reported by the SDK manager.
• ShimProcessManager stdout processing — Replaced raw stdout.pipe() to the log stream with a readline.Interface for line-by-line processing (needed for timestamp injection). The stdout event is now emitted per-line from the readline handler.

Fixed

• TUI shutdown summary showed wrong output path (ENG-211) — The "Run Complete" summary box displayed {executionPath}/outputs/ as the fallback output location when no explicit outputDirectory was configured. Outputs actually live in agentRoot/. Fixed to show the correct agent workspace path.
• Could not resume auto-managed executions via --execution (ENG-198) — Using --execution with a path inside ~/.hankweave-executions/ always threw a hard error, even for existing executions the user wanted to resume. Now checks for the presence of execution-meta.json — if the metadata file exists (indicating an existing execution), resume is allowed. Only creation of new executions in the managed directory is blocked.

Platform-Specific Instructions

macOS

• Apple Silicon (M1/M2/M3): hankweave-darwin-arm64
• Intel: hankweave-darwin-x64

After downloading:

xattr -d com.apple.quarantine hankweave-darwin-arm64
chmod +x hankweave-darwin-arm64
./hankweave-darwin-arm64 --help

Linux

• x64: hankweave-linux-x64
• ARM64: hankweave-linux-arm64

chmod +x hankweave-linux-x64
./hankweave-linux-x64 --help

Windows

• x64: hankweave-windows-x64.exe

.\hankweave-windows-x64.exe --help

Hankweave v0.5.5

Installation

Via npm:

npm install -g hankweave
# or
npx hankweave --init

Via Standalone Executable:
Download the binary for your platform below, make it executable, and run it.

What's Changed

[0.5.5] - 2026-02-26

Added

• --overwrite-output CLI flag — When set, existing files in the output directory are overwritten in-place instead of being renamed with _N_timestamp suffixes. Useful for workflows that always produce the same output filenames across codons and want the latest version, not a history. Default behavior (rename on conflict) is unchanged.
• HANKWEAVE_*=unset env var passthrough — The HANKWEAVE_* environment variable passthrough mechanism now supports the special value "unset". When HANKWEAVE_FOO=unset is set, FOO is actively removed from both the server's own process environment (before sentinel provider initialization) and child process environments (codon agents). Solves the proxy inheritance problem where ANTHROPIC_BASE_URL or OPENAI_BASE_URL from a parent process (e.g., hankhelp) would propagate into codon agents and sentinels, causing guide injection, cost inflation, and silent sentinel failures.

Changed

• Cost tracking extracted from runtime — Cost computation and lifecycle management moved from HankweaveRuntime into a dedicated CostTracker class owned by CodonRunner. No behavior change; internal cleanup.

Fixed

• Sentinel output.file and output.lastValueFile now work — Both fields in sentinel JSON configs were silently ignored despite passing Zod validation. Sentinel output always went to auto-generated paths in .hankweave/sentinels/outputs/ regardless of what was configured. The sentinel constructor now reads config.output.file and config.output.lastValueFile as fallbacks when settings.outputPaths (hank.json) is not set. Priority chain: settings.outputPaths (codon-level) > config.output.* (sentinel-level) > auto-generated. Path resolution uses the same convention: paths with / resolve to agentRoot, bare filenames stay in the managed directory.
• Sentinel output.format now works — The output.format field ("text" | "jsonl") was also silently ignored. It now controls two things: (1) the auto-generated file extension when no explicit path is set (.md or .jsonl), and (2) the write format for text outputs — "jsonl" wraps each text output as a JSON line with text, timestamp, and sentinelId fields, useful for downstream parsing. The "json" option was removed to avoid confusion (it produced JSONL, not valid JSON). A new validation refinement rejects configs that set both structuredOutput and output.format, since structured output determines its own format.
• Structured output E2E tests selecting deprecated model — Two E2E tests (Schema file loading, Cost tracking) were failing because dynamic model selection grabbed anthropic/claude-3-5-haiku-latest (deprecated by Anthropic) before anthropic/claude-haiku-4-5. Fixed to prefer the current model name.

Platform-Specific Instructions

macOS

• Apple Silicon (M1/M2/M3): hankweave-darwin-arm64
• Intel: hankweave-darwin-x64

After downloading:

xattr -d com.apple.quarantine hankweave-darwin-arm64
chmod +x hankweave-darwin-arm64
./hankweave-darwin-arm64 --help

Linux

• x64: hankweave-linux-x64
• ARM64: hankweave-linux-arm64

chmod +x hankweave-linux-x64
./hankweave-linux-x64 --help

Windows

• x64: hankweave-windows-x64.exe

.\hankweave-windows-x64.exe --help

Hankweave v0.5.4

Installation

Via npm:

npm install -g hankweave
# or
npx hankweave --init

Via Standalone Executable:
Download the binary for your platform below, make it executable, and run it.

What's Changed

[0.5.4] - 2026-02-20

Added

Changed

Fixed

• Release CI: all 5 platform builds now succeed — darwin-x64 and linux-arm64 builds were failing because bun install only fetches the codex binary for the host architecture. Cross-compilation targets now fetch the correct binary via npm pack before building. Also survived the retirement of macos-13 (Intel) runners along the way.

Platform-Specific Instructions

macOS

• Apple Silicon (M1/M2/M3): hankweave-darwin-arm64
• Intel: hankweave-darwin-x64

After downloading:

xattr -d com.apple.quarantine hankweave-darwin-arm64
chmod +x hankweave-darwin-arm64
./hankweave-darwin-arm64 --help

Linux

• x64: hankweave-linux-x64
• ARM64: hankweave-linux-arm64

chmod +x hankweave-linux-x64
./hankweave-linux-x64 --help

Windows

• x64: hankweave-windows-x64.exe

.\hankweave-windows-x64.exe --help

Hankweave v0.5.0

Installation

Via npm:

npm install -g hankweave
# or
npx hankweave --init

Via Standalone Executable:
Download the binary for your platform below, make it executable, and run it.

What's Changed

[0.5.0] - 2026-02-17

Added

• Shim idle timeout — Configurable timeout that aborts agent harnesses when no events are received within a deadline. Prevents runs from hanging indefinitely on stalled agents. Configurable per-codon (shimIdleTimeout), per-hank (in overrides), or runtime-wide (--shim-idle-timeout CLI flag / hankweave.json). Shims default to 120s.
• Environment metadata in execution-meta.json — Execution metadata now records hankweave version, invocation method (binary/bun/node/deno), platform, arch, OS release, and runtime version. Schema version bumped to 1.1.0.
• Wizard credit validation — The welcome wizard now makes a lightweight API call to verify credentials have working credits before launching the demo, catching dead keys and exhausted balances up front.
• Wizard model fallback — The demo wizard now adapts to whatever provider the user has available (Anthropic → OpenAI → Google) instead of failing when the user lacks Anthropic credentials.
• Wizard completed-run detection — If the user already ran the demo with the same data folder, the wizard detects the prior completed run and offers to start fresh.

Changed

• Idle timeout validation — --idle-timeout and --shim-idle-timeout CLI values are now validated (must be positive finite integers within bounds). Previously, invalid values like NaN could cause instant aborts.
• Error tracking enrichment — Original Error objects are now preserved at all failure sites instead of creating synthetic errors at the capture point. Correlation context (runIdHash, codonIdHash, codonPosition, model, hankweaveVersion) added for debugging.
• Windows CI timeout budgets — Increased timeout budgets for unit, integration, and E2E tests on Windows to accommodate PowerShell overhead and file locking delays.

Fixed

• False "completed" status on billing errors — The Claude SDK returns billing failures as subtype: "success" with is_error: true. The runtime now distinguishes real success from disguised API errors, correctly marking codons as "failed" instead of "completed".
• Idle timeout timer leak — Fixed a timer leak in withIdleTimeout when iterator.next() rejects before the timeout fires.
• NPX init E2E flakiness — Resolved cache corruption and timeout issues causing intermittent init test failures.
• Deno version missing from startup banner — getRuntimeVersion() now correctly reports the Deno version instead of falling through to Node.js detection.

Platform-Specific Instructions

macOS

• Apple Silicon (M1/M2/M3): hankweave-darwin-arm64
• Intel: hankweave-darwin-x64

After downloading:

xattr -d com.apple.quarantine hankweave-darwin-arm64
chmod +x hankweave-darwin-arm64
./hankweave-darwin-arm64 --help

Linux

• x64: hankweave-linux-x64
• ARM64: hankweave-linux-arm64

chmod +x hankweave-linux-x64
./hankweave-linux-x64 --help

Windows

• x64: hankweave-windows-x64.exe

.\hankweave-windows-x64.exe --help

Hankweave v0.4.1

Installation

Via npm:

npm install -g hankweave
# or
npx hankweave --init

Via Standalone Executable:
Download the binary for your platform below, make it executable, and run it.

What's Changed

• 2026-02-13

Added

• Rig setup telemetry events — rig_setup_completed and rig_setup_failed are now captured by the telemetry collector. Previously the event names were defined but no code generated them.
• rollback-completed idle reason — New server.idle reason emitted after rollback completes without autostart, so TUI and clients know the server is waiting for input.
• Sentinel codon.completed drain test suite — 6 new unit tests verifying sentinels watching codon.completed fire correctly for all execution strategies.
• TUI shutdown summary box — When a hank finishes (success, failure, or user interrupt), the TUI now shows a prominent summary box with: codon count, total cost, duration, full clickable workspace path, and output directory path. On first successful run, includes a one-time star nudge for the GitHub repo.
• TUI activity heartbeat — After 10 seconds of no output (e.g., during large file generation), the TUI shows a ticking Working... Xs counter on the same line so it doesn't appear frozen. Clears automatically when new output arrives.
• TUI resume hint on quit — When the user presses q to interrupt a run, the TUI shows the hankweave --execution <path> command to resume.
• Validation run hint — After successful --validate, shows a copy-pasteable hankweave <config> <data_path> command. Uses the original URL for remote hanks.
• outputDirectory in server.ready event — The output directory path is now included in the server.ready WebSocket event so TUI and clients know where outputs will be copied.
• First-success tracking — firstSuccessAt field added to ~/.hankweave/telemetry.json to track when a user's first successful hank run occurred (used for the star nudge).

Changed

• TUI rollback now auto-restarts execution — Rollback commands from the TUI ([r] menu) now send autoRestart: true instead of false. If config.autostart is enabled (the default), execution resumes automatically from the rollback point. Users running with --no-autostart are not affected.
• TUI idle state display — server.idle events now render as a prominent "Waiting for Input" box with contextual command hints (e.g., [n] start next codon [r] rollback [q] quit) instead of dim text. Hints adapt based on why the server is idle (rollback, codon completion, startup, all-done).
• TUI rig setup events — rig.setup.completed and rig.setup.failed now render properly (green check with duration / red cross with failure type) instead of showing as "Unknown Event" with raw JSON.
• Wizard demo output path — The demo wizard now shows the full resolved path for the output directory (Cmd/Ctrl-clickable) instead of a relative ./hankweave-demo-output.
• Remote hank cache: hash-based freshness — Branch caches now validate via git ls-remote (a single lightweight network roundtrip) to check if the remote tip has new commits, replacing the previous 1-hour TTL. Tags/commits remain cached indefinitely. Falls back to cache if offline.
• Strict hank file validation — hankFileSchema now uses .strict() to catch unrecognized root-level fields (e.g., outputFiles at hank root instead of codon level). Error messages detect codon fields placed at root and suggest where to move them.
• CLI: single remote URL treated as hank path — A single positional argument starting with https://, http://, or git@ is now correctly treated as a hank path instead of a data path. Fixes --validate and bare execution of remote hanks.
• Emoji-free CLI output — Replaced all emoji characters (🔍📁🏃❌🌐📦✨⚠️🎮) in startup, validation, and error output with ASCII symbols (>, ✓, ✗, !, +) for a consistent terminal aesthetic.
• Validation summary box alignment — Fixed "GOOD TO RUN!" box top border width to match the bottom border.
• Sentinel docs improved — Added execution model section (blocking vs non-blocking at codon boundaries), "note-takers not editors" capabilities callout, sentinel-vs-codon guidance, unidirectional data flow pattern, event routing rules, and shared-file antipattern warning. Driven by customer feedback on sentinel complexity.
• Sentinel config reference updated — Event types table split into routed/not-routed sections with warning that sentinel.* events never fire triggers.
• Execution flow docs updated — Added "Routed to Sentinels" column to event categories table and two-phase drain description.
• Public README improved — Expanded FAQs with new sections (Understanding Hankweave, Using Hanks), added MCPs rationale, codon data flow, information sharing between codons, and interactive-vs-hermetic comparison with Claude Code.
• Release script overhauled — Two-phase release with full dry-run validation before any changes. --dry-run flag validates the entire pipeline (merge feasibility, schema generation, typecheck, lint, tag availability). --yes flag enables headless/agent execution. Automatic rollback on failure.
• Public sync: .github/actions stripped — Composite actions (setup-environment, run-tests, dump-test-logs) are now excluded from the public repo snapshot since they're only used by private CI.
• Public sync: broken scripts removed from package.json — release:patch, release:minor, release:major scripts are now stripped during public transformation since release.ts is not included.

Fixed

• Sentinels watching codon.completed now reliably fire — Added a second sentinel queue drain after the codon.completed event emission. Previously, sentinels triggered by codon.completed had their work silently dropped during unload. Affects all execution strategies (immediate, debounce, count, timeWindow).
• Telemetry shutdown: run_started, run_completed, $ai_trace events missing — The RunCompleted/RunFailed state transitions clear currentRunId, causing getCurrentRun() to return null when telemetry tried to build the shutdown payload. Run data is now captured before the transition.
• Telemetry E2E tests disabled by Cursor's CI=1 — Happy-path test now clears the CI environment variable so telemetry debug mode works when running from Cursor's terminal.
• Structured output E2E test calling Opus instead of Haiku — Model auto-discovery now prefers haiku before falling back to first-available, preventing 15s timeouts and unnecessary spend.
• E2E event integrity false positive — Relaxed duplicate assistant.action detection threshold from >1 to >3, since agents legitimately produce identical thinking/message patterns across codons.
• Output directory path resolution — Absolute paths passed via -o (e.g., -o /Users/.../output) were concatenated onto CWD by path.join, creating deeply nested directories instead of writing to the intended location. The outputDirectory is now resolved to an absolute path once at config assembly time using path.resolve. Also affects the wizard demo flow.
• Output file copy source — outputFiles glob patterns were resolved against executionPath (the outer system directory) instead of agentRootPath (where the agent actually works). Since execution isolation (v0.2.0) moved agent work into agentRoot/, the globs matched zero files and nothing was copied. Changed the copyFiles source to agentRootPath.
• TUI shutdown summary timing — The "Run Complete" summary box now prints on WebSocket disconnect (always last) instead of on the "All codons completed" info event (which fired before sentinel shutdown output). A brief one-liner provides immediate feedback when codons complete.

Platform-Specific Instructions

macOS

• Apple Silicon (M1/M2/M3): hankweave-darwin-arm64
• Intel: hankweave-darwin-x64

After downloading:

xattr -d com.apple.quarantine hankweave-darwin-arm64
chmod +x hankweave-darwin-arm64
./hankweave-darwin-arm64 --help

Linux

• x64: hankweave-linux-x64
• ARM64: hankweave-linux-arm64

chmod +x hankweave-linux-x64
./hankweave-linux-x64 --help

Windows

• x64: hankweave-windows-x64.exe

.\hankweave-windows-x64.exe --help

Hankweave v0.3.3

Installation

Via npm:

npm install -g hankweave
# or
npx hankweave --init

Via Standalone Executable:
Download the binary for your platform below, make it executable, and run it.

What's Changed

[0.3.3] - 2026-02-12

Added

Changed

Fixed

[0.3.2] - 2026-02-12

Added

Changed

Fixed

[0.3.1] - 2026-02-12

Added

Changed

Fixed

[0.3.0] - 2026-02-12

Added

• Welcome wizard — First-run experience when running hankweave with no arguments

  • Animated 4D tesseract splash screen with depth-aware teal/amber color gradient
  • Automatic environment detection (Claude Code, Codex, Gemini CLI + API keys)
  • Bordered environment panel with clear found/not-found status and help links
  • Menu: try demo hank, init new hank, open docs/GitHub/launch page
  • Demo hank flow with time/cost warning (~5-10 min, ~$0.50-1.00), data folder picker, and -o output copy
  • Init hank flow with file tree preview and next-steps guidance
  • Non-TTY fallback with static text for CI/piped environments
  • Runner detection (npx vs bunx) for accurate command suggestions
  • Uses @clack/prompts for interactive elements

• Shared color palette (server/wizard/colors.ts)

  • 24-bit RGB color functions anchored to the tesseract's amber/teal scheme
  • Box-drawing helper with rounded corners and optional title
  • ANSI-aware string width utilities (visibleLength, padVisible)

• .gitignore in init template — Scaffolded hanks now include .gitignore for .hankweave/, logs, and node_modules/

• Example hanks and learning materials

  • Clausetta example hank (shim builder) with full eval suite
  • Plan-gen-v2 example hank (general planning workflow)
  • hank-basics.md guide

• Force shutdown command (server.force_shutdown) — new WebSocket command that immediately kills agent processes and exits. Clients can send this during a graceful shutdown to skip the wait.

• Second-press force quit in TUI — pressing q or Ctrl+C a second time during graceful shutdown triggers an immediate force exit with SIGKILL escalation. The TUI now shows "press q again to force quit" during shutdown.

• Shutdown info event — server emits an info event to all connected clients when entering graceful shutdown, enabling external clients to show status and send server.force_shutdown if needed.

Changed

• CLI startup reordered — Welcome wizard, --init, --attach, and --help now exit early before heavy config resolution and SDK checks
• Init template README updated — Accurate file list, full model examples, running instructions, and learn-more links
• Banner links updated — Blog link replaced with launch page (southbridge.ai/hankweave)
• README.md trimmed — Detailed documentation moved to docs site
• SIGINT/SIGTERM signal handling — second signal now escalates to force shutdown instead of being silently ignored.

Fixed

• Basic TUI box overflow — drawBox() now caps width at min(terminalWidth, 120) and word-wraps long content lines. Fixes sentinel output boxes stretching to hundreds of columns.
• Tesseract aspect ratio — Side-by-side mode no longer squishes the tesseract vertically. scY is now derived from scX with character aspect ratio correction instead of scaling independently with terminal height.
• Remote hank branch fallback — main → master fallback now works on cached repos (previously only worked on initial clone). Fixes "pathspec 'main' did not match" errors on second fetch.
• HTTP status code — Non-WebSocket requests to the server now return 400 instead of 426.
• Telemetry shutdown — sendRunTelemetry now uses getCurrentRun() instead of looking up by a potentially-cleared run ID.
• Critical: Claude Code abort controller never reached the SDK — the abort controller was created after building SDK options, so the SDK received undefined and created its own internal controller. kill() was aborting a controller the SDK didn't know about. The child process never received SIGTERM via abort. Fixed by creating the controller before building options.
• Orphaned agent processes on shutdown — ClaudeAgentSDKManager.kill() now properly waits up to 5 seconds for the SDK query to complete after aborting, instead of returning after 100ms. This ensures the child process has time to exit before the server calls process.exit().
• ShimProcessManager SIGKILL escalation was dead code — the kill wait loop checked ChildProcess.killed (true when signal is sent) instead of actual process exit. The interval resolved on the first tick and SIGKILL was never reached. Fixed to check whether the process reference has been cleared by the exit event handler.

[0.2.3] - 2026-02-10

Added

• GPT-5.3 Codex model support (PR #105)

  • Added gpt-5.3-codex-high and gpt-5.3-codex-xhigh model definitions
  • Reasoning effort specifiers parsed from model ID suffix (e.g., -high, -xhigh)
  • Load-time assertions verify model resolution correctness

• Anonymous Telemetry (ENG-12, PR #100)

  • Privacy-preserving usage analytics via self-hosted PostHog

• New server events

  • rig.setup.completed — emitted after rig setup with duration, command count, and checkpoint status
  • rig.setup.failed — emitted on rig setup failure with classified failure type (command_failed, timeout, other)
  • loop.iteration.completed — emitted per loop iteration with duration, cost, token usage, and termination reason

Changed

• Codex SDK upgraded to v0.98.0 (PR #104, PR #105)

  • Updated @openai/codex-sdk from ^0.87.0 to ^0.98.0
  • New webSearchMode parameter support (replaces boolean webSearchEnabled)
  • Config overrides support via new config constructor option with TOML serialization
  • Thread resume (args.threadId) now passed before --image flags (ordering fix)

• Codex shim streaming rewritten for incremental deltas (PR #104)

  • Shim now tracks lastEmittedAssistantText and lastEmittedReasoningByItemId to compute true deltas
  • Previously re-emitted full accumulated text on each update, causing duplicate content in streaming output
  • Reasoning text deltas now tracked per-item via Map for correct multi-item reasoning streams

• CLI startup reordered: config resolution now happens before mode branches (init, attach, validate, cleanup) so all code paths have access to resolved config and telemetry

Fixed

Platform-Specific Instructions

macOS

• Apple Silicon (M1/M2/M3): hankweave-darwin-arm64
• Intel: hankweave-darwin-x64

After downloading:

xattr -d com.apple.quarantine hankweave-darwin-arm64
chmod +x hankweave-darwin-arm64
./hankweave-darwin-arm64 --help

Linux

• x64: hankweave-linux-x64
• ARM64: hankweave-linux-arm64

chmod +x hankweave-linux-x64
./hankweave-linux-x64 --help

Windows

• x64: hankweave-windows-x64.exe

.\hankweave-windows-x64.exe --help

Hankweave v0.2.2

Installation

Via npm:

npm install -g hankweave
# or
npx hankweave --init

Via Standalone Executable:
Download the binary for your platform below, make it executable, and run it.

What's Changed

• 2026-02-09

Added

Changed

Fixed

• Codon env variables not available in rig setup and beforeCopy commands (PR #103)
  • Codon env variables were only passed to the Claude/shim process, not to rigSetup or beforeCopy commands
  • Shell expansions like ${MY_VAR} in rig commands now correctly resolve instead of expanding to empty strings
  • runCommand() now accepts and forwards codon env variables to spawn()

Platform-Specific Instructions

macOS

• Apple Silicon (M1/M2/M3): hankweave-darwin-arm64
• Intel: hankweave-darwin-x64

After downloading:

xattr -d com.apple.quarantine hankweave-darwin-arm64
chmod +x hankweave-darwin-arm64
./hankweave-darwin-arm64 --help

Linux

• x64: hankweave-linux-x64
• ARM64: hankweave-linux-arm64

chmod +x hankweave-linux-x64
./hankweave-linux-x64 --help

Windows

• x64: hankweave-windows-x64.exe

.\hankweave-windows-x64.exe --help