@lazyingart/agintiflow 0.12.9 → 0.13.0

package/README.md

@@ -67,7 +67,7 @@ aginti
 aginti chat
 ```
 
-Inside chat, type normal requests such as `write a small Python CLI app with tests`. The default is Docker workspace mode with approved package installs, so coding, plotting, and LaTeX tasks can set up project-local tools without touching the host. Use `/help` for commands, `/login` or `/auth` to paste a provider key, `/instructions` to inspect `AGINTI.md`, `/latex on` for PDF work, `/docker off` only when you intentionally want host mode, `/sessions` to list project runs, and `/resume latest` or `/resume <session-id>` to continue work. Type `/` then Tab for command completion. `Ctrl+J` inserts a new line in the colored input panel, Enter sends, arrow keys move through wrapped multiline input, and `Ctrl+A`/`Ctrl+E` jump to the current line start/end. During an active run, Enter sends the draft as an ASAP pipe message (`→`) and Tab queues it for after the run (`↳`); ASAP messages are consumed first, Alt+Up edits the last piped message, and Shift+Left edits the last after-finish queued message. The input panel always shows the current `cwd` footer and a single live status row, so long goals and tool updates are compacted instead of flooding the transcript. Assistant responses start on a fresh line after the `aginti>` header with a colored response gutter and render common Markdown, including headings, inline code, bold text, lists, quotes, code fences, tables, and red/green patch diff lines. Resuming a session prints a compact recent-chat preview before the prompt. Esc or Ctrl+C stops the active run cleanly and prints the resume command.
+Inside chat, type normal requests such as `write a small Python CLI app with tests`. The default is Docker workspace mode with approved package installs, so coding, plotting, and LaTeX tasks can set up project-local tools without touching the host. Use `/help` for commands, `/login` or `/auth` to paste a provider key, `/instructions` to inspect `AGINTI.md`, `/latex on` for PDF work, `/docker off` only when you intentionally want host mode, `/sessions` to list project runs, and `/resume latest` or `/resume <session-id>` to continue work. Type `/` then Tab for command completion. `Ctrl+J` inserts a new line in the colored input panel, Enter sends, arrow keys move through wrapped multiline input, and `Ctrl+A`/`Ctrl+E` jump to the current line start/end. During an active run, Enter sends the draft as an ASAP pipe message (`→`) and Tab queues it for after the run (`↳`); ASAP messages are consumed first, Alt+Up edits the last piped message, and Shift+Left edits the last after-finish queued message. The input panel always shows the current `cwd` footer and a single live status row, so long goals and tool updates are compacted instead of flooding the transcript. Assistant responses start on a fresh line after the `aginti>` header with a colored response gutter and render common Markdown, including headings, inline code, bold text, lists, quotes, code fences, tables, and red/green patch diff lines. Resuming a session prints the full saved chat history with wrapped messages before the prompt. Esc or Ctrl+C stops the active run cleanly and prints the resume command.
 
 `aginti init` creates `AGINTI.md` at the project root. This is the editable project-instruction file for both CLI and web runs, similar to `AGENTS.md` or project memory in other agents. Keep durable preferences, commands, and constraints there, but never secrets. You can edit it manually or ask in chat, for example: `update AGINTI.md to remember that this project uses pytest and npm run check`.
 
@@ -75,7 +75,9 @@ For code edits, AgInTiFlow routes patch/refactor/database-style tasks to DeepSee
 
 For larger repositories, use `--profile large-codebase` or choose **Large codebase engineering** in the web UI. The web default stays **Auto**, and Auto now escalates codebase/system/debugging prompts to the same engineering loop when needed. Complex work routes to DeepSeek v4 pro, starts with `inspect_project`, then uses search/read/patch/check loops inspired by Codex, Copilot SDK, Claude Code, Gemini CLI, Qwen, and Claw Code. See [docs/large-codebase-engineering.md](docs/large-codebase-engineering.md).
 
-AgInTiFlow can also spend cheap DeepSeek calls on parallel scout notes before the main executor starts a complicated task. Scouts run independently for architecture, implementation, review, research, context mapping, tests, git workflow, and integration risks, then a coordinator synthesis is injected for the main agent. The executor still does the real file/shell/browser work itself. Disable with `--no-parallel-scouts` or set `--scout-count 1..8`.
+AgInTiFlow can also spend cheap DeepSeek calls on parallel scout notes before the main executor starts a complicated task. It first writes a bounded project map to `.aginti/codebase-map.json`, then runs scouts for architecture, implementation, review, research, context mapping, tests, git workflow, integration, symbol tracing, and dependency risks. A coordinator Swarm Board is injected for the main agent and saved as `artifacts/scout-blackboard.json` in the session. The executor still does the real file/shell/browser work itself. Disable with `--no-parallel-scouts` or set `--scout-count 1..10`.
+
+The next productive-agent roadmap is tracked in [docs/productive-agent-roadmap.md](docs/productive-agent-roadmap.md): durable codebase maps, stronger scout blackboards, long-run checkpoints, LSP/symbol tools, test triage, and release automation.
 
 For current docs, install errors, package/toolchain setup, and source discovery, the agent has a guarded `web_search` tool. It returns compact search results without browser search-engine loops and respects configured domain allowlists. Disable with `--no-web-search`.
 

package/docs/large-codebase-engineering.md

@@ -13,6 +13,8 @@ Local agent references informed the design:
 - Claw-style `doctor` discipline: check health and environment before treating system symptoms as code bugs.
 - Claude/Codex-style context discipline: read project instructions, manifests, entry points, and failing tests before touching broad files.
 
+The shared pattern is not “put the whole repo in context.” It is: build a cheap map, choose the next exact evidence, edit with deterministic patches, verify, then compact what changed. AgInTiFlow uses cheap DeepSeek calls to add more independent eyes around that loop, not to replace it.
+
 ## Skill vs Tool
 
 The `large-codebase` profile is a skill: it changes the model’s engineering behavior. It tells DeepSeek v4 pro to orient first, plan minimally, patch incrementally, and verify.
@@ -94,11 +96,15 @@ DeepSeek calls are cheap enough that complex tasks can use several short advisor
 - Tester: finds the narrowest useful checks and setup blockers.
 - Git operator: keeps status/diff/commit/pull/push workflows disciplined.
 - Integrator: looks for cross-stream conflicts and ordering constraints.
+- Symbol tracer: predicts names, APIs, routes, schemas, and searches that connect the change.
+- Dependency doctor: checks package managers, Docker/toolchain setup, generated artifacts, and install risks.
+
+Before scouts run, AgInTiFlow builds a bounded shared context pack from a durable project map at `.aginti/codebase-map.json`: manifests, top-level files, source/test directories, package scripts, language counts, git status hints, and recommended reads. This avoids the weak pattern of each scout rediscovering the repo differently or flooding the main context with an infinite tree.
 
-Scout output is synthesized by a coordinator note and injected as advisory context only. The main agent still owns execution and must use real tools to inspect, edit, run commands, and finish. CLI flags:
+Scout output is synthesized by a coordinator Swarm Board, persisted as `artifacts/scout-blackboard.json`, and injected as advisory context only. The board records shared context, execution order, conflicts/unknowns, must-read files/checks, and stop conditions. The main agent still owns execution and must use real tools to inspect, edit, run commands, and finish. CLI flags:
 
 ```bash
-aginti --parallel-scouts --scout-count 8 "fix this complicated repo bug"
+aginti --parallel-scouts --scout-count 10 "fix this complicated repo bug"
 aginti --no-parallel-scouts "run a cheap short task"
 ```
 

package/docs/productive-agent-roadmap.md

@@ -0,0 +1,35 @@
+# Productive Agent Roadmap
+
+AgInTiFlow should become a practical coding agent, not only a chat UI around a model. DeepSeek v4 pro is strong and cheap, so the advantage is to spend more inference on context, review, and verification while keeping the main executor focused.
+
+## Lessons From Other Agents
+
+- Codex: orient with file search, edit with deterministic patches, run focused checks, and keep git status visible.
+- Claude Code: keep the terminal UX simple, project-local, resumable, and interruption-friendly.
+- Gemini CLI: expose extensibility through tools, MCP-style capabilities, large-context workflows, and auth/setup discovery.
+- Copilot SDK: make sessions, hooks, permissions, telemetry, and tool events first-class APIs.
+- Claw Code: use doctor/preflight checks, container-first execution, parity tests, and explicit lifecycle state.
+- LazyingArtBot: preserve workflow memory and artifacts so the agent can continue creative or production tasks later.
+
+## Current Strengths
+
+- Project-local CLI and web share sessions, preferences, artifacts, and `AGINTI.md`.
+- DeepSeek flash/pro routing, Docker workspace mode, web search, image generation, canvas artifacts, and guarded file tools are already wired.
+- `inspect_project`, `apply_patch`, command policy, git discipline, and the scout swarm give the model concrete tools instead of relying on memory.
+
+## Missing Productive-Agent Pieces
+
+1. Durable codebase map: cache `inspect_project`, symbol locations, test commands, package scripts, and recently changed files per project. Initial slice implemented as `.aginti/codebase-map.json` with manifests, source/test dirs, package scripts, languages, git hints, and recommended reads.
+2. Scout blackboard: let scouts write short structured findings to a shared board, then run a coordinator pass that resolves conflicts before execution. Initial slice implemented as per-session `artifacts/scout-blackboard.json` with role lanes, findings, coordinator handoff, and codebase-map metadata.
+3. Long-run checkpoints: save phase state after inspect, patch, test, repair, and commit so a long task can recover after interruption.
+4. Symbol/LSP tools: add find-definition, references, diagnostics, and document-symbols for JS/TS, Python, Rust, Go, and C/C++ where available.
+5. Test triage: parse common test failures into file, symbol, command, and likely cause so repair loops stay narrow.
+6. Patch review loop: before finalizing large edits, run a cheap reviewer scout over diffs, risks, and missing tests.
+7. Dependency doctor: detect toolchain gaps and propose Docker/project-local setup before touching host installs.
+8. Release assistant: status, diff, changelog, version bump, pack, publish, push, and rollback notes as a reusable workflow.
+
+## Swarm Design
+
+Scouts must not become noisy subagents. Each scout gets the same bounded context pack generated from the durable codebase map and one role. The coordinator produces a Swarm Board with shared context, execution order, disagreements, must-read files, checks, and stop conditions. The main agent still owns tool use and must re-read exact files before editing.
+
+Use 3 scouts for medium tasks, 5 for large tasks, and up to 10 for complex multi-language or system tasks. More scouts are only useful when their roles cover different failure modes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lazyingart/agintiflow",
-  "version": "0.12.9",
+  "version": "0.13.0",
   "type": "module",
   "description": "AgInTiFlow is a resumable Playwright website-control agent with OpenAI-compatible tool calling.",
   "license": "Apache-2.0",

package/public/app.js

@@ -1042,7 +1042,7 @@ function formPayload() {
     allowAuxiliaryTools: allowAuxiliaryToolsField?.checked ?? true,
     allowWebSearch: allowWebSearchField?.checked ?? true,
     allowParallelScouts: allowParallelScoutsField?.checked ?? true,
-    parallelScoutCount: Math.min(Math.max(Number(parallelScoutCountField?.value) || 3, 1), 8),
+    parallelScoutCount: Math.min(Math.max(Number(parallelScoutCountField?.value) || 3, 1), 10),
     allowWrapperTools: allowWrapperToolsField.checked,
     preferredWrapper: preferredWrapperField.value,
     taskProfile: taskProfileField?.value || "auto",

package/public/index.html

@@ -205,7 +205,7 @@
 
           <label>
             <span data-i18n="parallelScoutCountLabel">Scout count</span>
-            <input id="parallelScoutCount" name="parallelScoutCount" type="number" min="1" max="8" value="3" />
+            <input id="parallelScoutCount" name="parallelScoutCount" type="number" min="1" max="10" value="3" />
           </label>
 
           <div class="grid wrapper-controls">

package/scripts/smoke-cli-chat.js

@@ -150,13 +150,16 @@ try {
   if (!latest.stdout.includes("resume history") || !latest.stdout.includes("Mock run complete")) {
     throw new Error("bare aginti resume did not preview saved chat history");
   }
+  if (latest.stdout.includes("showing=") || latest.stdout.includes("…")) {
+    throw new Error("resume history should render full saved messages instead of compact previews");
+  }
 
   console.log(
     JSON.stringify(
       {
         ok: true,
         projectRoot: tempRoot,
-        checks: ["markdown-render", "markdown-table-no-duplicate", "patch-diff-render", "prompt-layout", "live-input-status-layout", "agent-response-gutter", "aginti-md", "instructions-command", "instructions-chat-edit", "interactive-chat", "mock-file-write", "run-status", "resume-latest", "resume-history-preview"],
+        checks: ["markdown-render", "markdown-table-no-duplicate", "patch-diff-render", "prompt-layout", "live-input-status-layout", "agent-response-gutter", "aginti-md", "instructions-command", "instructions-chat-edit", "interactive-chat", "mock-file-write", "run-status", "resume-latest", "resume-history-full"],
       },
       null,
       2

package/scripts/smoke-coding-tools.js

@@ -5,9 +5,10 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { repairModelMessageHistory, runAgent } from "../src/agent-runner.js";
 import { resolveRuntimeConfig } from "../src/config.js";
+import { readCodebaseMap } from "../src/codebase-map.js";
 import { engineeringGuidanceForTask, recommendedMaxStepsForTask } from "../src/engineering-guidance.js";
 import { selectModelRoute } from "../src/model-routing.js";
-import { shouldRunParallelScouts } from "../src/parallel-scouts.js";
+import { listParallelScouts, runParallelScouts, shouldRunParallelScouts } from "../src/parallel-scouts.js";
 import { SessionStore } from "../src/session-store.js";
 import { searchWeb } from "../src/web-search.js";
 import { executeWorkspaceTool } from "../src/workspace-tools.js";
@@ -127,6 +128,16 @@ try {
     ),
     "parallel scouts did not enable for complex auto task"
   );
+  const scoutNames = listParallelScouts().map((scout) => scout.name);
+  assert(scoutNames.length >= 10, "parallel scout roster did not expose 10 scout roles");
+  for (const expectedScout of ["cartographer", "git-operator", "integrator", "symbol-tracer", "dependency-doctor"]) {
+    assert(scoutNames.includes(expectedScout), `parallel scout roster missing ${expectedScout}`);
+  }
+  const scoutConfig = resolveRuntimeConfig(
+    { provider: "mock", parallelScoutCount: 99, commandCwd: workspace },
+    { baseDir: runtimeDir, packageDir: repoRoot, provider: "mock", commandCwd: workspace }
+  );
+  assert(scoutConfig.parallelScoutCount === 10, "parallel scout count did not clamp to 10");
   const drySearch = await searchWeb(
     { query: "AgInTiFlow web_search smoke", maxResults: 2 },
     { allowWebSearch: true, webSearchDryRun: true }
@@ -166,6 +177,62 @@ try {
   assert(inspected.sourceDirs.some((item) => item.path === "src"), "inspect_project did not identify src directory");
   assert(inspected.testFiles.some((item) => item.path === "test/index.test.js"), "inspect_project did not identify test file");
   assert(inspected.recommendedReads.includes("package.json"), "inspect_project did not recommend package.json");
+  const fakeScoutPrompts = [];
+  const fakeScoutClient = {
+    chat: {
+      completions: {
+        create: async ({ messages }) => {
+          const systemContent = messages.find((message) => message.role === "system")?.content || "";
+          const userContent = messages.find((message) => message.role === "user")?.content || "";
+          fakeScoutPrompts.push(userContent);
+          const role = userContent.match(/Scout role: ([^\n]+)/)?.[1] || "coordinator";
+          return {
+            choices: [
+              {
+                message: {
+                  content: systemContent.includes("synthesize")
+                    ? "Swarm Board: read package.json first, inspect src/test, patch narrowly, run npm test, stop on unrelated git changes."
+                    : `Advice from ${role}: use the shared context pack and inspect package.json before editing.`,
+                },
+              },
+            ],
+          };
+        },
+      },
+    },
+  };
+  const scoutRun = await runParallelScouts(
+    fakeScoutClient,
+    {
+      provider: "deepseek",
+      model: "deepseek-v4-flash",
+      commandCwd: workspace,
+      allowFileTools: true,
+      parallelScoutCount: 10,
+      goal: "fix this complicated repo test bug",
+      taskProfile: "large-codebase",
+      sandboxMode: "host",
+      packageInstallPolicy: "block",
+    },
+    { goal: "fix this complicated repo test bug", meta: {}, plan: "Inspect and patch." }
+  );
+  assert(scoutRun.requested === 10 && scoutRun.completed === 10, "parallel scout fake run did not complete 10 scouts");
+  assert(scoutRun.contextPack.includes("package.json"), "parallel scout context pack did not include manifest evidence");
+  assert(scoutRun.summary.includes("## shared context pack"), "parallel scout summary omitted shared context pack");
+  assert(scoutRun.summary.includes("## coordinator"), "parallel scout summary omitted coordinator synthesis");
+  assert(scoutRun.codebaseMap?.fingerprint, "parallel scout run did not return durable codebase map metadata");
+  assert(scoutRun.blackboard?.lanes?.length === 10, "parallel scout blackboard did not include all scout lanes");
+  assert(scoutRun.blackboard?.coordinator.includes("Swarm Board"), "parallel scout blackboard did not retain coordinator synthesis");
+  assert(
+    fakeScoutPrompts.filter((prompt) => /Shared context pack:[\s\S]*package\.json/.test(prompt)).length >= 10,
+    "parallel scouts did not receive the shared context pack"
+  );
+  const codebaseMap = await readCodebaseMap(workspace);
+  assert(codebaseMap.ok && codebaseMap.map.fingerprint === scoutRun.codebaseMap.fingerprint, "durable codebase map was not persisted");
+  const blackboardStore = new SessionStore(runtimeDir, "blackboard-smoke");
+  const blackboardPath = await blackboardStore.saveJsonArtifact("scout-blackboard.json", scoutRun.blackboard);
+  const blackboardJson = JSON.parse(await fs.readFile(blackboardPath, "utf8"));
+  assert(blackboardJson.lanes.length === 10, "scout blackboard artifact did not persist lanes");
 
   const inspectRun = await runMock("Inspect this large codebase and recommend next reads.", "coding-inspect");
   assert(
@@ -306,8 +373,13 @@ try {
           "auto_system_pro_route",
           "auto_engineering_guidance",
           "parallel_scout_trigger",
+          "parallel_scout_roster",
+          "parallel_scout_count_clamp",
           "web_search_dry_run",
           "inspect_project",
+          "parallel_scout_context_pack",
+          "durable_codebase_map",
+          "scout_blackboard",
           "mock_inspect_project",
           "write_file",
           "duplicate_write_failed",

package/src/agent-runner.js

@@ -1170,11 +1170,17 @@ export async function runAgent(config) {
 
     if (shouldRunParallelScouts(config, state)) {
       const scouts = await runParallelScouts(client, config, state);
+      const blackboardPath = scouts.blackboard
+        ? await store.saveJsonArtifact("scout-blackboard.json", scouts.blackboard).catch(() => "")
+        : "";
       state.meta.parallelScoutsCompleted = true;
       state.meta.parallelScouts = {
         model: scouts.model,
         requested: scouts.requested,
         completed: scouts.completed,
+        codebaseMap: scouts.codebaseMap || null,
+        blackboardPath,
+        contextPack: scouts.contextPack ? scouts.contextPack.slice(0, 1200) : "",
         synthesis: scouts.synthesis || "",
       };
       state.messages.push({
@@ -1185,7 +1191,11 @@ export async function runAgent(config) {
         model: scouts.model,
         requested: scouts.requested,
         completed: scouts.completed,
+        codebaseMap: scouts.codebaseMap || null,
+        blackboardPath,
+        contextPack: scouts.contextPack || "",
         synthesis: scouts.synthesis || "",
+        blackboard: scouts.blackboard || null,
         scouts: scouts.scouts.map((scout) => ({
           name: scout.name,
           model: scout.model,
@@ -1198,6 +1208,7 @@ export async function runAgent(config) {
         model: scouts.model,
         requested: scouts.requested,
         completed: scouts.completed,
+        blackboardPath,
       });
       emitConsole(config, `Parallel scouts: ${scouts.completed}/${scouts.requested} completed using ${scouts.model}`, {
         kind: "meta",

package/src/capabilities.js

@@ -8,6 +8,7 @@ import { listProjectSessions, projectPaths, providerKeyStatus, readProjectInstru
 import { listTaskProfiles } from "./task-profiles.js";
 import { listAgentWrappers } from "./tool-wrappers.js";
 import { listAuxiliarySkills } from "./auxiliary-tools.js";
+import { readCodebaseMap } from "./codebase-map.js";
 
 const execFileAsync = promisify(execFile);
 
@@ -110,7 +111,7 @@ function trustedDockerPolicyChecks(config) {
 export async function buildCapabilityReport(projectRoot, packageVersion, config) {
   const paths = projectPaths(projectRoot);
   const keyStatus = providerKeyStatus(projectRoot);
-  const [node, npm, python, conda, r, pdflatex, latexmk, dockerStatus, sessions, instructions] = await Promise.all([
+  const [node, npm, python, conda, r, pdflatex, latexmk, dockerStatus, sessions, instructions, codebaseMap] = await Promise.all([
     commandAvailable("node", ["--version"]),
     commandAvailable("npm", ["--version"]),
     commandAvailable("python3", ["--version"]),
@@ -121,6 +122,7 @@ export async function buildCapabilityReport(projectRoot, packageVersion, config)
     getDockerSandboxStatus(config).catch((error) => ({ ok: false, error: error.message })),
     listProjectSessions(projectRoot, 12),
     readProjectInstructions(projectRoot, { maxBytes: 1 }),
+    readCodebaseMap(projectRoot),
   ]);
 
   const npmPrefixPolicy = evaluateCommandPolicy("npm --prefix round9-node-app test", config);
@@ -179,6 +181,13 @@ export async function buildCapabilityReport(projectRoot, packageVersion, config)
       sessionsDir: paths.sessionsDir,
       sessionDbPath: paths.sessionDbPath,
       sharedSessionFolder: path.resolve(config.sessionsDir) === path.resolve(paths.sessionsDir),
+      codebaseMap: {
+        present: Boolean(codebaseMap.ok),
+        path: paths.codebaseMapPath,
+        generatedAt: codebaseMap.ok ? codebaseMap.map.generatedAt || "" : "",
+        fingerprint: codebaseMap.ok ? codebaseMap.map.fingerprint || "" : "",
+        summary: codebaseMap.ok ? codebaseMap.map.inspection?.summary || "" : "",
+      },
     },
     routing: {
       active: {

package/src/cli.js

@@ -261,7 +261,7 @@ export function parseArgs(argv) {
 
 function printUsage() {
   console.log(
-    'Usage: aginti [chat] OR aginti web [--port 3210] OR aginti login deepseek|openai|grsai OR aginti resume [latest|<session-id>] ["prompt"] OR aginti queue <session-id> "message" OR aginti [--image] [--latex] [--routing smart|fast|complex|manual] [--provider deepseek|openai|mock] [--sandbox-mode host|docker-readonly|docker-workspace] [--package-install-policy block|prompt|allow] [--approve-package-installs] [--allow-shell|--no-shell] [--allow-file-tools|--no-file-tools] [--web-search|--no-web-search] [--parallel-scouts|--no-parallel-scouts --scout-count 1..8] [--allow-auxiliary-tools|--no-auxiliary-tools] [--allow-wrappers --wrapper codex] [--sandbox-status|--sandbox-preflight] "your task"'
+    'Usage: aginti [chat] OR aginti web [--port 3210] OR aginti login deepseek|openai|grsai OR aginti resume [latest|<session-id>] ["prompt"] OR aginti queue <session-id> "message" OR aginti [--image] [--latex] [--routing smart|fast|complex|manual] [--provider deepseek|openai|mock] [--sandbox-mode host|docker-readonly|docker-workspace] [--package-install-policy block|prompt|allow] [--approve-package-installs] [--allow-shell|--no-shell] [--allow-file-tools|--no-file-tools] [--web-search|--no-web-search] [--parallel-scouts|--no-parallel-scouts --scout-count 1..10] [--allow-auxiliary-tools|--no-auxiliary-tools] [--allow-wrappers --wrapper codex] [--sandbox-status|--sandbox-preflight] "your task"'
   );
 }
 

package/src/codebase-map.js

@@ -0,0 +1,151 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { projectPaths } from "./project.js";
+import { redactSensitiveText } from "./redaction.js";
+import { executeWorkspaceTool } from "./workspace-tools.js";
+
+const MAP_VERSION = 1;
+const DEFAULT_CONTEXT_PACK_CHARS = 3800;
+
+function stableHash(value) {
+  return crypto.createHash("sha256").update(JSON.stringify(value)).digest("hex").slice(0, 16);
+}
+
+function truncateText(text, limit = DEFAULT_CONTEXT_PACK_CHARS) {
+  const value = String(text || "");
+  if (value.length <= limit) return value;
+  return `${value.slice(0, Math.max(limit - 80, 1))}\n... [truncated ${value.length - limit + 80} chars]`;
+}
+
+function listValues(items, limit, mapper) {
+  const values = Array.isArray(items) ? items.slice(0, limit).map(mapper).filter(Boolean) : [];
+  if (!values.length) return "";
+  const suffix = Array.isArray(items) && items.length > limit ? `, ... +${items.length - limit}` : "";
+  return `${values.join(", ")}${suffix}`;
+}
+
+function packageScriptValues(scripts) {
+  if (!Array.isArray(scripts) || !scripts.length) return "";
+  return listValues(scripts, 14, (item) => `${item.name}: ${item.command}`);
+}
+
+function compactInspection(inspected) {
+  return {
+    summary: inspected.summary || "",
+    counts: inspected.counts || {},
+    truncated: Boolean(inspected.truncated),
+    topLevel: Array.isArray(inspected.topLevel) ? inspected.topLevel.slice(0, 80) : [],
+    manifestFiles: Array.isArray(inspected.manifestFiles) ? inspected.manifestFiles.slice(0, 80) : [],
+    sourceDirs: Array.isArray(inspected.sourceDirs) ? inspected.sourceDirs.slice(0, 60) : [],
+    testFiles: Array.isArray(inspected.testFiles) ? inspected.testFiles.slice(0, 80) : [],
+    packageManagers: Array.isArray(inspected.packageManagers) ? inspected.packageManagers.slice(0, 20) : [],
+    packageScripts: Array.isArray(inspected.packageScripts) ? inspected.packageScripts.slice(0, 30) : [],
+    languageCounts: Array.isArray(inspected.languageCounts) ? inspected.languageCounts.slice(0, 30) : [],
+    git: inspected.git || {},
+    recommendedReads: Array.isArray(inspected.recommendedReads) ? inspected.recommendedReads.slice(0, 40) : [],
+    engineeringHints: Array.isArray(inspected.engineeringHints) ? inspected.engineeringHints.slice(0, 20) : [],
+  };
+}
+
+export function codebaseMapToContextPack(map, { maxChars = DEFAULT_CONTEXT_PACK_CHARS } = {}) {
+  if (!map?.inspection) return "Context pack: no durable codebase map available.";
+  const inspected = map.inspection;
+  const sections = [
+    `Context pack for ${map.commandCwd || map.projectRoot}`,
+    `Map: version=${map.version} generatedAt=${map.generatedAt} fingerprint=${map.fingerprint}`,
+    `Summary: ${inspected.summary || "no summary"}`,
+    inspected.counts
+      ? `Counts: files=${inspected.counts.files} dirs=${inspected.counts.directories} bytes=${inspected.counts.totalBytes}`
+      : "",
+    `Top level: ${listValues(inspected.topLevel, 20, (item) => `${item.type}:${item.path}`)}`,
+    `Manifests: ${listValues(inspected.manifestFiles, 18, (item) => item.path)}`,
+    `Source dirs: ${listValues(inspected.sourceDirs, 14, (item) => item.path)}`,
+    `Tests: ${listValues(inspected.testFiles, 18, (item) => item.path)}`,
+    `Package managers: ${listValues(inspected.packageManagers, 8, (item) => item.name || item.path || item)}`,
+    packageScriptValues(inspected.packageScripts) ? `Package scripts: ${packageScriptValues(inspected.packageScripts)}` : "",
+    `Languages: ${listValues(inspected.languageCounts, 10, (item) => `${item.name}:${item.count}`)}`,
+    inspected.git?.present
+      ? `Git: present; start with ${inspected.git.recommendedCommands?.join(" && ") || "git status --short"}; ${inspected.git.workflow}`
+      : "Git: not detected at workspace root.",
+    `Recommended reads: ${listValues(inspected.recommendedReads, 16, (item) => item)}`,
+    `Engineering hints: ${listValues(inspected.engineeringHints, 8, (item) => item)}`,
+  ].filter(Boolean);
+  return truncateText(redactSensitiveText(sections.join("\n")), maxChars);
+}
+
+export async function readCodebaseMap(projectRoot = process.cwd()) {
+  const paths = projectPaths(projectRoot);
+  try {
+    const raw = await fs.readFile(paths.codebaseMapPath, "utf8");
+    return {
+      ok: true,
+      path: paths.codebaseMapPath,
+      map: JSON.parse(raw),
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      path: paths.codebaseMapPath,
+      reason: error?.code === "ENOENT" ? "missing" : error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+export async function refreshCodebaseMap(config, options = {}) {
+  if (!config.allowFileTools) {
+    return { ok: false, reason: "workspace file tools disabled" };
+  }
+  const projectRoot = path.resolve(options.projectRoot || config.commandCwd || config.baseDir || process.cwd());
+  const paths = projectPaths(projectRoot);
+  const inspected = await executeWorkspaceTool(
+    "inspect_project",
+    {
+      path: options.path || ".",
+      maxDepth: options.maxDepth || 4,
+      limit: options.limit || 1000,
+      includeFiles: Boolean(options.includeFiles),
+    },
+    {
+      ...config,
+      commandCwd: projectRoot,
+      allowFileTools: true,
+    }
+  );
+
+  if (!inspected?.ok) {
+    return {
+      ok: false,
+      path: paths.codebaseMapPath,
+      reason: inspected?.reason || inspected?.error || "inspect_project failed",
+    };
+  }
+
+  const inspection = compactInspection(inspected);
+  const fingerprint = stableHash({
+    summary: inspection.summary,
+    counts: inspection.counts,
+    manifests: inspection.manifestFiles.map((item) => item.path),
+    sourceDirs: inspection.sourceDirs.map((item) => item.path),
+    tests: inspection.testFiles.map((item) => item.path),
+    packageScripts: inspection.packageScripts,
+    languages: inspection.languageCounts,
+  });
+  const map = {
+    version: MAP_VERSION,
+    generatedAt: new Date().toISOString(),
+    projectRoot: paths.root,
+    commandCwd: projectRoot,
+    fingerprint,
+    inspection,
+  };
+
+  await fs.mkdir(paths.controlDir, { recursive: true });
+  await fs.writeFile(paths.codebaseMapPath, `${JSON.stringify(map, null, 2)}\n`, "utf8");
+  return {
+    ok: true,
+    path: paths.codebaseMapPath,
+    map,
+    contextPack: codebaseMapToContextPack(map),
+  };
+}

package/src/config.js

@@ -102,7 +102,7 @@ export function resolveRuntimeConfig(args, overrides = {}) {
     parallelScoutCount: clampNumber(
       parseNumber(overrides.parallelScoutCount ?? args.parallelScoutCount ?? process.env.AGINTI_SCOUT_COUNT, 3),
       1,
-      8
+      10
     ),
     preferredWrapper: normalizeWrapperName(
       overrides.preferredWrapper ?? args.preferredWrapper ?? process.env.PREFERRED_WRAPPER ?? process.env.AGENT_WRAPPER

package/src/interactive-cli.js

@@ -351,6 +351,20 @@ function printPreviewBlock(role, text, { time = "", bg = ansi.systemBg, maxLines
   }
 }
 
+function printHistoryBlock(role, text, { time = "", bg = ansi.systemBg } = {}) {
+  const header = [label(role, bg).trimEnd(), time ? color(time, ansi.dim) : ""].filter(Boolean).join(" ");
+  outputLine(header);
+  const width = Math.max(terminalWidth() - 8, 38);
+  const rendered = stripMarkdown(text)
+    .split(/\r?\n/)
+    .map((line) => line.trimEnd());
+  const lines = rendered.length ? rendered : ["(empty)"];
+  for (const line of lines) {
+    const wrapped = wrapTextLine(line || " ", width);
+    for (const wrappedLine of wrapped) outputLine(`${color(" | ", bg)} ${wrappedLine}`);
+  }
+}
+
 function printSystemLine(text) {
   if (!String(text || "").trim()) {
     outputLine("");
@@ -468,7 +482,7 @@ function printHelp() {
       "  /sessions                 List recent sessions in this project.",
       "  /profile <name>           Set task profile, e.g. code, website, latex, maintenance.",
       "  /web-search on|off        Enable or disable the web_search tool.",
-      "  /scouts on|off|<1-8>      Enable parallel DeepSeek scouts and set scout count.",
+      "  /scouts on|off|<1-10>     Enable parallel DeepSeek scouts and set scout count.",
       "  /routing <mode>           Set routing: smart, fast, complex, manual.",
       "  /provider <name>          Set provider: deepseek, openai, mock.",
       "  /model <name>             Set an explicit model, or /model auto.",
@@ -1298,20 +1312,14 @@ async function latestSession() {
   return sessions[0] || null;
 }
 
-function compactHistoryText(content = "", limit = 170) {
-  const rendered = stripAnsi(stripMarkdown(String(content || "")));
-  return compactLine(rendered.replace(/\s+/g, " "), limit);
-}
-
 function printHistoryEntry(entry) {
   const role = entry.role === "assistant" ? "aginti" : entry.role === "user" ? "user" : String(entry.role || "note");
   const bg = role === "aginti" ? ansi.agentBg : role === "user" ? ansi.userBg : ansi.systemBg;
   const time = entry.at ? new Date(entry.at).toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" }) : "";
-  const maxLines = role === "aginti" ? 4 : 3;
-  printPreviewBlock(role, compactHistoryText(entry.content, 520), { time, bg, maxLines });
+  printHistoryBlock(role, entry.content, { time, bg });
 }
 
-async function printResumeHistory(state, { limit = 8 } = {}) {
+async function printResumeHistory(state, { limit = 0 } = {}) {
   if (!state.sessionId) return;
   const store = new SessionStore(projectPaths(process.cwd()).sessionsDir, state.sessionId);
   const saved = await store.loadState().catch(() => null);
@@ -1321,8 +1329,10 @@ async function printResumeHistory(state, { limit = 8 } = {}) {
     return;
   }
 
-  const shown = chat.slice(-limit);
-  printSystemLine(`resume history session=${state.sessionId} showing=${shown.length}/${chat.length}`);
+  const shown = limit > 0 ? chat.slice(-limit) : chat;
+  printSystemLine(
+    `resume history session=${state.sessionId} messages=${chat.length}${limit > 0 ? ` showing=${shown.length}/${chat.length}` : ""}`
+  );
   for (const entry of shown) printHistoryEntry(entry);
 }
 
@@ -1596,7 +1606,7 @@ async function handleCommand(line, state, packageDir) {
     } else {
       state.allowParallelScouts = true;
       const count = Number(value);
-      if (Number.isFinite(count) && count > 0) state.parallelScoutCount = Math.min(Math.max(count, 1), 8);
+      if (Number.isFinite(count) && count > 0) state.parallelScoutCount = Math.min(Math.max(count, 1), 10);
     }
     printSystemLine(`parallelScouts=${state.allowParallelScouts ? "on" : "off"} count=${state.parallelScoutCount}`);
     return true;

package/src/parallel-scouts.js

@@ -2,6 +2,10 @@ import { engineeringGuidanceForTask } from "./engineering-guidance.js";
 import { getModelPresets } from "./model-routing.js";
 import { getTaskProfile, normalizeTaskProfile } from "./task-profiles.js";
 import { redactSensitiveText } from "./redaction.js";
+import { refreshCodebaseMap } from "./codebase-map.js";
+
+const MAX_CONTEXT_PACK_CHARS = 3800;
+const MAX_SCOUT_CONTENT_CHARS = 1200;
 
 const SCOUTS = [
   {
@@ -44,8 +48,22 @@ const SCOUTS = [
     prompt:
       "Look across workstreams for conflicts, shared files, ordering constraints, and what each scout might be missing. Keep it execution-focused.",
   },
+  {
+    name: "symbol-tracer",
+    prompt:
+      "Infer likely symbols, APIs, routes, commands, schemas, or config keys that connect the change. Suggest exact searches before editing.",
+  },
+  {
+    name: "dependency-doctor",
+    prompt:
+      "Identify dependency, environment, package-manager, Docker, and generated-artifact risks. Prefer project-local or sandboxed setup and focused verification.",
+  },
 ];
 
+export function listParallelScouts() {
+  return SCOUTS.map((scout) => ({ name: scout.name, prompt: scout.prompt }));
+}
+
 function shouldUseComplexScouts(config, state) {
   const profile = normalizeTaskProfile(config.taskProfile);
   const goal = String(config.goal || state.goal || "");
@@ -70,20 +88,64 @@ function scoutModel(config) {
   return config.model;
 }
 
-function scoutMessages(config, state, scout) {
+function truncateText(text, limit = MAX_CONTEXT_PACK_CHARS) {
+  const value = String(text || "");
+  if (value.length <= limit) return value;
+  return `${value.slice(0, limit - 80)}\n... [truncated ${value.length - limit + 80} chars]`;
+}
+
+async function buildScoutContextPack(config) {
+  if (!config.allowFileTools) {
+    return {
+      text: "Context pack: workspace file tools are disabled. Scouts should recommend the minimal inspection commands/files instead of assuming repository structure.",
+      codebaseMap: null,
+    };
+  }
+
+  try {
+    const refreshed = await refreshCodebaseMap(config, { maxDepth: 4, limit: 1000, includeFiles: false });
+    if (!refreshed?.ok) {
+      return {
+        text: `Context pack: inspect_project unavailable (${refreshed?.reason || refreshed?.error || "unknown error"}).`,
+        codebaseMap: null,
+      };
+    }
+    return {
+      text: truncateText(redactSensitiveText(refreshed.contextPack || "")),
+      codebaseMap: {
+        path: refreshed.path,
+        generatedAt: refreshed.map.generatedAt,
+        fingerprint: refreshed.map.fingerprint,
+        summary: refreshed.map.inspection?.summary || "",
+      },
+    };
+  } catch (error) {
+    return {
+      text: `Context pack: inspect_project failed (${redactSensitiveText(error instanceof Error ? error.message : String(error))}).`,
+      codebaseMap: null,
+    };
+  }
+}
+
+function capScoutContent(content) {
+  return truncateText(redactSensitiveText(content || "").trim(), MAX_SCOUT_CONTENT_CHARS);
+}
+
+function scoutMessages(config, state, scout, contextPack) {
   const profile = getTaskProfile(config.taskProfile);
   const guidance = engineeringGuidanceForTask(config.goal || state.goal || "", config.taskProfile);
   return [
     {
       role: "system",
       content:
-        "You are a parallel scout for AgInTiFlow. Your answer is advisory only: do not claim work is done, do not ask questions, do not use tools, and keep under 180 words.",
+        "You are a parallel scout for AgInTiFlow. Your answer is advisory only: do not claim work is done, do not ask questions, do not use tools, and keep under 180 words. Work from the shared context pack and state dependencies on other scout roles when relevant.",
     },
     {
       role: "user",
       content: [
         `Scout role: ${scout.name}`,
         scout.prompt,
+        `Shared context pack:\n${contextPack}`,
         `Goal: ${config.goal || state.goal || ""}`,
         `Task profile: ${profile.label}. ${profile.prompt}`,
         guidance,
@@ -100,7 +162,7 @@ function scoutMessages(config, state, scout) {
   ];
 }
 
-async function synthesizeScouts(client, config, model, scouts) {
+async function synthesizeScouts(client, config, model, scouts, contextPack) {
   const usable = scouts.filter((scout) => scout.content);
   if (usable.length < 2) return "";
   const response = await client.chat.completions.create(
@@ -111,11 +173,13 @@ async function synthesizeScouts(client, config, model, scouts) {
         {
           role: "system",
           content:
-            "You synthesize parallel coding-agent scout notes. Produce a compact execution brief under 220 words. Resolve conflicts, identify shared context, and list stop conditions. Do not claim work is done.",
+            "You synthesize parallel coding-agent scout notes into a Swarm Board. Produce under 320 words with: shared context, execution order, conflicts/unknowns, must-read files/checks, and stop conditions. Prefer concrete paths/commands from the context pack. Do not claim work is done.",
         },
         {
           role: "user",
-          content: usable.map((scout) => `## ${scout.name}\n${scout.content}`).join("\n\n"),
+          content: [`## shared context pack\n${contextPack}`, ...usable.map((scout) => `## ${scout.name}\n${scout.content}`)].join(
+            "\n\n"
+          ),
         },
       ],
     },
@@ -124,24 +188,58 @@ async function synthesizeScouts(client, config, model, scouts) {
   return redactSensitiveText(response.choices[0]?.message?.content || "").trim();
 }
 
+function extractFindings(content) {
+  return String(content || "")
+    .split(/\r?\n/)
+    .map((line) => line.trim().replace(/^[-*]\s+/, "").replace(/^\d+\.\s+/, ""))
+    .filter((line) => line && line.length > 8)
+    .slice(0, 6);
+}
+
+function buildScoutBlackboard({ config, state, model, requested, completed, scouts, contextPack, codebaseMap, synthesis }) {
+  return {
+    version: 1,
+    generatedAt: new Date().toISOString(),
+    goal: config.goal || state.goal || "",
+    model,
+    requested,
+    completed,
+    codebaseMap,
+    contextPack,
+    coordinator: synthesis || "",
+    lanes: scouts.map((scout) => ({
+      role: scout.name,
+      model: scout.model || model,
+      status: scout.content ? "completed" : "failed",
+      findings: scout.content ? extractFindings(scout.content) : [],
+      content: scout.content || "",
+      error: scout.error || "",
+    })),
+    handoff:
+      "Use this blackboard as advisory shared context. The executor must still inspect exact files, patch deterministically, run focused checks, and stop on conflicts or unrelated dirty work.",
+  };
+}
+
 export async function runParallelScouts(client, config, state) {
   const count = Math.min(Math.max(Number(config.parallelScoutCount) || 3, 1), SCOUTS.length);
   const selected = SCOUTS.slice(0, count);
   const model = scoutModel(config);
+  const context = await buildScoutContextPack(config);
+  const contextPack = context.text;
   const settled = await Promise.allSettled(
     selected.map(async (scout) => {
       const response = await client.chat.completions.create(
         {
           model,
           temperature: 0,
-          messages: scoutMessages(config, state, scout),
+          messages: scoutMessages(config, state, scout, contextPack),
         },
         config.abortSignal ? { signal: config.abortSignal } : undefined
       );
       return {
         name: scout.name,
         model,
-        content: redactSensitiveText(response.choices[0]?.message?.content || "").trim(),
+        content: capScoutContent(response.choices[0]?.message?.content || ""),
       };
     })
   );
@@ -157,12 +255,13 @@ export async function runParallelScouts(client, config, state) {
   const completed = scouts.filter((scout) => scout.content).length;
   const synthesis =
     completed > 1
-      ? await synthesizeScouts(client, config, model, scouts).catch((error) =>
+      ? await synthesizeScouts(client, config, model, scouts, contextPack).catch((error) =>
           `Synthesis failed: ${redactSensitiveText(error instanceof Error ? error.message : String(error))}`
         )
       : "";
   const summary = [
-    "Parallel scout notes. Treat these as advisory, not completed work.",
+    "Parallel scout swarm notes. Treat these as advisory shared context, not completed work.",
+    `\n## shared context pack\n${contextPack}`,
     synthesis ? `\n## coordinator\n${synthesis}` : "",
     ...scouts.map((scout) =>
       scout.content ? `\n## ${scout.name}\n${scout.content}` : `\n## ${scout.name}\nScout failed: ${scout.error || "unknown error"}`
@@ -170,6 +269,17 @@ export async function runParallelScouts(client, config, state) {
   ]
     .filter(Boolean)
     .join("\n");
+  const blackboard = buildScoutBlackboard({
+    config,
+    state,
+    model,
+    requested: selected.length,
+    completed,
+    scouts,
+    contextPack,
+    codebaseMap: context.codebaseMap,
+    synthesis,
+  });
 
   return {
     ok: completed > 0,
@@ -177,6 +287,9 @@ export async function runParallelScouts(client, config, state) {
     requested: selected.length,
     completed,
     scouts,
+    contextPack,
+    codebaseMap: context.codebaseMap,
+    blackboard,
     synthesis,
     summary,
   };

package/src/project.js

@@ -33,6 +33,7 @@ export function projectPaths(projectRoot = process.cwd()) {
     rootEnvPath: path.join(root, ".env"),
     envExamplePath: path.join(root, ".aginti", ".env.example"),
     controlReadmePath: path.join(root, ".aginti", "README.md"),
+    codebaseMapPath: path.join(root, ".aginti", "codebase-map.json"),
     notesDir: path.join(root, "notes"),
     notesReadmePath: path.join(root, "notes", "README.md"),
     sessionsDir: path.join(root, ".sessions"),
@@ -195,6 +196,7 @@ export async function initProject(projectRoot = process.cwd()) {
       "- `../AGINTI.md` stores editable project instructions for CLI and web agents.",
       "- `.env` is ignored and can hold local provider keys.",
       "- `.env.example` documents accepted variable names.",
+      "- `codebase-map.json` is a generated, ignored project-intelligence cache.",
       "- `.sessions/` at the project root stores CLI and web run history.",
       "",
     ].join("\n")
@@ -227,6 +229,7 @@ export async function initProject(projectRoot = process.cwd()) {
     ".aginti/.env",
     ".aginti/.env.*",
     "!.aginti/.env.example",
+    ".aginti/codebase-map.json",
     ".sessions/",
   ]);
   if (gitignore.changed) updated.push(paths.gitignorePath);

package/src/session-store.js

@@ -38,6 +38,15 @@ export class SessionStore {
     await fs.writeFile(this.planPath, `${planText.trim()}\n`, "utf8");
   }
 
+  async saveJsonArtifact(filename, data) {
+    await this.ensure();
+    const safeName = path.basename(String(filename || "artifact.json"));
+    const outputName = safeName.endsWith(".json") ? safeName : `${safeName}.json`;
+    const filePath = path.join(this.artifactsDir, outputName);
+    await fs.writeFile(filePath, `${JSON.stringify(data, null, 2)}\n`, "utf8");
+    return filePath;
+  }
+
   async appendEvent(type, data = {}) {
     await this.ensure();
     const line = JSON.stringify({