Skip to content

Harden tool contracts after long-running agent session - #12

Merged
halqme merged 18 commits into
mainfrom
fix/session-orchestration-failures
Aug 12, 2026
Merged

Harden tool contracts after long-running agent session#12
halqme merged 18 commits into
mainfrom
fix/session-orchestration-failures

Conversation

@halqme

@halqme halqme commented Aug 12, 2026

Copy link
Copy Markdown
Owner

Summary

This PR turns repeated failures observed in a long-running Luna session into explicit tool and delegation contracts instead of relying on the model to infer them.

  • make Astrolabe inspect_many a true read batch across files, while keeping replace_many single-file
  • keep Astrolabe continuations usable across internal handle-cache eviction
  • clarify Astrolabe schema/guidance for declaration lookup, source inspection, and candidate limits
  • expose Agent-Team's supported read-only tools directly in its tool schema
  • distinguish shared-workspace change observation from writer provenance in delegate-task
  • add regression tests/evals for the observed failure modes
  • add repository CI for lint, type checking, and tests

Motivation

The session completed successfully because the harness kept driving implementation and verification to completion, but it also exposed systematic errors that brute-force retries do not solve well: Astrolabe read-side protocol surprises, hidden Agent-Team tool constraints, and incorrect attribution of shared-worktree file changes to a child writer.

These are deterministic contracts, so they should be made explicit or enforced by the harness/tooling rather than left to model capability.

Changes

Astrolabe

  • inspect_many now reads selected continuations concurrently even when they span files. It proposes replace_many only when every selected target belongs to one file, preserving the existing single-file mutation contract.
  • Continuations retain a handle snapshot and can reactivate a handle evicted from the bounded live cache. Cache pressure alone therefore no longer turns an otherwise valid continuation into invalid_continuation; explicit deletion, path clearing, and session shutdown still invalidate it.
  • Tool descriptions now make the locate declaration scope, inspect path/continuation distinction, cross-file batch-read behavior, and maxCandidates range visible to the model. no_candidates also points to search or ordinary text retrieval when locate is the wrong primitive.

Agent-Team

  • The supported read-only tool set is now an enum in the tool schema instead of a free-form string list. The runtime check remains as defense in depth and reports the exact supported set when bypassed.

Delegation

  • delegate-task now states that a file-change notification in a shared workspace is evidence that the workspace changed, not writer provenance. Ownership violations require attributable evidence; otherwise concurrent writers must be serialized or isolated.
  • A regression eval covers the observed parent-edit / child-notification misattribution case.

CI

  • The root package pins Bun 1.3.14 through packageManager and exposes a single check command.
  • bun run check runs root Oxlint and then every workspace's existing check script sequentially. This keeps each workspace's own test-runner contract while avoiding interference between process-heavy test suites.
  • GitHub Actions runs on pull requests and pushes to main, installs Node 24 and Bun, performs a frozen-lockfile install, and executes the root check.
  • background-process now invokes its declared test script from check, so its detached-process lifecycle tests execute under Node as intended rather than inheriting the Bun test runner.
  • The lightweight plan extension opts out of the shared Node global type set because it does not use Node globals; this removes an otherwise undeclared @types/node requirement from that workspace.
  • format:check is available separately but is not part of the required CI gate yet; formatting remains handled by the repository's existing formatter/pre-commit convention.

Verification

Regression coverage added for:

  • continuation survival across LRU eviction and invalidation on explicit clear/delete
  • cross-file inspect_many without a cross-file mutation suggestion
  • Agent-Team read-only tool schema and direct-call error reporting
  • shared-workspace provenance handling in delegate-task evals

The PR diff was reviewed against current main, including removal of an unrelated test change introduced while editing. The Agent-Team schema change was checked against Pi v0.84.1's StringEnum contract.

GitHub Actions CI now passes on this PR. The successful run performs a frozen Bun install, root Oxlint, and every workspace's existing check script, including 69 passing Astrolabe tests and 12 passing Agent-Team tests.

@halqme
halqme marked this pull request as ready for review August 12, 2026 06:36
@halqme
halqme merged commit e38368d into main Aug 12, 2026
1 check passed
@halqme
halqme deleted the fix/session-orchestration-failures branch August 12, 2026 07:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant