@lazyingart/agintiflow 0.20.203 → 0.20.205

package/.env.example

@@ -13,6 +13,11 @@ AGINTI_LOCALLLM_VISION_MODEL=localllm-vision-xl
 AGINTI_LOCALLLM_CONTEXT_TOKENS=32768
 AGINTI_LOCALLLM_MAX_OUTPUT_TOKENS=8192
 AGINTI_LOCALLLM_TOOL_SCHEMA_TOKENS=4096
+# Committee JSON uses the same-provider route model when possible. LocalLLM uses
+# deterministic contract/evidence validation by default; hosted providers keep
+# the independent model validator. Set `model` to force model validation.
+AGINTI_SCS_VALIDATION_MODE=auto
+AGINTI_SCS_MODEL_TIMEOUT_MS=45000
 
 # Genuine implementation work uses the code alias only after authenticated model
 # discovery confirms that exact configured alias; otherwise it remains on Deep.
@@ -33,6 +38,16 @@ AGINTI_WRITING_PROVIDER=
 AGINTI_WRITING_MODEL=
 AGINTI_ALLOW_HOSTED_WRITING_SPECIALIST=false
 
+# Optional Agent Skills interoperability. Existing ~/.agents/skills,
+# ~/.codex/skills, and ~/.claude/skills are discovered read-only by default.
+AGINTIFLOW_DISCOVER_AGENT_SKILLS=true
+# AGINTIFLOW_AGENT_SKILL_PACKS=/path/to/agent-skills:/path/to/more-skills
+# AGINTIFLOW_SKILL_PACKS=/path/to/another-reviewed-pack
+
+# Optional structured read-only roots for sibling routines/reference repos.
+# Repeatable CLI equivalent: --read-root /absolute/reference/repo
+# AGINTI_READ_ROOTS=/absolute/reference/repo:/another/reference/repo
+
 # Optional local npm publish fallback. Prefer GitHub Actions Trusted Publishing.
 NPM_TOKEN=
 NODE_AUTH_TOKEN=

package/README.md

@@ -54,7 +54,7 @@ Most agent tools are either a chat box with hidden state or an expensive one-mod
 | Disciplined by default | `AGINTI.md` starts with a behavior contract: surface ambiguity, keep edits surgical, avoid speculative complexity, verify outcomes, and respect permission blockers. |
 | Role-based models | Route, main, spare, wrapper, and auxiliary image roles are separate. LocalLLM supplies the default fast/deep lanes; DeepSeek, OpenAI, OpenRouter, Qwen, and Venice are optional explicit routes. |
 | Writing without agent noise | `writing_specialist` drafts novels, books, scripts, essays, and paper prose in an isolated writing-only context on the active provider. Cross-provider writing requires explicit permission; ambient keys and model arguments cannot silently switch a LocalLLM session to a hosted model. The main agent then handles files, formatting, citations, checks, and artifacts. |
-| Visual and web evidence | `read_image` keeps local pixels local. Fast search has provider fallback; exact page reads preserve hashes and metadata; `deep_research` adds resumable planning, parallel retrieval, exact-quote evidence, gap filling, synthesis, and citation auditing on the active provider. |
+| Visual and web evidence | `read_image` keeps local pixels local. Fast search has provider fallback; standard/deep research merges independent indexes; exact HTML/PDF reads preserve hashes and metadata; `deep_research` adds resumable planning, parallel retrieval, exact-quote evidence IDs, gap filling, synthesis, and claim-level citation auditing on the active provider. |
 | Scouts before big work | Parallel scouts can cheaply map architecture, tests, risks, symbols, and integration points before the main executor edits anything. |
 | SCS by default | Student-Committee-Supervisor mode adds a typed gate: committee drafts, student approves/monitors, supervisor executes. Use `/scs off` or `--no-scs` only when speed matters more than validation. |
 | AAPS for large workflows | AAPS describes top-down agentic pipeline scripts; AgInTiFlow can act as the interactive backend that validates, compiles, and executes those workflows. |

package/bin/aginti-integration.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { main, safeIntegrationCliError } from "../src/integration-cli.js";
+
+main().catch((error) => {
+  process.stderr.write(`aginti-integration: ${safeIntegrationCliError(error)}\n`);
+  process.exitCode = 1;
+});

package/docs/deep-research-engine.md

@@ -15,36 +15,100 @@ real value.
 The implementation follows the strongest production patterns without making
 every query an unbounded agent swarm:
 
-1. **Plan**: the active provider decomposes the question into non-overlapping
-   subquestions, search queries, preferred source types, and exclusions.
-2. **Search**: queries run with bounded concurrency. The no-key default falls
-   back from DuckDuckGo HTML to Bing RSS. An explicitly configured Brave Search
-   route is optional. Multi-domain corpora receive separate bounded `site:`
+1. **Plan**: a fast routing model on the active provider decomposes the question
+   into non-overlapping subquestions, search queries, preferred source types,
+   and exclusions. If that structured call fails, the main model gets one
+   bounded retry; the workflow never switches providers implicitly.
+2. **Search**: queries run with bounded concurrency. Quick lookup uses the
+   no-key DuckDuckGo-to-Bing fallback. Standard/deep research uses a bounded
+   ensemble that merges DuckDuckGo and Bing indexes, plus Brave only when it is
+   explicitly configured. A paper-oriented request receives one initial bounded
+   scholarly discovery pass against Crossref and arXiv, attached to the most
+   paper-like planned query. If the independently verified source minimum is
+   still open, the single gap pass may retry that lane once with a different
+   planner-derived query. This improves paper recall and metadata identity
+   without multiplying every query or creating bursty arXiv traffic.
+   When the request explicitly asks for official engineering or first-party
+   implementation evidence, one separate bounded query targets engineering,
+   documentation, system-card, and whitepaper surfaces. The selector reserves
+   one relevant first-party candidate when available instead of letting a large
+   paper set erase the requested source class. Search snippets can guide
+   discovery, but they cannot satisfy verified first-party coverage or enter
+   synthesis as cited evidence.
+   Canonical duplicates found by multiple providers are promoted and retain
+   per-provider rank evidence. Multi-domain corpora receive separate bounded `site:`
    queries matched to entity-specific subquestions instead of one fragile OR
-   expression.
-3. **Rank, diversify, and deduplicate**: canonical URLs remove tracking state;
-   primary, official, scholarly, and high-relevance results rank ahead of
-   summaries, while a bounded diversity penalty prevents one domain from
-   crowding every selected source.
+   expression. If an exact `site:` query returns no candidates, the engine
+   retries the same planner query once without the search-operator hint while
+   retaining the domain allowlist. This recovery stays inside the original
+   research run and is recorded in its checkpoint.
+3. **Rank, diversify, and deduplicate**: canonical URLs remove tracking state.
+   Scholarly records additionally carry DOI, arXiv ID, normalized title,
+   provider, venue, author, PDF, and alternate-URL provenance. DOI publisher,
+   arXiv abstract, and arXiv PDF variants of one work collapse before source
+   budgeting, while the audit records how many variants were merged. A title
+   match is only a fallback and never merges records with conflicting DOI or
+   arXiv identities. A source
+   repository is useful implementation evidence but is not automatically an
+   official or scholarly paper merely because it is hosted on GitHub or has
+   `paper` in its path.
+   Topical overlap, independent provider rediscovery, discovery by multiple
+   planned queries, and domain-constrained intent rank candidates. Official or
+   scholarly status is a quality signal, not a substitute for relevance, so a
+   generic university citation guide cannot crowd out a paper merely because it
+   is hosted on an academic domain. Dictionary, translation, and citation-generator
+   pages are excluded when stronger policy-compliant evidence exists. Under a
+   strict `primary`, `official`, or `scholarly` policy, four relevant compliant
+   candidates are enough to exclude generic supplementary commentary entirely.
+   When at least four strongly topical compliant candidates exist, marginally
+   related academic pages are excluded as well;
+   a sparse set may add only enough relevant supplementary context to reach
+   that small floor, but a strict policy with zero compliant candidates fails
+   closed instead of accepting generic filler. Source budgets are ceilings rather than targets, and a
+   bounded diversity penalty prevents one domain from crowding every selected
+   source.
 4. **Read exact sources**: `read_web_page` validates every redirect before the
    next request, rejects private DNS resolutions, streams bounded bytes, strips
    scripts/navigation, extracts article/main text and metadata, records hashes,
-   and marks all retrieved text as untrusted evidence.
+   and marks all retrieved text as untrusted evidence. Verified PDF response
+   bytes are passed to a bounded local `pdftotext` process when available, so
+   papers can contribute exact passages without sending the PDF to another
+   provider. If one exact scholarly landing page is inaccessible, the reader
+   tries only the same work's verified alternate landing/PDF URLs before giving
+   up; it never substitutes a nearby paper. When the original request requires
+   a paper, selected provider-supplied PDFs and arXiv, ACL Anthology,
+   OpenReview, and Nature landing pages are resolved to bounded PDF candidates
+   before evidence extraction. Direct PDF candidates receive the bounded 5 MiB
+   document allowance rather than the generic 2 MiB HTML-page allowance; larger
+   files still fail closed with the exact size error. Browser-verification,
+   CAPTCHA, and access-challenge HTML is marked unreadable instead of counting
+   its warning text as source evidence.
 5. **Extract evidence**: isolated structured-output calls identify relevant
-   subquestions, claims, exact quotations, confidence, and limitations.
+   subquestions, claims, exact quotations, confidence, and limitations. The
+   active provider's fast routing model handles the parallel first pass. Only
+   failed sources are retried, at lower concurrency and a larger output budget,
+   with that provider's stronger main model. Every extracted claim receives a
+   stable evidence ID such as `S2-C3`.
 6. **Verify**: deterministic code checks that quoted passages occur in the
    exact retrieved source. Unverified quotations do not enter synthesis.
 7. **Fill gaps**: standard/deep runs may issue one bounded follow-up pass for
-   uncovered subquestions when query and source budgets remain.
-8. **Synthesize**: the active provider receives verified evidence rather than
-   arbitrary page text. Every substantive paragraph and finding carries source
-   IDs.
-9. **Audit**: deterministic code removes invented source IDs and unsupported
-   synthesis statements whose cited sources produced no verified evidence,
-   then reports claim, quotation, citation, question, domain, and
-   primary-source coverage.
+   uncovered subquestions, insufficient independent readable primary evidence,
+   or a requested first-party class that has not produced readable,
+   quote-verified evidence, when query and source budgets remain.
+8. **Synthesize**: the active provider's main model receives verified evidence
+   rather than arbitrary page text. Every substantive paragraph and finding
+   cites exact evidence IDs instead of merely naming a source. A failed main
+   synthesis gets one same-provider fast-model fallback.
+9. **Audit**: deterministic code removes unknown or unverified evidence IDs,
+   derives visible source citations from accepted evidence records, removes
+   unsupported synthesis statements, then reports claim, quotation, citation,
+   question, domain, PDF, and independent primary-source coverage. A second
+   audit checks the cleaned synthesis; rejected provider IDs remain diagnostic
+   warnings but do not make the delivered report's final audit look dirty.
 10. **Persist**: every stage checkpoints one JSON state file. The final cited
-    Markdown report is saved beside it and sent to the canvas.
+    Markdown report is saved beside it by default, or written directly to a
+    guarded workspace-relative `outputPath` when the caller requests a durable
+    filename, then sent to the canvas.
 
 This combines the orchestrator/worker and separate citation-pass lessons
 described by [Anthropic's production research
@@ -67,6 +131,33 @@ The caller may reduce these budgets, but hard caps remain 12 queries and 24
 sources. Search/page concurrency is bounded to six and defaults to three or
 four.
 
+Explicit evidence requirements are derived from both the tool arguments and
+the authoritative original user goal. A planner may shorten the research
+question, but cannot silently drop requirements such as “compare at least three
+independent primary sources,” “read a paper/PDF when available,” or “include
+negative evidence.” These requirements are fingerprinted and checkpointed.
+
+Planning and evidence extraction deliberately use the configured routing model
+when it belongs to a hosted active provider. Synthesis uses the configured main
+model. For LocalLLM, when the outer agent has already selected and loaded its
+main model, every research stage reuses that resident model unless a dedicated
+extraction model was explicitly configured. This avoids a costly GPU residency
+swap; local evidence extraction is bounded to two concurrent calls by default.
+Failed evidence calls are retried selectively rather than repeating every
+successful source.
+
+The same residency rule applies to the outer SCS committee plan for a LocalLLM
+research task. It reuses the selected executor model instead of waiting on a
+second local route-model queue before the bounded research workflow can start.
+
+Planner-produced concise queries take precedence over the original user brief.
+The raw brief is retained as a search query only when it is already concise;
+long conversational instructions are research context, not a literal search
+engine query. For DeepSeek, bounded JSON transformations explicitly use
+non-thinking mode. The multi-stage workflow supplies the reasoning structure,
+while disabling hidden reasoning prevents a small extraction object from
+spending its entire output budget before emitting JSON.
+
 ## Usage
 
 Interactive:
@@ -83,7 +174,11 @@ An agent can call:
   "query": "What evidence supports the current design choices?",
   "depth": "standard",
   "sourcePolicy": "primary",
-  "domains": ["docs.example.org", "arxiv.org"]
+  "requirePdf": true,
+  "minIndependentSources": 3,
+  "includeNegativeEvidence": true,
+  "domains": ["docs.example.org", "arxiv.org"],
+  "outputPath": "reports/design-evidence.md"
 }
 ```
 
@@ -94,6 +189,12 @@ is marked failed, preserves its attempts, and retries retrieval on resume
 instead of caching an empty report as success. Checkpoint schema changes
 invalidate old cached runs automatically.
 
+`outputPath` is optional and must name a Markdown file inside the active
+workspace. Repository internals such as `.git`, dependency trees such as
+`node_modules`, path escapes, and symlink escapes are rejected. This lets the
+bounded engine satisfy an exact report filename without granting the outer
+agent access to private session artifacts.
+
 ## Artifacts
 
 Each session stores:
@@ -103,6 +204,9 @@ artifacts/deep-research-RESEARCH_ID.json
 artifacts/deep-research-RESEARCH_ID.md
 ```
 
+When `outputPath` is supplied, the JSON checkpoint remains private to the
+session while the report is also written to that exact guarded workspace path.
+
 The JSON includes:
 
 - objective, plan, query/source budgets, and source policy;
@@ -111,6 +215,12 @@ The JSON includes:
 - readable source text and ranked passages;
 - extracted claims, exact quotations, limitations, and question mappings;
 - missing questions, source diversity, and quote-verification rates;
+- explicit evidence requirements, parsed-PDF attempts, and independent verified
+  primary/scholarly source counts;
+- DOI/arXiv work identities, alternate read attempts, and merged-variant counts;
+- requested and verified first-party engineering source coverage;
+- evidence that came only from search excerpts, kept distinct from readable
+  source verification;
 - final synthesis and citation audit;
 - stage/status fields used for crash-safe resume.
 
@@ -122,6 +232,35 @@ The default `auto` policy uses public no-key providers:
 DuckDuckGo HTML -> Bing RSS
 ```
 
+The `multi` policy used by standard/deep research queries all available
+no-key indexes and merges their canonical results:
+
+```text
+DuckDuckGo HTML + Bing RSS (+ Brave when explicitly configured)
+```
+
+Paper-oriented `deep_research` requests keep that broad lane and add one
+bounded scholarly lane initially; an unresolved independent-source contract
+may trigger one additional scholarly call in the single gap pass:
+
+```text
+Crossref metadata + arXiv metadata/preprint links
+```
+
+For direct `web_search` use, `provider=scholarly` selects only Crossref and
+arXiv, while `provider=research` combines the general and scholarly lanes.
+`provider=crossref` and `provider=arxiv` remain available for a deliberately
+index-specific lookup. These public endpoints require no API key; provider
+failures remain visible in `providersTried` rather than being hidden.
+
+An explicit request for official engineering writeups adds one source-class
+query such as an engineering architecture or system-card lookup. This is not a
+hardcoded vendor list: the planner names relevant first-party organizations
+when it knows them, while deterministic routing preserves the requested source
+class and records whether a readable first-party source actually supported a
+quote-verified claim. A result-page excerpt alone is reported separately and
+does not close that requirement.
+
 For an explicitly configured Brave Search account:
 
 ```bash
@@ -140,17 +279,38 @@ through configuration or a tool argument.
 - Domain allowlists and blocklists apply to search results, direct reads, and
   redirect targets.
 - Tracking parameters and fragments are removed before deduplication.
+- arXiv abstract, HTML, versioned, and PDF URLs for the same paper collapse to
+  one canonical paper identity before source budgeting.
+- DOI and arXiv variants are merged at the work level when identifiers or a
+  sufficiently specific normalized scholarly title agree. Conflicting DOI or
+  arXiv identities always remain separate even when titles match. Distinct
+  variant URLs remain in the audit and exact-source fallback ledger.
+- Strict source policies do not fill unused capacity with blogs or social posts
+  once at least four relevant policy-compliant sources are available. This is a
+  quality floor, not a requirement to consume the configured source ceiling.
+- When a PDF is explicitly required, evidence extraction does not begin until a
+  discovered PDF has yielded readable text. A hard requirement fails closed;
+  “when available” is allowed to proceed only when no bounded PDF candidate was
+  discoverable.
 - Page bytes are bounded while streaming; extracted characters are bounded too.
+- Direct PDF candidates use a bounded 5 MiB read allowance; ordinary pages keep
+  the lower 2 MiB allowance.
 - HTML scripts, forms, navigation, footers, and similar noise are removed.
+- Access-challenge pages are explicitly rejected as unreadable evidence.
 - Retrieved text is always labeled untrusted and never treated as tool or agent
   instructions.
-- PDFs are hash-verified but not misrepresented as parsed by the dependency-free
-  page reader. A document/PDF tool remains responsible for full PDF extraction.
+- PDFs are always hash-verified. When local `pdftotext` is available, bounded
+  text and relevant passages are extracted from those exact bytes; otherwise
+  the result stays explicitly unreadable and preserves the extraction error.
 - Synthesis sees only verified evidence records. Unknown citation IDs and
   citations to sources without verified evidence are removed and reported.
 - Provider selection remains explicit. Deep research uses the active provider;
   it does not silently escape LocalLLM or DeepSeek because another API key is
   present.
+- Structured-output mode follows the active provider contract. DeepSeek and
+  LocalLLM use JSON-object output with a prompt fallback; providers that truly
+  support JSON Schema may use it. Unsupported response formats are not probed
+  on every research call.
 
 ## Quality Signals
 
@@ -160,6 +320,12 @@ prose:
 - question coverage;
 - readable source count;
 - primary/scholarly source count;
+- independent verified primary/scholarly source count;
+- duplicate scholarly variants merged before source budgeting;
+- verified first-party engineering/official source count when requested;
+- search-excerpt-only source-match count, which is diagnostic and never enters
+  synthesis or satisfies readable first-party or independent-primary verification;
+- parsed-PDF count and PDF requirement status;
 - independent-domain count;
 - exact-quote verification rate;
 - statement-level citation coverage;

package/docs/external-skill-packs.md

@@ -47,6 +47,36 @@ AgInTiFlow supports both its native frontmatter (`id`, `label`, `description`,
 `triggers`, `tools`) and the broader Agent Skills dialect used by K-Dense
 (`name`, `description`, `allowed-tools`, nested `metadata`).
 
+## Standard Local Agent Skills
+
+AgInTiFlow also discovers user-owned Agent Skills from these standard local
+locations when they exist:
+
+- `~/.agents/skills`
+- `~/.codex/skills`
+- `~/.claude/skills`
+
+This is read-only interoperability. AgInTiFlow loads only `SKILL.md`, treats its
+contents as guidance rather than executable authority, and still applies the
+normal tool, command, permission, and irreversible-action policies. Built-in,
+project-local, and reviewed SkillMesh skills continue to win on ID collisions.
+
+Override the standard roots with a path-delimited list:
+
+```bash
+AGINTIFLOW_AGENT_SKILL_PACKS=/path/to/agent-skills:/path/to/more-skills aginti skills
+```
+
+Disable ambient discovery for a hardened or fully isolated runtime:
+
+```bash
+AGINTIFLOW_DISCOVER_AGENT_SKILLS=false aginti skills
+```
+
+Selected skill context includes a bounded excerpt, section index, and the
+read-only `SKILL.md` source path. This lets a tool-capable agent inspect the full
+routine before a multi-stage task without bloating every ordinary chat turn.
+
 ## Design Rules
 
 - External packs are optional. Missing packs do not block startup.

package/docs/perception-and-web-research.md

@@ -7,10 +7,10 @@ AgInTiFlow separates visual understanding, web search, and wrapper advice so eac
 | Tool | Purpose | Evidence |
 | --- | --- | --- |
 | `read_image` | Read workspace screenshots, plots, scanned text, diagrams, or allowed remote image URLs. | Saves JSON and Markdown reports under `artifacts/perception/`, records image hashes, and sends the Markdown report to the canvas when used by an agent run. |
-| `web_search` | Cheap raw search snippets. | Returns compact titles, URLs, snippets, and fallback search URL. |
-| `read_web_page` | Read one exact public source instead of relying on a snippet. | Returns bounded article text, metadata, canonical URL, relevant passages, retrieval time, and content hash. |
+| `web_search` | Cheap raw search snippets or a bounded multi-provider ensemble. | Returns compact titles, canonical URLs, snippets, provider attempts, and per-provider discovery evidence. |
+| `read_web_page` | Read one exact public source instead of relying on a snippet. | Returns bounded article/PDF text, metadata, canonical URL, relevant passages, retrieval time, and content hash. |
 | `web_research` | Sourced research unit for current or external information. | Saves `artifacts/research/*-web-research.json` with query, mode, source list, and answer. |
-| `deep_research` | Plan, retrieve, verify, synthesize, and audit a genuinely multi-source question. | Saves resumable JSON state and a cited Markdown report with coverage metrics. |
+| `deep_research` | Plan, retrieve, verify, synthesize, and audit a genuinely multi-source question. | Saves resumable JSON state and a cited Markdown report with exact claim-evidence IDs, coverage metrics, and an optional guarded workspace `outputPath`. |
 | `research_wrapper` | Read-only strict-JSON second opinion from the selected wrapper. | Saves `artifacts/wrappers/*-research-wrapper.json` with wrapper, model, reasoning, metadata, result, and raw fallback output. |
 
 ## Defaults
@@ -20,8 +20,14 @@ AgInTiFlow separates visual understanding, web search, and wrapper advice so eac
 - Codex image reading requires both `provider=codex` and explicitly enabled wrapper tools. It is not an automatic fallback.
 - OpenAI image reading defaults to `AGINTI_PERCEPTION_MODEL=gpt-5.4-mini` and `AGINTI_PERCEPTION_REASONING=medium`, with fallback models remaining inside the same explicitly selected OpenAI provider.
 - `web_research` defaults to lightweight snippet mode. The active LocalLLM can synthesize those returned snippets and sources during the next agent step without a second provider call.
-- `web_search` automatically falls back from DuckDuckGo HTML to Bing RSS. Brave Search is available only when explicitly selected and configured.
-- `deep_research` uses the active provider for planning, evidence extraction, and synthesis. It never treats another provider's ambient credentials as permission.
+- `web_search provider=auto` falls back from DuckDuckGo HTML to Bing RSS. `provider=multi` merges both indexes and adds Brave only when explicitly configured. Standard/deep research defaults to this ensemble; quick research stays on auto.
+- Exact PDF responses are hashed first, then parsed locally with bounded `pdftotext` when available. Direct PDF candidates receive a bounded 5 MiB document allowance instead of the generic 2 MiB HTML-page allowance. An explicit original-goal PDF requirement resolves selected arXiv, ACL Anthology, OpenReview, or Nature landing pages before claim extraction; extraction failure remains visible rather than silently treating a snippet as full-paper evidence.
+- `deep_research` stays on the active provider: its fast routing model plans and extracts sources in parallel, only failed extractions retry on the stronger main model, and the main model synthesizes the verified evidence. DeepSeek JSON transformations explicitly disable thinking mode and use its supported JSON-object contract; the bounded workflow, not hidden chain-of-thought, owns decomposition and verification. A failed synthesis may fall back once to the same-provider routing model. It never treats another provider's ambient credentials as permission. Visible source citations are derived from verified claim-level evidence IDs rather than trusted directly from model output.
+- LocalLLM research reuses an already-selected resident main model for planning, extraction, and synthesis unless `deepResearchExtractionModel` is explicit. It limits extraction to two concurrent local calls by default, avoiding multi-model GPU thrash and four-way local inference contention.
+- Candidate ranking requires topical evidence, provider/query rediscovery, or an explicit domain constraint. Academic or official hosting improves source quality but does not make an irrelevant page relevant. When a strict-policy run finds at least four strongly topical sources, marginally related academic pages cannot consume the remaining source budget.
+- A domain-specific `site:` query that returns no candidates is retried once as the same plain planner query while the domain allowlist remains enforced. This bounded recovery is part of one research run, not an outer-agent manual search detour.
+- Concise planner queries are searched before the raw request, and long conversational briefs are not sent verbatim to search engines. Explicit source-count, PDF, first-party, and negative-evidence requirements remain authoritative from the original goal. Paper-oriented runs add one bounded Crossref/arXiv discovery pass and may retry it once during the single gap pass when the independently verified source minimum remains open; DOI, arXiv HTML/abstract/PDF, and version URLs are merged as one scholarly work while conflicting identifiers remain separate and exact variants remain auditable fallback paths. First-party requirements close only on readable, quote-verified content. Search excerpts and access-challenge pages remain discovery diagnostics and never enter synthesis as cited evidence. Source budgets are ceilings: once a strict source policy has at least four relevant compliant candidates, blogs, social commentary, dictionaries, citation generators, and third-party paper utilities cannot pad the set; with zero compliant candidates, strict policy fails closed.
+- A requested `deep_research outputPath` must be a Markdown file inside the active workspace. Path escapes, symlink escapes, `.git`, and `node_modules` are rejected, so an agent can deliver the requested report without reading private session artifacts.
 - `web_research mode=openai` is accepted only for an active OpenAI session or when `allowHostedWebResearch=true`. A denied or failed hosted synthesis is returned with `ok=false`; any preserved snippets are labeled fallback evidence rather than hosted success.
 - `json_specialist` stays on the active provider. A different provider requires `allowHostedJsonSpecialist=true`; ambient hosted keys and model-generated provider arguments cannot escalate a LocalLLM session.
 - `research_wrapper` defaults to `AGINTI_RESEARCH_WRAPPER_MODEL=gpt-5.4-mini` and `AGINTI_RESEARCH_WRAPPER_REASONING=medium`.

package/docs/runtime-modes-and-autonomy.md

@@ -29,10 +29,18 @@ Codex exposes these concerns as `--sandbox read-only|workspace-write|danger-full
 
 - `-s safe|normal|danger` and `/safe`, `/normal`, `/danger`
 - `--sandbox-mode host|docker-readonly|docker-workspace`
+- repeatable `--read-root /absolute/reference/repository` for structured read-only cross-repository inspection
 - `--package-install-policy block|prompt|allow`
 - `--allow-shell|--no-shell`
 - `--allow-destructive`
 
+Read roots are narrower than danger mode. `inspect_project`, `list_files`,
+`search_files`, `read_file`, and `read_image` may inspect an explicitly named
+root, while every write still remains inside `--cwd`. Use read roots for
+established sibling routines and reference repositories. Do not replace them
+with recursive `grep`; use bounded workspace search or targeted `rg` with an
+explicit path, relevant globs, and a result limit.
+
 ## Docker Package Installs
 
 Docker package installs are safe when they match the sandbox contract.

package/docs/student-committee-supervisor.md

@@ -26,12 +26,15 @@ Inside interactive chat:
 
 ## Role Contract
 
-SCS uses the selected main model for every internal role.
+SCS uses the selected main model for execution. Hosted providers use a model
+student by default. LocalLLM uses the same typed student contract with
+deterministic runtime validation so periodic checks do not repeatedly occupy
+the local inference queue.
 
 | Role | Right | Boundary |
 | --- | --- | --- |
 | Committee | Draft one next-phase plan with acceptance criteria and stop conditions. | Cannot approve plans or call tools. |
-| Student | Act as the independent validator: approve/veto the phase plan, review failure evidence, and approve/reject finish. | Cannot call tools, approve its own work, or override runtime safety. |
+| Student | Act as the independent validator: approve/veto the phase plan, review failure evidence, and approve/reject finish. The implementation may be a model or the deterministic contract/evidence engine. | Cannot call tools, approve its own work, or override runtime safety. |
 | Supervisor | Execute the approved phase with the existing browser, shell, file, canvas, and wrapper tools. | Cannot replace the strategic plan without student review. |
 
 The runtime remains the real authority for command policy, filesystem guardrails, secret redaction, session persistence, and user interruption.
@@ -45,10 +48,12 @@ When SCS is active:
 - The normal `createPlan()` path is replaced by a committee draft plus student approval.
 - An approved supervisor instruction is injected into the execution loop.
 - Failed, blocked, suspicious, or mismatched tools trigger a bounded student validator review.
-- Every fourth execution step triggers a bounded progress review for long runs.
+- Every fourth execution step triggers a bounded progress review for long runs. LocalLLM evaluates this directly from the runtime ledger without another inference call.
 - `finish` and assistant-content completion pass through a final student gate.
 - A deterministic task contract and evidence ledger are built under the student gate. The contract records required evidence categories such as file, command, artifact, browser, visual, git, or publish evidence. The ledger classifies recent tool and event evidence into those categories.
 - The final gate compares the contract, approved plan, executor finish claim, and evidence ledger. A model approval cannot override missing deterministic evidence for evidence-bearing tasks unless the run is reporting a real external blocker.
+- Audit, handoff, and readiness reports that publish command examples are source-grounded. Nonstandard command signatures must appear in an inspected Markdown code block, successful runtime command, or authoritative help output; prose that merely mentions a product or workflow cannot validate invented CLI syntax.
+- Recoverable runtime controls such as malformed-tool retries, bounded discovery caps, and repeated-read guards remain execution feedback rather than external blockers. They cannot be used to justify a false "blocked but complete" finish.
 - If the student validator rejects progress or finish, the runtime asks the committee for a new phase plan and sends that plan back through the student gate before the supervisor continues.
 - Decisions are persisted as `scs.*` events and the phase pack is saved as a session artifact.
 
@@ -59,6 +64,13 @@ The current implementation is deliberately bounded:
 - Finish rejections are capped to avoid deadlock.
 - If the monitor cannot produce strict JSON, AgInTiFlow uses a conservative fallback decision and records the parser warning.
 
+`AGINTI_SCS_VALIDATION_MODE=auto` is the default. `auto` selects deterministic
+validation for LocalLLM and model validation for hosted providers. Use `model`
+or `deterministic` only when explicitly testing one implementation. LocalLLM
+committee planning has one bounded attempt and a deterministic hard-contract
+fallback, so an unavailable or slow route model cannot turn validation into a
+multi-minute retry loop.
+
 ## Auto Mode
 
 `/scs auto` and `--scs auto` are the default for users who want cheap simple turns without losing strict validation on risky work. Auto mode activates SCS for high-risk, evidence-heavy, or long-running work. Signals include:

package/docs/supervised-capability-curriculum.md

@@ -2,6 +2,11 @@
 
 AgInTiFlow should be trained and verified by supervising real tasks, not by trusting the agent's final summary. Each curriculum run uses a clean project under `~/ProjectsLFS/Aginti-Test/`, runs AgInTiFlow through a persistent tmux session, and verifies artifacts from outside the agent.
 
+Use `scripts/supervision-ledger.js` and
+`docs/supervision-campaign-ledger.md` for the machine-readable campaign record.
+The Markdown homework ledger remains the compact human handoff; it does not
+replace the SQLite evidence record.
+
 ## Verification Contract
 
 Every supervised task must end with independent checks:

package/docs/supervision-campaign-ledger.md

@@ -0,0 +1,55 @@
+# Supervision Campaign Ledger
+
+Continuous AgInTiFlow validation uses a SQLite ledger instead of relying on a
+chat transcript. The ledger records capability coverage, realistic scenarios,
+individual test runs, runtime events, reusable fixes, versions, session IDs,
+tmux ownership, and external evidence.
+
+Initialize a campaign:
+
+```bash
+node scripts/supervision-ledger.js init \
+  --db /path/to/campaign.sqlite \
+  --campaign general-capability \
+  --objective "Make AgInTiFlow fast, robust, and generally capable" \
+  --aginti-version "$(node -p \"require('./package.json').version\")"
+```
+
+Register coverage before testing:
+
+```bash
+node scripts/supervision-ledger.js capability \
+  --db /path/to/campaign.sqlite --campaign general-capability \
+  --id media-chain --domain media --subdomain music-video-publish \
+  --description "Reuse Musia, LALACHAN, and LazyEdit without rebuilding them" \
+  --priority 90
+
+node scripts/supervision-ledger.js scenario \
+  --db /path/to/campaign.sqlite --campaign general-capability \
+  --id media-chain-readiness --domain media --profile auto \
+  --prompt-quality normal \
+  --prompt "Inspect the established media chain without generating or publishing." \
+  --expected-outputs '["media-routine-readiness.md"]' \
+  --validation "Verify exact routine paths, command help, artifact bytes, and zero external writes."
+```
+
+Create, start, and finish a concrete run with `test`, `start`, `event`, and
+`finish`. Record a reusable product change with `fix`. Every command is an
+idempotent or append-only SQLite operation suitable for a persistent tmux
+campaign.
+
+Test registration validates that any named capability and scenario belong to
+the same campaign. Finishing a test updates the test, capability, and scenario
+status in one SQLite transaction, so a typo cannot silently leave the campaign
+matrix stale or split across contradictory states.
+
+Inspect current coverage:
+
+```bash
+node scripts/supervision-ledger.js status \
+  --db /path/to/campaign.sqlite --campaign general-capability
+```
+
+Do not mark a test passed from the agent's prose. Verify session events, files,
+checks, external state, and side-effect boundaries first, then store those paths
+in `evidence_json` and `events`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lazyingart/agintiflow",
-  "version": "0.20.203",
+  "version": "0.20.205",
   "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",
@@ -62,6 +62,9 @@
     "scripts/real-deepseek-capabilities.js",
     "scripts/postinstall-webapp.js",
     "scripts/seed-supervised-homework.js",
+    "scripts/supervision-ledger.js",
+    "scripts/smoke-supervision-ledger.js",
+    "scripts/smoke-integration-production-mount.js",
     "scripts/smoke-auxiliary-tools.js",
     "scripts/smoke-agentlink.js",
     "scripts/smoke-auth.js",
@@ -71,6 +74,7 @@
     "scripts/smoke-coding-tools.js",
     "scripts/smoke-docker-command.js",
     "scripts/smoke-dynamic-step-budget.js",
+    "scripts/smoke-context-budget-recovery.js",
     "scripts/smoke-execution-policy.js",
     "scripts/smoke-capabilities.js",
     "scripts/smoke-auto-update.js",
@@ -84,6 +88,7 @@
     "scripts/smoke-progressive-tool-selection.js",
     "scripts/smoke-truthful-completion.js",
     "scripts/smoke-writing-specialist-routing.js",
+    "scripts/eval-provider-attribution.js",
     "scripts/local-first-agent-eval.mjs",
     "scripts/fixtures/local-first-agent-eval-fixtures.mjs",
     "scripts/smoke-run-stdin.js",
@@ -118,13 +123,14 @@
   "bin": {
     "aginti": "bin/aginti-cli.js",
     "aginti-cli": "bin/aginti-cli.js",
+    "aginti-integration": "bin/aginti-integration.js",
     "aginti-public-research": "bin/aginti-public-research.js",
     "aginti-safe-chat": "bin/aginti-safe-chat.js"
   },
   "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/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",
+    "check": "node --check run.js && node --check web.js && node --check bin/aginti-cli.js && node --check bin/aginti-integration.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/supervision-ledger.js && node --check scripts/smoke-supervision-ledger.js && node --check scripts/smoke-integration-production-mount.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",
@@ -176,10 +182,13 @@
     "real:deepseek": "node scripts/real-deepseek-capabilities.js",
     "postinstall": "node scripts/postinstall-webapp.js",
     "supervision:seed": "node scripts/seed-supervised-homework.js",
+    "supervision:ledger": "node scripts/supervision-ledger.js",
+    "smoke:supervision-ledger": "node scripts/smoke-supervision-ledger.js",
+    "smoke:integration-production-mount": "node scripts/smoke-integration-production-mount.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-code-routing && 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:deep-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:integration-production-mount && npm run smoke:localllm-provider && npm run smoke:localllm-model-tiers && npm run smoke:localllm-code-routing && 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:deep-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:supervision-ledger && 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"
   },