@lazyingart/agintiflow 0.20.198 → 0.20.200

package/README.md

@@ -178,6 +178,13 @@ aginti --language de
 | Resume current project | `aginti resume` (`1` is newest/latest; Space shows more) |
 | Browse all sessions | `aginti resume --all-sessions` |
 | Queue into a running session | `aginti queue <session-id> "extra instruction"` |
+| Inspect durable goal revisions | `aginti sessions list` and `aginti sessions show <session-id>` |
+
+The runtime uses durable goal lifecycles, safe-boundary inbox interruption,
+progressive tool/context disclosure, bounded read batching, evidence-gated
+completion, and provider attribution. See
+[State-of-the-Art Agent Runtime](docs/state-of-the-art-agent-runtime.md) for the
+embedding and acceptance contract.
 | Clean empty sessions | `aginti --remove-empty-sessions` |
 | Check capabilities | `aginti capabilities`, `aginti doctor --capabilities` |
 | Sync reviewed skills | `aginti skillmesh status`, `aginti skillmesh sync` |

package/bin/aginti-cli.js

@@ -1,7 +1,22 @@
 #!/usr/bin/env node
-import { main } from "../src/cli.js";
+import fs from "node:fs";
 
-main().catch((error) => {
+const argv = process.argv.slice(2);
+
+function fail(error) {
   console.error(error);
   process.exit(1);
-});
+}
+
+try {
+  if (["--version", "version", "-v"].includes(argv[0])) {
+    const packageJson = JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+    console.log(packageJson.version);
+  } else {
+    import("../src/cli.js")
+      .then(({ main }) => main(argv))
+      .catch(fail);
+  }
+} catch (error) {
+  fail(error);
+}

package/docs/agent-runtime-pipe.md

@@ -8,8 +8,56 @@ AgInTiFlow keeps CLI and web runs equivalent by using a project-local session in
 - Canonical session store: `~/.agintiflow/sessions/<session-id>/`.
 - Runtime inbox: `~/.agintiflow/sessions/<session-id>/inbox.jsonl`.
 
+## Persistence Guarantees
+
+Long-lived processes reuse one SQLite session-index connection and prepared
+statement set per resolved `AGINTIFLOW_HOME`. The index enables WAL mode and a
+bounded busy timeout so CLI, web, and bridge processes can update the
+rebuildable index without repeatedly reopening and migrating the database.
+Call `closeSessionIndexConnections()` in tests or embedding hosts that switch
+runtime homes inside one process.
+
+Each `SessionStore` memoizes directory/pointer initialization and serializes
+its event appends. Concurrent callers therefore retain call order without
+recreating the session pointer for every event. `state.json` remains an atomic,
+fsynced save boundary. A missing state file is resumably absent; malformed JSON
+raises `SESSION_STATE_CORRUPT` instead of silently looking like a new session.
+
+## Machine Run Input
+
+`aginti run` uses deterministic input precedence: explicit `--stdin` reads
+standard input, otherwise a positional prompt wins, and piped standard input is
+used only when no positional prompt exists. This keeps positional automation
+working in subprocesses whose stdin is non-interactive while preserving both
+explicit and implicit pipe workflows. `aginti --version` is handled by the
+lightweight launcher without loading the full agent and web runtime.
+
 When a run is active, the web chat and `aginti queue <session-id> "..."` append messages to the inbox instead of trying to mutate the running process directly. The web API exposes `GET /api/sessions/:id/inbox`, `POST /api/sessions/:id/inbox`, `PATCH /api/sessions/:id/inbox/:itemId`, and `DELETE /api/sessions/:id/inbox/:itemId` so browser users can inspect, edit, or remove pending pipe messages before the runner consumes them. The runner drains the inbox at safe boundaries: before each model step and after tool execution. This mirrors the event-queue style used by mature agent UIs while keeping the backend decoupled from any specific frontend.
 
+Embedding hosts can continue the same durable context without scraping terminal
+output:
+
+```bash
+printf '%s' 'Follow up using the existing evidence.' \
+  | aginti resume SESSION_ID --stdin --json
+```
+
+Machine resume emits the same single JSON object as `aginti run --json`, keeps
+the original session ID, restores the saved provider/model/tool/runtime policy,
+and never starts the web UI or writes interactive status lines. Explicit resume
+options may still patch durable runtime fields, but `--stdin` and `--json` are
+transport flags and are not persisted. This is the supported boundary for
+LabCanvas, chat bridges, schedulers, and other embedding hosts that need one
+isolated reusable agent session per conversation.
+
+The object includes `goalRevision` and `goalStatus`. A first request starts at
+revision 1. Every nonempty resume prompt advances the revision while retaining
+the bounded prior-goal ledger. Accepted completion marks that revision
+`completed`; a safe interruption or exhausted bounded run marks it `paused`;
+provider/runtime failure marks it `failed`. The next continuation reactivates
+the same session instead of replaying prior work. `aginti sessions show
+SESSION_ID` exposes both the revision history and lifecycle transitions.
+
 The interactive CLI keeps the input panel visible while a run is working. Enter sends the current draft as an ASAP pipe message and displays it as `→`; the runner drains those messages before normal inbox items and before after-finish queued prompts. Tab stores the draft as an after-finish queue item and displays it as `↳`; those prompts run only after the current run completes. Alt+Up moves the last pending `→` message back into the editor, and Shift+Left moves the last pending `↳` message back into the editor. Idle Esc is ignored so it does not redraw the prompt into the transcript. During a run, Esc waits when `→` pipe messages are still pending and stops the run only when no ASAP pipe message is pending; Ctrl+C always stops. The current command cwd is rendered below the input panel in both idle and running states.
 
 The web UI uses a related but browser-appropriate pattern. Enter sends and Shift+Enter adds a newline. `Pipe to run` writes an ASAP inbox item shared with CLI. `Queue after finish` keeps a browser-local next prompt and starts it after the current web-owned run finishes. Both lanes render in a pending panel with Edit and Remove buttons instead of terminal-only keybindings.

package/docs/labcanvas-chatops-fallback.md

@@ -0,0 +1,46 @@
+# LabCanvas ChatOps Fallback
+
+AgInTiFlow is a reasoning and tool-supervision fallback for LabCanvas. LabCanvas remains the owner of chat transport, schedules, exact-source media resolution, durable task state, routine selection, artifact validation, and delivery.
+
+## Contract
+
+LabCanvas should pass one bounded task packet containing:
+
+- exact current request and source-chat identity;
+- latest same-chat interruptions and a small amount of attributed context;
+- one selected routine and its contract paths;
+- current deterministic preflight and stage state;
+- exact artifact directory and irreversible-action gates.
+
+AgInTi should read `AGENTS.md` and the selected routine contract, then call established commands. It should not invent a second scheduler, publication pipeline, media downloader, CAD generator, or delivery mechanism.
+
+The default provider chain is `deepseek,localllm`. Switching providers is safe only when the first provider failed before inference or tool execution. Never replay an unknown task failure or timeout on another provider because the first attempt may already have caused a side effect.
+
+## Evidence Scope
+
+ChatOps prompts may include a trusted single-line marker:
+
+```text
+AGINTI_EVIDENCE_SCOPE_JSON: {"mode":"chat-response","request":"Produce only the requested chat response."}
+```
+
+or:
+
+```text
+AGINTI_EVIDENCE_SCOPE_JSON: {"mode":"task","request":"Create the requested PDF from the supplied evidence."}
+```
+
+For `chat-response`, ordinary conversation and routing do not require file or command evidence. For `task`, evidence requirements are inferred only from the exact request, not from surrounding wrapper prose. Artifact requests still require real artifacts.
+
+## Local Context Recovery
+
+LocalLLM planning compacts oversized goals to a bounded head-and-tail representation. Runtime compaction retains the first request and latest interruptions. A `LocalContextBudgetError` triggers one compact-and-retry cycle at the same step and records private recovery events. It does not authorize replaying task side effects.
+
+Validate with:
+
+```bash
+npm run check
+npm run smoke:context-budget-recovery
+npm run smoke:truthful-completion
+```
+

package/docs/state-of-the-art-agent-runtime.md

@@ -0,0 +1,179 @@
+# State-of-the-Art Agent Runtime
+
+AgInTiFlow is designed as an embeddable agent runtime, not a prompt wrapper.
+Its main job is to preserve intent, evidence, and tool progress while providers,
+frontends, and long-running tasks change underneath it.
+
+This architecture draws on proven patterns from durable agent systems,
+including the append-only session and lifecycle ideas in
+[`deepseek-ai/deepseek-harness`](https://github.com/deepseek-ai/deepseek-harness),
+while retaining AgInTiFlow's provider-neutral tool and safety boundaries. The
+implementation is local and does not import that repository as a runtime
+dependency.
+
+## Runtime Invariants
+
+1. One logical conversation owns one durable session ID.
+2. A continuation resumes that session; it does not replay the task from the
+   beginning.
+3. The current user request is authoritative, but prior verified evidence and
+   unfinished requirements remain available.
+4. Tool side effects are accepted only through explicit, validated contracts.
+5. A final answer is successful only when its required evidence exists.
+6. Provider failure is not task success and is not silently converted into it.
+7. Provider handoff preserves the session and goal rather than duplicating
+   external work.
+
+## Durable Goal Contract
+
+Every session stores a versioned goal contract in `state.json`:
+
+- `revision`: advances for every resumed request;
+- `currentHash` and `currentPreview`: identify the authoritative request
+  without placing private raw prompts in operational indexes;
+- `history`: bounded revision history with previous-goal and plan hashes;
+- `status`: `active`, `completed`, `paused`, or `failed`;
+- `lifecycle`: bounded status transitions with reason and timestamp.
+
+Accepted direct answers, evidence-backed assistant answers, and `finish` tool
+calls mark the current revision completed. User interruption, step exhaustion,
+or a repairable tool-contract stop pauses it. Provider timeout, preflight
+failure, and unexpected runtime errors mark it failed. A new continuation
+reactivates the same session at the next revision.
+
+Inspect it without parsing terminal output:
+
+```bash
+aginti sessions list
+aginti sessions show SESSION_ID
+```
+
+Machine responses also expose `goalRevision` and `goalStatus`.
+
+## Append-Only Evidence And Atomic State
+
+The canonical session lives under
+`~/.agintiflow/sessions/<session-id>/`. Atomic `state.json` snapshots hold the
+resumable working state. Append-only JSONL events preserve lifecycle, tool,
+model, evidence, inbox, and recovery facts. A project-local index points to the
+canonical session without copying private history.
+
+Malformed state is treated as corruption, not as a missing session. Event
+appends are serialized, state saves are atomic and fsynced, and the SQLite
+session index uses WAL plus a bounded busy timeout for multiple frontends.
+
+## Safe Interruption And Inbox
+
+`aginti queue SESSION_ID "instruction"`, the CLI composer, and the web app all
+write to the same durable inbox. The runner consumes messages only at safe
+boundaries:
+
+- before a model step;
+- after a tool action;
+- before accepting completion.
+
+This permits an operator or chat bridge to correct, narrow, extend, or cancel
+the current direction without mutating an in-flight model request or replaying
+completed side effects. ASAP input and after-finish input remain distinct.
+
+## Progressive Context And Tool Disclosure
+
+The first model turn receives a focused runtime contract, the current goal,
+relevant project instructions, and only the skills selected for that request.
+It does not receive an indiscriminate dump of every skill or workspace file.
+
+Tool access is progressively disclosed:
+
+- direct chat can answer without tools;
+- unfamiliar repositories begin with bounded inspection and search;
+- relevant routines are preferred over rebuilding mature workflows;
+- a small batch of up to four independent read-only calls may run in one turn;
+- writes, GUI actions, network writes, and irreversible operations remain
+  isolated, ordered calls.
+
+Workspace search is bounded by file count, bytes, and elapsed time. Default
+root scans skip generated outputs, artifacts, and private data, while an
+explicit path remains inspectable when the user actually requested it.
+
+## Truthful Completion
+
+Completion is checked against an evidence scope. Read-only answers and plans do
+not need irrelevant command or visual evidence. File creation, publication,
+GUI work, and other external actions require the corresponding evidence.
+
+The runtime provides:
+
+- one bounded retry when a model claims completion without required evidence;
+- one bounded repair for an empty model answer;
+- a concise fallback only when runtime evidence already verifies completion;
+- a resumable stop instead of a false success when evidence remains absent;
+- short-circuiting after a blocked tool so later calls in that batch are not
+  dispatched against an invalid state.
+
+## Provider Attribution And Handoff
+
+`npm run eval:provider-attribution` compares a raw provider answer with the
+same provider through AgInTiFlow. Results are classified as:
+
+- `both_pass`: provider and orchestration both satisfy the contract;
+- `orchestration_loss_or_help`: the runtime changed the outcome, so inspect
+  prompting, context, tools, or completion gates;
+- `provider_limit`: the raw model itself failed the contract.
+
+This prevents orchestration bugs from being blamed on DeepSeek or a local
+model, and prevents weak model output from triggering unnecessary framework
+rewrites.
+
+Embedding hosts should use a provider chain while preserving the same AgInTi
+session. LabCanvas uses DeepSeek first and LocalLLM second. A handoff occurs
+only after a categorized provider failure and must not replay verified side
+effects. Codex and Claude remain explicit opt-in backends rather than hidden
+fallbacks.
+
+## Machine Host Protocol
+
+The supported subprocess boundary is:
+
+```bash
+printf '%s' 'Do the task.' | aginti run --stdin --json [runtime options]
+printf '%s' 'Continue with this correction.' \
+  | aginti resume SESSION_ID --stdin --json
+```
+
+Exactly one JSON object is emitted. It includes success/failure, session,
+provider, model, resume state, goal revision/status, result, stop state, and
+reason. Interactive banners, update checks, and web startup are suppressed.
+Stopped or failed runs always have `ok: false` even when they contain a useful
+human-facing explanation.
+
+## Established Routines, Not Reinvention
+
+AgInTiFlow is the reasoning and supervision layer. Domain work should use the
+existing routine owned by the relevant project:
+
+- LazyEdit and AutoPublish for subtitle-aware video publication;
+- LALACHAN/Xiaoyunque for story and video generation;
+- Musia for music and song-first MV workflows;
+- LabCanvas CAD, KiCad, Blender, TeX/PDF, presentation, grant, and figure
+  routines;
+- WeChat and WeCom transports for exact-chat delivery.
+
+The agent selects, invokes, monitors, and verifies those routines. It does not
+replace them with prompt-specific shell fragments.
+
+## Acceptance Gates
+
+A primary-backend release is accepted only after all of these pass:
+
+1. Syntax and deterministic runtime tests.
+2. Durable run/resume, goal lifecycle, inbox, and session-isolation tests.
+3. Progressive tool, bounded search, and truthful-completion tests.
+4. Raw-provider versus agent attribution for DeepSeek and LocalLLM.
+5. A live read-only established-routine task with no accidental write.
+6. A live exact artifact-creation task with byte-level verification.
+7. A live LocalLLM direct-response task.
+8. Host project tests, chat-bridge self-tests, package dry run, installed
+   version check, and existing-runtime restart.
+
+These gates keep the architecture fast for ordinary chat, capable for long
+tasks, and honest when a provider or external service is unavailable.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lazyingart/agintiflow",
-  "version": "0.20.198",
+  "version": "0.20.200",
   "type": "module",
   "description": "AgInTiFlow is a project-aware agent workspace for hybrid wet-dry R&D, hardware-aware intelligence, software automation, and industrial workflows.",
   "license": "Apache-2.0",
@@ -86,6 +86,7 @@
     "scripts/local-first-agent-eval.mjs",
     "scripts/fixtures/local-first-agent-eval-fixtures.mjs",
     "scripts/smoke-run-stdin.js",
+    "scripts/smoke-runtime-core.js",
     "scripts/smoke-mcp.js",
     "scripts/fixtures/mcp-stdio-smoke-server.mjs",
     "scripts/smoke-model-roles.js",
@@ -121,7 +122,7 @@
   "scripts": {
     "start": "node run.js",
     "web": "node web.js",
-    "check": "node --check run.js && node --check web.js && node --check bin/aginti-cli.js && node --check bin/aginti-public-research.js && node --check bin/aginti-safe-chat.js && node --check src/*.js && node --check src/mcp/*.js && node --check public/*.js && node --check scripts/postinstall-webapp.js && node --check scripts/seed-supervised-homework.js && node --check scripts/smoke-agentlink.js && node --check scripts/smoke-execution-policy.js && node --check scripts/smoke-math-rendering.js && node --check scripts/smoke-mcp.js && node --check scripts/smoke-public-research-wrapper.js && node --check scripts/smoke-safe-chat.js && node --check scripts/smoke-web-ui.js && node --check scripts/smoke-scs-evidence-visibility.js && node --check scripts/fixtures/mcp-stdio-smoke-server.mjs",
+    "check": "node --check run.js && node --check web.js && node --check bin/aginti-cli.js && node --check bin/aginti-public-research.js && node --check bin/aginti-safe-chat.js && node --check src/*.js && node --check src/mcp/*.js && node --check public/*.js && node --check scripts/postinstall-webapp.js && node --check scripts/seed-supervised-homework.js && node --check scripts/eval-provider-attribution.js && node --check scripts/smoke-agentlink.js && node --check scripts/smoke-execution-policy.js && node --check scripts/smoke-math-rendering.js && node --check scripts/smoke-mcp.js && node --check scripts/smoke-public-research-wrapper.js && node --check scripts/smoke-runtime-core.js && node --check scripts/smoke-safe-chat.js && node --check scripts/smoke-web-ui.js && node --check scripts/smoke-scs-evidence-visibility.js && node --check scripts/fixtures/mcp-stdio-smoke-server.mjs",
     "setup:toolchain-docker": "scripts/setup-agent-toolchain-docker.sh",
     "smoke:coding-tools": "node scripts/smoke-coding-tools.js",
     "smoke:dynamic-step-budget": "node scripts/smoke-dynamic-step-budget.js",
@@ -140,8 +141,10 @@
     "smoke:inbox": "node scripts/smoke-inbox.js",
     "smoke:long-jobs": "node scripts/smoke-long-jobs.js",
     "smoke:run-stdin": "node scripts/smoke-run-stdin.js",
+    "smoke:runtime-core": "node scripts/smoke-runtime-core.js",
     "smoke:localllm-auto-max": "node scripts/smoke-localllm-auto-max.js",
     "smoke:local-resource-policy": "node scripts/smoke-local-resource-policy.js",
+    "smoke:context-budget-recovery": "node scripts/smoke-context-budget-recovery.js",
     "smoke:localllm-model-tiers": "node scripts/smoke-localllm-model-tiers.js",
     "smoke:localllm-provider": "node scripts/smoke-localllm-provider.js",
     "smoke:progressive-tools": "node scripts/smoke-progressive-tool-selection.js",
@@ -165,13 +168,14 @@
     "smoke:web-port-fallback": "node scripts/smoke-web-port-fallback.js",
     "smoke:autoupdate": "node scripts/smoke-auto-update.js",
     "eval:local-first-agent": "node scripts/local-first-agent-eval.mjs",
+    "eval:provider-attribution": "node scripts/eval-provider-attribution.js",
     "real:deepseek": "node scripts/real-deepseek-capabilities.js",
     "postinstall": "node scripts/postinstall-webapp.js",
     "supervision:seed": "node scripts/seed-supervised-homework.js",
     "storage:migrate": "node bin/aginti-cli.js storage migrate",
     "publish:env": "node scripts/npm-publish-from-env.js publish --access public",
     "publish:env:whoami": "node scripts/npm-publish-from-env.js whoami",
-    "test": "npm run check && npm run smoke:localllm-provider && npm run smoke:localllm-model-tiers && npm run smoke:localllm-auto-max && npm run smoke:local-resource-policy && npm run smoke:session-runtime && npm run smoke:progressive-tools && npm run smoke:truthful-completion && npm run smoke:writing-specialist-routing && npm run eval:local-first-agent && npm run smoke:runtime-compat && npm run smoke:autoupdate && npm run smoke:web-api && npm run smoke:math-rendering && npm run smoke:web-ui && npm run smoke:web-autostart && npm run smoke:webapp-command && npm run smoke:web-port-fallback && npm run smoke:docker-command && npm run smoke:coding-tools && npm run smoke:dynamic-step-budget && npm run smoke:execution-policy && npm run smoke:aaps-adapter && npm run smoke:auxiliary-tools && npm run smoke:perception-research && npm run smoke:public-research && npm run smoke:safe-chat && npm run smoke:auth && npm run smoke:agentlink && npm run smoke:canvas-artifacts && npm run smoke:capabilities && npm run smoke:mcp && npm run smoke:model-roles && npm run smoke:platform && npm run smoke:permission-modes && npm run smoke:skills && npm run smoke:skillmesh && npm run smoke:tmux-tools && npm run smoke:long-jobs && npm run smoke:run-stdin && npm run smoke:cli-chat && npm run smoke:inbox",
+    "test": "npm run check && npm run smoke:localllm-provider && npm run smoke:localllm-model-tiers && npm run smoke:localllm-auto-max && npm run smoke:local-resource-policy && npm run smoke:context-budget-recovery && npm run smoke:session-runtime && npm run smoke:runtime-core && npm run smoke:progressive-tools && npm run smoke:truthful-completion && npm run smoke:writing-specialist-routing && npm run eval:local-first-agent && npm run eval:provider-attribution && npm run smoke:runtime-compat && npm run smoke:autoupdate && npm run smoke:web-api && npm run smoke:math-rendering && npm run smoke:web-ui && npm run smoke:web-autostart && npm run smoke:webapp-command && npm run smoke:web-port-fallback && npm run smoke:docker-command && npm run smoke:coding-tools && npm run smoke:dynamic-step-budget && npm run smoke:execution-policy && npm run smoke:aaps-adapter && npm run smoke:auxiliary-tools && npm run smoke:perception-research && npm run smoke:public-research && npm run smoke:safe-chat && npm run smoke:auth && npm run smoke:agentlink && npm run smoke:canvas-artifacts && npm run smoke:capabilities && npm run smoke:mcp && npm run smoke:model-roles && npm run smoke:platform && npm run smoke:permission-modes && npm run smoke:skills && npm run smoke:skillmesh && npm run smoke:tmux-tools && npm run smoke:long-jobs && npm run smoke:run-stdin && npm run smoke:cli-chat && npm run smoke:inbox",
     "pack:dry-run": "npm pack --dry-run",
     "smoke:capabilities": "node scripts/smoke-capabilities.js"
   },

package/scripts/smoke-cli-chat.js

@@ -918,6 +918,23 @@ try {
   ) {
     throw new Error("resume subcommand options after the session id should remain options, not prompt text");
   }
+  const machineResume = parseResumeCommandArgs([
+    "web-agent-smoke",
+    "--stdin",
+    "--json",
+    "--provider",
+    "mock",
+  ]);
+  if (
+    machineResume.sessionId !== "web-agent-smoke" ||
+    !machineResume.stdin ||
+    !machineResume.json ||
+    machineResume.optionArgv.includes("--stdin") ||
+    machineResume.optionArgv.includes("--json") ||
+    parseArgs(machineResume.optionArgv).provider !== "mock"
+  ) {
+    throw new Error("resume machine transport flags should be parsed outside the durable runtime patch");
+  }
   const resumeRuntimeOptions = [
     "--provider",
     "mock",

package/scripts/smoke-progressive-tool-selection.js

@@ -18,6 +18,7 @@ import { SessionStore } from "../src/session-store.js";
 import {
   attachToolContract,
   createToolContract,
+  safeSequentialToolBatchLimit,
   toolContractFromResponse,
   validateToolCallBatch,
 } from "../src/tool-contract.js";
@@ -816,6 +817,81 @@ assert(
   "valid offered tool call did not satisfy its exact schema"
 );
 
+const safeReadDescriptors = [
+  {
+    type: "function",
+    function: {
+      name: "read_file",
+      description: "Read a file.",
+      parameters: {
+        type: "object",
+        properties: { path: { type: "string" } },
+        required: ["path"],
+        additionalProperties: false,
+      },
+    },
+  },
+  {
+    type: "function",
+    function: {
+      name: "search_files",
+      description: "Search files.",
+      parameters: {
+        type: "object",
+        properties: { path: { type: "string" }, query: { type: "string" } },
+        required: ["path", "query"],
+        additionalProperties: false,
+      },
+    },
+  },
+  {
+    type: "function",
+    function: {
+      name: "list_files",
+      description: "List files.",
+      parameters: {
+        type: "object",
+        properties: { path: { type: "string" } },
+        required: ["path"],
+        additionalProperties: false,
+      },
+    },
+  },
+];
+const safeReadCalls = [
+  contractCall("safe-read", "read_file", { path: "AGENTS.md" }),
+  contractCall("safe-search", "search_files", { path: ".", query: "lazyedit" }),
+  contractCall("safe-list", "list_files", { path: "." }),
+];
+const safeReadContract = createToolContract(safeReadDescriptors);
+assert(safeSequentialToolBatchLimit(safeReadCalls) === 4, "safe read batch did not receive the bounded sequential allowance");
+assert(
+  validateToolCallBatch(safeReadCalls, safeReadContract, {
+    maxToolCalls: safeSequentialToolBatchLimit(safeReadCalls),
+  }).ok,
+  "valid safe read batch did not pass the exact per-turn contract"
+);
+const mixedReadWriteCalls = [
+  safeReadCalls[0],
+  contractCall("unsafe-write", "write_file", { path: "blocked.txt", content: "bad" }),
+];
+assert(safeSequentialToolBatchLimit(mixedReadWriteCalls) === 1, "mixed read/write batch escaped the single-call limit");
+assert(
+  !validateToolCallBatch(mixedReadWriteCalls, createToolContract([...safeReadDescriptors, strictWriteDescriptor]), {
+    maxToolCalls: safeSequentialToolBatchLimit(mixedReadWriteCalls),
+  }).ok,
+  "mixed read/write batch unexpectedly passed"
+);
+const oversizedReadCalls = Array.from({ length: 5 }, (_, index) =>
+  contractCall(`read-${index}`, "read_file", { path: `file-${index}.txt` })
+);
+assert(
+  !validateToolCallBatch(oversizedReadCalls, safeReadContract, {
+    maxToolCalls: safeSequentialToolBatchLimit(oversizedReadCalls),
+  }).ok,
+  "oversized read batch escaped the bounded allowance"
+);
+
 for (const [label, call, expectedCode] of [
   [
     "hidden dryRun",