v0.3.1

Finish or reconcile running attempts before downgrading to 0.3.0.

• Study-scoped executor container names (#149, product fix): a container name now derives from the study id together with the attempt id, so two studies that repeat one attempt identity on the same executor no longer collide and end unknown with container isolation verification failed. Each stage record stores the name it launched with; a record written before this change carries none and keeps resolving ares-<attemptId>-<stage>[-<pipelineStage>] for inspect, reconcile and absence confirmation. Isolation verification still refuses a foreign or leftover container that carries the new name, and the watchdog, cleanup and adoption paths use the recorded name rather than recomputing one. No record version changes and existing attempts stay readable.

• Reuse request warning (#150, product fix): eligible requests outside a matching investigation run still run fresh and return additive, non-persisted warnings with code outside-investigation, cause and nextStep. CLI/MCP result shapes are otherwise unchanged; no new command or flag is added.

• Task snapshot archive (#148): ares attempt run now creates the task archive with the shared content-only tar rule (COPYFILE_DISABLE=1 tar --no-xattrs, also used for stage logs) and checks every streamed member against the staged task files. An AppleDouble ._* member or any member that differs from the staged files is refused by name, so a macOS controller no longer ships extended-attribute metadata to a Linux executor. The frozen task tree hash is unchanged and pinned by a test.

• Reuse rematerialization r2 preparation (#63 T3): export existing source/fault helpers without changing their implementations, add an arm-neutral fresh/eligible fixture runner and a separate create-once superseding setup receipt. Per-case stage hashes and fault states must equal the original amendment; all frozen inputs, labels, v1/v2 seals and the original Reuse receipt stay unchanged. Phase parent CPU, subprocess unknowns and wall clocks stay distinct. This preparation step contains no measurement; the completed T3 runs are reported separately below. The r2 developer receipt names the original setup seal as superseded before use; invalid r2 receipts refuse instead of falling back. Earlier setup verification may report changed code and never rewrites history.

• Reuse admission (#64, product fix): a candidate stage is no longer reused from a source attempt that is not succeeded. A cancelled or unknown attempt that left its sealed stages intact used to produce a verified hit; it now misses as ineligible-source and the stage runs fresh. A valid digest alone never makes an interrupted or semantically stale source eligible, so the rule only narrows reuse: no stage is added, no stored byte or format changes, and a hit from a succeeded source is unaffected.

• Reuse source rematerialization amendment (#63 T3a): integration-check reports the Reuse arm as integrated-rematerialized-source. A deterministic, code-bound setup rebuilds each case's source stage outputs from that case's own frozen source.workload with the v1 workload arithmetic, at every declared seed, as the producer's own payload bytes, and a separate create-once receipt seals the setup. All ten cases that declare a source are rebuilt: four healthy and six rebuilt healthy and then given their own declared fault, so the fault suites reach the reuse path instead of being refused by the setup. Corruption changes a retained payload after the seal so the sealed manifest hash no longer matches; pruning disposes the rebuilt stages through the retention prune path; an interrupted source is recorded cancelled or unknown after its candidate stages were sealed. The admission check is a fake-runner test per fault and requires the reuse path itself to refuse all three stages with its own reason and admit none. The seal binds the setup modules including the fault-injection code, the corpus index, all twelve input hashes, the per-case workload and stage hashes, inherited thresholds/denominators and the immutable v1 parent; freeze-reuse-rematerialization and verify-reuse-rematerialization verify it and refuse drift. Evaluator labels are never read, so no expected file enters the seal. Outcomes stay null with zero trial executions, and the setup's own cost is recorded separately in the materialization dimensions while every other clock stays unknown.

• Supervision snapshot integration (#63 T2b): pin the closed exported snapshot with source-owned evaluated triples and evaluatedSuppressed. Independent producer-generated unit vectors replace hand-authored snapshots; frozen v1/v2 corpora, labels, receipts and baseline bytes stay unchanged. Absence scoring requires exact rule/task/revision coverage, with gaps and retention overflow remaining insufficient. Intent none requires all three rules; wrong/false proposal burden remains counted from presence, and zero helpful actions reports 0. No treatment trial or runtime hub/model/network call is added by this reader. Its unsealed fixture envelope requires evaluated and evaluatedSuppressed; earlier incomplete envelopes refuse with a restore-from-producer next step.

• Supervision corpus v2 amendment (#63 T2c-B): separate create-once freeze/verify receipt binds the approved v2 protocol/join method, inherited budgets/thresholds/denominators, all input/expected bytes and the immutable v1 parent. Integration-check keeps v1 unsupported and adds twelve format-covered v2 cases with null outcomes and zero runs. The intent join uses action/rule/task/current revision, never producer trigger strings; the 2026-11-10 ruling separates exclusive case outcomes from observed wrong/false proposal burden. Always-wrong proposals consume the false-proposal budget even when missing desired-rule coverage leaves the case insufficient. Absence scoring remains pending source-owned evaluated coverage; no evaluator, treatment, hub or model call is added.

• Execution evaluation (#63 T3/T4): preserve immutable paired Diagnose/Reuse and Supervision v2 shadow receipts and publish the evidence-bound disposition report and closeout. Diagnose is insufficient evidence, Reuse is restricted after failed performance gates, and Supervision is at most retained in shadow mode. Lineage remains read-only utility, eligible reuse stays off by default with explicit operator opt-in, and advisory mode remains off without separate authorization. Human timing and live/native/account benefits are not inferred from synthetic observations.

Install

bun add -g @staix/agent-research@0.3.1

Published with npm OIDC trusted publishing and provenance. The validated tarball and its tag/commit/SHA-256 manifest are attached. SHA-256: dbd850494a51393bd5ce1345a0094041956528a389c283575928211a529068c8.

v0.3.0

N-1 compatibility for 0.3.0 is against 0.2.1, the latest published patch of the 0.2 minor line. The installed-package bun scripts/n1-check.ts check passed on the prepared 0.3.0 candidate; the existing networked n1 CI job repeats it and remains required by ci-ok.

• N-1 CLI: all 60 published 0.2.1 commands remain, with every prior usage word retained in order; 30 commands are additive (90 total). Additions cover retention, skill checks, harness rounds/streams/transitions, experiences, reviewed lessons, lineage, executor input hashes, literature queries/flow/card exchange, review checklist and paper plans. Optional input/GPU, reuse, named-stage log, query-intent and screening-code controls are additive. New source checks and default v2 skill evidence can require a compatible source reader or revised input; this is not a promise that every earlier write payload or readiness judgment behaves identically.
• N-1 MCP tools: all 55 published tools keep their manifest readOnly values; 30 tools are additive (85 total): ares_retention_inspect, ares_retention_prune, ares_lesson_propose, ares_lesson_list, ares_lesson_check, ares_lesson_decide, ares_skill_check, ares_harness_close, ares_harness_contrast, ares_harness_compose, ares_harness_adopt, ares_harness_stream_set, ares_harness_stream_show, ares_experience_select, ares_experience_freeze, ares_experience_check, ares_harness_set, ares_harness_show, ares_harness_import, ares_lineage_show, ares_lineage_compare, ares_executor_inputs_hash, ares_lit_queries, ares_lit_flow, ares_lit_card_export, ares_lit_card_import, ares_lit_card_list, ares_review_checklist, ares_paper_plan_set, ares_paper_plan_show. Existing schemas gain optional inputs or wider versioned definitions. Skill propose/decide also advertise openWorldHint: true while retaining readOnly: false. The N-1 gate checks names and manifest readOnly values, not complete schema or annotation equivalence.
• N-1 study/ledger formats: 0.3.0 reads 0.2.1 survey/experiment studies (study v1/v2), ledger-event v1 and the existing native formats without a read-time migration. The installed-package check confirms unchanged study/ledger bytes and the no-input protocol hash, design binding and approved gate; 0.2.1 also reads a newly written study v2 unchanged. When encountered by their respective readers, 0.2.1 refuses stage protocol v2, attempt v2/v3, skill-proposal v2 and paper-evidence v2; it also refuses the new fields in closed protocol, executor, scope and plan-step schemas. Paper-plan v1/v2 and the other new namespaces/settings below have no 0.2.1 reader, so those files are ignored rather than version-refused. Use 0.3.0 for the new semantics; no automatic downgrade or blanket older-reader enforcement is promised.

Newer data encountered by 0.2.1	Compatibility boundary
Protocol v2 stages, attempt v2/v3, skill-proposal v2, paper-evidence v2	Their old readers refuse the unsupported version without rewriting the record. Paper evidence v2 is refused by old build/current-build and study-export paths.
Protocol v1 inputs; executor v1 gpu or retentionCapBytes; scope exclusionCodes; plan-step intent, reuse or force-fresh	Old closed-field validators refuse them. Formats retaining v1 does not make these fields usable by 0.2.1.
Paper-plan v1/v2, harness round/transition/stream/experience/fixture-projection v1, lesson proposals v1, executor-local retained artifacts/reuse metadata	0.2.1 has no reader for these namespaces. It ignores their files and unrelated new ledger-event kinds; it does not enforce routing, writing points, harness gates, disposal or reuse semantics. Planned/staged studies require the newer reader.
study.toml paper/review settings	Published 0.2.1 ignores the file, including [review]; refusal by an intermediate unpublished settings reader is not a published N-1 guarantee.
Candidate/search/screen optional metadata; v1 attempt verifiedInputs, gpuDevices or freshRequest	Old readers can ignore optional metadata; acceptance is not equivalent interpretation. Protocol/executor configuration checks remain separate barriers.
Review repair/section/checklist.survey; card extension/reuse fields	Old strict authoring commands refuse the new inputs; stored review replay and direct card readers ignore extra fields. They do not implement current review/card semantics or the new physical-card refusal.

The networked N-1 check covers the manifest and representative study/protocol reads above, not every new format or operation. Feature-specific refusal/ignore distinctions are grounded in the published 0.2.1 source and the offline compatibility tests. New checks may add findings or make an earlier build stale while its stored format remains readable.

• Harness guidance mapper (#66): read-only decoding of the agent-hub GuidanceReadResult public metadata contract at 50100a8 alongside the existing ares fixture format. Keeps native variant/experiment/task/layer/section/digest identity, bounded lifecycle and evidence metadata, and explicit unavailable results. Rationale shape/bounds are checked but its text is omitted pending agent-hub task #822; synthetic PII-shaped canaries cover outputs and errors. Strict ahub execution-reference decoding never enables local-source fallback, skill evidence, hub resolution or live probe import (#1226 remains pending).

  • N-1 CLI: command names, usage and existing fixture operations stay unchanged; no new command is exposed.
  • N-1 MCP: tool names, schemas and annotations stay unchanged; no external resolver is added.
  • N-1 study/ledger formats: no format/version or stored-record rewrite; existing ares reference/projection bytes, round bindings and denominators remain unchanged. New producer metadata is decoded read-only and carries no probe/handoff assurance.

• Supervision treatment record integration (#63 T2b): integration-check now retains all 36 frozen cases and reports the agent-hub#1221 T1 record consumer pinned to bc6f46b077dd3a255debaee8152fa17f1f13b79c. All 12 frozen Supervision task-state payloads remain unsupported rule facts, with per-case reason/hash coverage and helpful/false/missed left unknown (null), not zero or fabricated success. Separate synthetic record vectors exercise the closed reader/scorer without importing or executing hub rules. Helpful/false scoring requires a present matching observation; absence is no-evaluation-coverage, and missed/correct-non-trigger metrics remain null pending source-owned evaluation coverage. Batch counters or caller-asserted evaluated lists cannot establish that coverage. No treatment trial, record receipt or effect path is launched; person decisions remain literal 0. Corpus amendment/sealing and T3 launch remain separate work under their own authorization.

  • N-1 CLI: no command/default switch change; the existing check-only integration output adds Supervision coverage and producer binding.
  • N-1 MCP: no tool, schema or annotation change.
  • N-1 study/ledger/receipt formats: unchanged; prior receipts stay readable and are not rewritten. The T1 seal and frozen corpus/expected files and T2a baseline bytes remain unchanged; new source is bound per run. Tagging and publication follow the separate release workflow.

• Extraction cards are read as physical files: every reader, including lit card list, lit card export, lit card import, paper check's cited-card pass and point evidence, refuses a card path that is a link or special file with the cause and the next step instead of following it out of literature/cards, and a dangling link no longer reads as a missing card. A regular card reads as before and an absent card is still missing.

  • N-1 CLI: no command or usage change; a linked card path refuses where an N-1 reader followed it.
  • N-1 MCP: no tool, annotation or schema change; ares_lit_card_list and ares_paper_check inherit the same refusal.
  • N-1 study/ledger formats: no change; an N-1 reader still follows a linked card path, so a study relying on the refusal needs the newer line.

• Card reuse through vault-mem (#101): lit card export <dir> <id>... --vault ID [--confirm FINGERPRINT] previews, then writes own, identifier-verified cards with hashed-study provenance to the single matching vault-mem reference note (doi/arxiv_id), guarded by the note hash. lit card import copies a card back only for an included candidate verified in this study, stored with a reused record. lit card list and paper check's reusedCards show the provenance; unreadableCards lists cited cards that cannot be read. ArXiv-only papers resolve their note through the arXiv DOI, citekey, id or title (vault-mem does not index arxiv_id) with an exact frontmatter match. The study lock is held only for planning and the commit, not across vmem calls. Both commands need the scope gate and carry any automatic approval into their commit; export preflights its receipt before writing to the vault, and provenance names the actor of the recording lit.card event. Reused cards never touch verification, screening, gates or the bibliography. Cards gain optional datasets, results and motivation. MCP adds ares_lit_card_export, ares_lit_card_import and ares_lit_card_list. Tests use a fake vmem only.

  • N-1 CLI: existing commands and usage remain; the three lit card subcommands are additive.
  • N-1 MCP: existing tools remain; the three card tools are additive and the ares_lit_card card schema gains optional fields only.
  • N-1 study/ledger formats: study and ledger versions stay unchanged; lit.card.exported and lit.card.imported events are additive. Cards without the new fields keep their bytes. Older readers that read card files directly ignore reused and the optional fields; an older lit card refuses input with the new fields.

• Selection flow report (#104): ...

v0.2.1

• Fix release clean-install smoke to compare installed schema versions with the checkout's FORMAT_VERSIONS, including study v2; an offline regression runs in the ordinary check (#88).

• v0.2.0 was tagged but never published because its release smoke failed. This patch ships the fix without moving that tag.

Install

bun add -g @staix/agent-research@0.2.1

Published with npm OIDC trusted publishing and provenance. The validated tarball and its tag/commit/SHA-256 manifest are attached. SHA-256: 5ab9040d6784c04fb276a0dc0b4608d7783e5eda000dd7bf1acb5f66515b617b.

ares 0.1.0

First public release of ares (@staix/agent-research), the research engine of the agent family: a study ledger with approval gates, verified literature, sealed container experiments, evidence-bound papers and reviews, memory export, and console/MCP surfaces. One CLI and a stdio MCP server share every command.

Highlights

• Literature (A1): scope, search across OpenAlex, Semantic Scholar and arXiv, screening, identifier verification (Crossref, DataCite, arXiv) and BibTeX with stable citekeys.
• Experiments (A2, A3): frozen Git commits in isolated local or SSH Docker containers with a sealed evaluator; a resumable plan DAG; investigate, ablate and a one-shot reserved-seed final with qualified or not_qualified outcomes.
• Paper and review (A4): manuscripts whose numbers come only from closed results, citation checks, and a review gate that needs two model families and no open blocking finding.
• Memory (A5): amem lesson export with decayed ranking and a reviewed skill proposal queue.
• Setup, console and watch (A6): ares setup <client> with receipts and undo, an agent-console plugin for study panels and confirmed person decisions, and finite literature watch passes for scheduled refresh.

Getting started

bun add -g @staix/agent-research
ares setup claude            # preview; add --apply to register the MCP server
ares init study --question "..."
ares playbook

Requires Bun 1.4.2 or newer. This is the initial publication, so no N-1 compatibility is claimed yet; checks against this minor line start with 0.2.0. Known follow-ups are tracked in #59; the copilot and step autonomy modes are planned in #52.

---

• Phase A6 setup/console/watch (#51): dry-run client and API-1 console registration with receipts, conditional undo and versioned roots; an explicit private study registry; read panels and event-timed inboxes; and eight decision-level console actions with preview/fingerprint confirmation, person attribution and stale-input refusal. Read-only console mode blocks writes. Saved literature watches run one finite, study-locked pass, retain ordinary scope/screen rules and never score rubrics or screen automatically; recurrence is person-managed agent-hub task proposals or user cron. Malformed watch versions are repairable; safe-integer future versions remain unchanged. CLI/MCP share watch and registry operations; MCP watch runs always return detached admission {started:true,configSha256} after locked config/scope/year preflight and finish in the same responsive MCP process. Outcomes arrive in watch.ran/watch show; every-source failure is recorded as ok:false. A second start while locked refuses. CLI watch run and watch.run plan steps remain synchronous (exit 1/failed node on all-source failure). Manifest lists studyRegistry/watchConfig v1 and watch ledger events. Tests use synthetic records/fake HTTP/runners and pinned console conformance, with no live deployment/amem/vault claim. No resident watcher is included.

• Phase A5 memory/evolution (#44): project-scoped amem lesson reads and half-life ranking; preview/fingerprint-confirmed archive batches with partial-success receipts; pivot cause/retryWhen; and a bounded, actor-recorded skill proposal queue. CLI/MCP share commands; manifest lists skillProposal v1 and the three A5 ledger kinds. Every playbook phase starts with intent lessons and archive is the last study step. Survey supports lessons/archive/skills, with experiment-only sources still refused. Tests use synthetic records and fake runners, no network, real amem or vault writes; live interoperability is not claimed. Vault promotion stays in amem, and ares never opens/checks/merges proposal PRs.

• Fix local macOS executor log collection with binary xattrs: content-only log archives now exclude xattrs and AppleDouble files while preserving original file attributes, strict parsing and capture limits (#30).

• Phase A1 (#2): study ledger with approval gates, scope, literature search across OpenAlex, Semantic Scholar and arXiv with merging, screening, extraction cards, identifier verification at Crossref, DataCite and arXiv, BibTeX generation with stable citekeys, citation check for drafts, and a stdio MCP server with the same operations.

• Phase A2 (#4): local/SSH Docker execution of frozen Git commits, a design gate binding protocol and evaluator task files, separate isolated non-root candidate/evaluator containers, evaluator-only finite metrics, attempt identity/retry/reconcile/cancel, wall-clock enforcement and budgets across every status. CLI and MCP include executor checks, paged attempt summaries and read-only host log retrieval. Study records hold ares-observed evidence and artifact metadata only; signed receipts remain deferred. Offline fixtures and separate dgx live proof cover isolation, commit selection, log truncation and archive containment.

• Phase A3 plan DAG (#6): revisioned bounded step/hub/gate definitions, ledger-derived readiness and stale propagation, durable command-id controls, upstream-output plan gates and CLI-only ares run. The controller restores paused, fences ownership by pid/host/process start, reconciles interrupted work without implicit replay, admits parallel steps while preserving one active attempt, and backs off observations. Hub nodes only read campaign/unit task references, wait for activation/approval, retain task bindings across restarts and expose read errors plus the resolved board. MCP set/show/control never starts the controller loop.

• Phase A3 investigate (#25): a sealed selection rule, ledger-only ideas with evidence-backed refine/pivot decisions and unique commit ownership, current-protocol counting after the selection cutoff, paired-seed delta ranking and named winner/no-winner outcomes. Read-only show and deterministic close retain all run statuses/exclusions; unchanged close writes nothing. CLI/MCP operations and the no-argument investigate.close plan step share the result, whose {sha256, winner} reference binds downstream gates. Tests are offline synthetic fixtures; no live hub or executor DAG proof is claimed. Automatic idea generation, significance tests and concurrent attempts remain out of scope; amem export is provided by A5.

• Phase A3 ablate/final/posthoc (#32): unused reserved seeds join the design seal, declared ablations pair against fresh winner replications without ranking, and a content-bound final gate authorizes one-shot reserved-seed evaluation. First attempts remain decisive across retries and reapproval; changed winners cannot buy a second final. Deterministic final close records qualified/not_qualified with named reasons; posthoc requires historical final closure and keeps all metrics exploratory without changing final inputs. CLI/MCP, manifest formats and no-argument ablate.close/final.close plan steps expose committed result hashes and statuses for downstream gates. Acceptance uses offline fixtures; held-out evaluator data and significance tests remain deferred.

• Phase A4 paper and review (#38): closed-result numeric placeholders, reviewer-visible literals/code numbers, positioned paper checks with citation verification and mandatory negative-result prose, deterministic Markdown/evidence builds, and build-bound review records with reasoned resolutions. The review gate needs a current clean build, two distinct self-reported model families and no open blocking finding; contradictions cannot be voted away. CLI/MCP and a no-argument paper.build plan step share the committed evidence hash; manifest lists paperEvidence v1. Survey papers use citation-only checks and refuse experiment refs. Offline fixtures only; claim-passage evidence awaits agent-hub#931, and automatic writing/reviewing plus LaTeX/PDF builds remain out of scope.

• Compatibility (#5 AC2/AC3): read-only ares manifest --json and MCP ares_manifest publish the package, command and implemented shared-format versions. Additive study/ledger/attempt fields and unknown ledger kinds survive reads and subsequent writes; unsupported versions or execution semantics refuse without rewriting data. Unknown stage entries remain readable but block budget-gated starts until a compatible version can account for them. A6 adds ares setup and versioned-root registration. This is the initial publication, with no prior published minor line; no N-1 compatibility claim is made yet for CLI, MCP tools or study/ledger formats. N-1 CI checks begin with the next minor release, against the latest published patch of this minor line. Release compatibility instructions are in AGENTS.md.

• Release readiness: tag/version and dated changelog validation, Ubuntu/macOS checks, staged tarball hash verification and clean-prefix CLI/manifest/MCP smoke checks. Publication is gated on NPM_PUBLISH_ENABLED=true and npm-production approval, using npm OIDC provenance for the validated Linux artifact. Actual tagging, trusted-publisher configuration and publication remain owner steps after merge.

Install

bun add -g @staix/agent-research@0.1.0

Published with npm OIDC trusted publishing and provenance. The validated tarball and its tag/commit/SHA-256 manifest are attached. SHA-256: ce4441fd002034734540a164dd105089d5c1dff56d241c36b175193915ccdcf6.