From AgentOS to AssemblyZero: A Deterministic Refactor and Modernization

Today marks a significant milestone in the evolution of this framework. We successfully executed a project-wide hard-fork and rename, transforming AgentOS into AssemblyZero. This wasn't just a find-and-replace exercise; it was a comprehensive audit, cleanup, and modernization of the entire stack.

Here is how we achieved a 100% stable build and reduced build noise by over 99% in a single session.

1. The Rename Protocol: Preserving History

Renaming a package is dangerous when your project relies on immutable audit trails. We have thousands of files in docs/audit and docs/lineage that represent historical records.

The Strategy:

• Isolation: We used the Worktree Isolation Rule to perform the refactor in a separate filesystem space.
• Selective Targeting: We wrote a custom Python script to perform case-sensitive string replacements (agentos → assemblyzero, AgentOS → AssemblyZero).
• Immutable Zones: We explicitly excluded docs/audit/, docs/lineage/, and docs/session-logs/ from the refactor, ensuring our historical "Chain of Custody" remains intact while the active code evolved.

2. Diagnosing the "Ghost" Failures

After the rename, the build initially failed. As a Senior QA Engineer, I had to diagnose why three specific tests were red in a supposedly "green" codebase.

• Config Drift: test_110 failed because .gitignore still referenced .agentos/. The test expected the new namespace.
• Assertion Drift: Two implementation tests failed because they performed exact string matching on error messages. Recent updates to our implement_code node added sophisticated retry logic, changing "Claude API error" to "API error after 3 attempts".

The Fix: We modernized the test suite to match the improved, more descriptive error reporting of the actual engine.

3. The Dependency Audit: Lean Engineering

We realized the pyproject.toml had accumulated "cruft" from previous experiments. Using an adapted version of our 0911 Audit Protocol, we performed a top-down usage analysis.

• Identifying Unused Deps: We confirmed that pywinpty, tzdata, openpyxl, and wexpect were no longer imported in the core.
• Side-car Compatibility: We verified that Unleashed (our autonomous coding script) manages its own pywinpty dependency, making it safe to remove from the primary framework.
• Pruning: Removing these 6 packages automatically triggered Poetry to prune sub-dependencies like psutil and pywin32, resulting in a significantly leaner environment.

4. Modernizing to LangGraph 1.0

The most impactful part of this session was the decision to move to the LangChain 1.2 / LangGraph 1.0 stack.

Operating on Python 3.14 (released Oct 2025) had introduced significant "warning noise"—297 warnings per test run, primarily due to the deprecation of asyncio.iscoroutinefunction.

The Breakthrough: By performing a deterministic group update of the LangChain stack, we discovered that the library maintainers had already resolved these 3.14 compatibility issues in the new major versions.

5. Deterministic Loops: Moving from Choice to Code

One of the key realizations of this session was that dependency maintenance should not be a "selective" process prone to human error.

By attempting a "One-by-One" update strategy, we successfully modernized 28 outdated packages. Crucially, the process identified a hard conflict where the latest google-genai SDK is incompatible with websockets 16.0.

Because we followed a deterministic "Update → Test → Commit/Rollback" loop, we were able to keep the build green while moving as many packages forward as possible. We are now formalizing this "Safe Loop" into an automated tool to ensure no utility package is ever left behind due to agent selection bias.

6. Lessons Learned

1. Worktrees are Non-Negotiable: Performing these heavy operations in isolated worktrees allowed us to fail fast, rollback, and re-attempt without ever leaving the main branch in a broken state.
2. Trust Exit Codes: Our 0911 protocol emphasizes trusting pytest exit codes over LLM interpretation. This prevented us from merging a "mostly working" update.
3. Upstream Awareness: In 2026, staying on the edge of the LangChain/LangGraph ecosystem is the most effective way to resolve Python core deprecation noise.

The project is now officially AssemblyZero. We are leaner, modern, and 100% green.

The Turtle Moves.