@lazyingart/agintiflow 0.20.299 → 0.20.301

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

@@ -6,7 +6,7 @@ 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. |
+| `read_image` | Read workspace screenshots, plots, scanned text, diagrams, or allowed remote image URLs. | Saves canonical JSON/Markdown evidence in the session artifact store, keeps the workspace-relative canvas copy under ignored `.aginti/artifacts/perception/`, and records image hashes. |
 | `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. |
@@ -18,6 +18,7 @@ AgInTiFlow separates visual understanding, web search, and wrapper advice so eac
 - In a LocalLLM session, `read_image provider=auto` sends bounded image data to the loopback LocalLLM Chat Completions endpoint with `AGINTI_LOCALLLM_VISION_MODEL` or `localllm-vision-xl`. It does not try OpenAI or a wrapper after a local failure.
 - In an OpenAI session, `read_image provider=auto` uses OpenAI Responses vision. A non-OpenAI session must set `allowHostedImagePerception=true` before `provider=openai` is accepted. `OPENAI_API_KEY` by itself grants no permission.
 - Codex image reading requires both `provider=codex` and explicitly enabled wrapper tools. It is not an automatic fallback.
+- Visual verification never creates a task-owned `artifacts/perception/` tree. Its workspace-relative Markdown copy stays under ignored `.aginti/` storage so a successful review cannot dirty an otherwise clean repository.
 - 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 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.

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

@@ -132,6 +132,10 @@ This starts interactive chat with Docker workspace mode, file tools, shell tools
 
 Docker workspace mode also mounts common host data roots, such as the user's home parent, read-only at their original absolute paths. This lets a task in `/home/lachlan/ProjectsLFS/aginti-test` inspect a sibling dataset such as `/home/lachlan/ProjectsLFS/ProteinStructure` without switching to host-write mode. Outputs and edits still belong under `/workspace` unless the user explicitly approves stronger host permissions. Set `AGINTI_DOCKER_READONLY_HOST_MOUNTS=/path/a:/path/b` to override the read-only mounts, or set it to `off` to disable them.
 
+For a linked Git worktree, bounded Git mutation commands such as the runtime's path-enumerated `git add` plus `git commit` also receive a writable mount for the validated shared Git common directory. The mount is not added to ordinary shell commands or read-only Git inspection. This lets Docker workspace mode commit the current worktree without granting broad host-write access.
+
+Outstanding exact project commands always run before Git completion. A pending producer, test, or user-declared validation command cannot be preempted by a commit merely because the current artifacts already exist.
+
 Direct trusted host mode:
 
 ```bash

package/docs/supervision-campaign-ledger.md

@@ -56,6 +56,45 @@ in `evidence_json` and `events`.
 
 ## Current Campaign Findings
 
+### Established media-chain reuse and permission boundaries
+
+`media-chain-readiness-020` passed after reconciling a stale machine-ledger
+`running` row with the retained session's terminal `session.finished` event.
+AgInTi inspected the existing Musia, LabCanvas, LALACHAN, Xiaoyunque, and
+LazyEdit entry points and produced `media-routine-readiness.md` without
+generating media, starting or focusing a browser, uploading, copying to
+Nutstore, creating a remote job, or publishing.
+
+The independent acceptance contract verified every required source-grounded
+entry, 16 read-only command results, zero forbidden external-action tools, and
+zero long jobs. The resulting contract keeps four permissions independent:
+reviewed-song generation, music-video generation, LazyEdit processing, and
+public platform publication. An earlier stage or old context cannot authorize a
+later irreversible stage.
+
+### Retained dependencies, linked-worktree commits, and clean visual evidence
+
+`data-analysis-retained-dependencies-060` resumed the original DeepSeek session
+after an imperfect data-analysis repair had narrowed its context too far. The
+agent retained the immutable configuration and CSV inputs referenced by the
+mutable Python source, regenerated every required output, ran the canonical
+producer and all four unit tests, inspected the 900 x 600 plot, and committed
+target revision `55cadcd` from Docker workspace mode. Independent verification
+confirmed 11 raw rows, one duplicate removal, two invalid-signal removals,
+eight clean rows, the expected condition means, valid CSV/JSON/Markdown/PNG
+artifacts, and a clean target worktree.
+
+The run established three reusable runtime contracts:
+
+- Failed-test recovery keeps bounded, previously read immutable dependencies
+  when the mutable source names them, while mutation scope remains limited to
+  the canonical repair paths.
+- An outstanding exact producer or validation command runs before artifact Git
+  completion. In a linked worktree, only bounded Git mutation commands receive
+  a writable mount for the validated shared Git common directory.
+- `read_image` stores its task-relative review copy under ignored `.aginti/`
+  runtime storage, so visual verification cannot dirty a completed repository.
+
 ### Data analysis retained-state recovery
 
 `data-analysis-local-011` passed after reusable runtime fixes. AgInTi completed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lazyingart/agintiflow",
-  "version": "0.20.299",
+  "version": "0.20.301",
   "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",

package/scripts/smoke-docker-command.js

@@ -7,6 +7,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
 import {
+  dockerWritableGitMounts,
   dockerWorkspaceAliasMounts,
   ensureDockerGitIdentity,
 } from "../src/docker-sandbox.js";
@@ -52,6 +53,47 @@ try {
   assert.equal(storedEmail.stdout.trim(), "aginti-test@example.invalid");
   assert.equal((await fs.stat(identityConfig)).mode & 0o777, 0o600, "Docker author config should be private");
 
+  const worktreeRoot = path.join(tempRoot, "worktree-root");
+  const linkedWorktree = path.join(tempRoot, "linked-worktree");
+  await execFileAsync("git", ["init", worktreeRoot]);
+  await execFileAsync("git", ["-C", worktreeRoot, "config", "user.name", "AgInTi Test Author"]);
+  await execFileAsync("git", ["-C", worktreeRoot, "config", "user.email", "aginti-test@example.invalid"]);
+  await fs.writeFile(path.join(worktreeRoot, "seed.txt"), "seed\n", "utf8");
+  await execFileAsync("git", ["-C", worktreeRoot, "add", "seed.txt"]);
+  await execFileAsync("git", ["-C", worktreeRoot, "commit", "-m", "seed"]);
+  await execFileAsync("git", ["-C", worktreeRoot, "worktree", "add", "-b", "linked-test", linkedWorktree]);
+  const linkedCommonDir = (await execFileAsync(
+    "git",
+    ["-C", linkedWorktree, "rev-parse", "--path-format=absolute", "--git-common-dir"]
+  )).stdout.trim();
+  assert.deepEqual(
+    dockerWritableGitMounts(
+      "git add -- changed.txt && git commit -m 'linked worktree change'",
+      { commandCwd: linkedWorktree, sandboxMode: "docker-workspace" },
+      { gitOnly: true }
+    ),
+    [linkedCommonDir],
+    "Docker Git mutation did not mount validated linked-worktree metadata writable"
+  );
+  assert.deepEqual(
+    dockerWritableGitMounts(
+      "git status --short",
+      { commandCwd: linkedWorktree, sandboxMode: "docker-workspace" },
+      { gitOnly: true }
+    ),
+    [],
+    "read-only Git inspection received an unnecessary writable metadata mount"
+  );
+  assert.deepEqual(
+    dockerWritableGitMounts(
+      "git add -- seed.txt",
+      { commandCwd: worktreeRoot, sandboxMode: "docker-workspace" },
+      { gitOnly: true }
+    ),
+    [],
+    "ordinary repositories should rely on the existing writable workspace mount"
+  );
+
   const { stdout } = await execFileAsync(process.execPath, [path.join(repoRoot, "bin/aginti-cli.js"), "docker", "status", "--json", "--cwd", tempRoot], {
     cwd: tempRoot,
     env: {

package/scripts/smoke-dynamic-step-budget.js

@@ -572,6 +572,98 @@ try {
       duplicateFocus?.duplicateDeclarations?.[0]?.name === "status_service",
     "duplicate production declarations were not promoted into a focused failed-test repair"
   );
+  const dependencyRecoveryWorkspace = path.join(tempRoot, "dependency-recovery-workspace");
+  await fs.mkdir(path.join(dependencyRecoveryWorkspace, "config"), { recursive: true });
+  await fs.mkdir(path.join(dependencyRecoveryWorkspace, "raw"), { recursive: true });
+  await fs.mkdir(path.join(dependencyRecoveryWorkspace, "tests"), { recursive: true });
+  await fs.writeFile(
+    path.join(dependencyRecoveryWorkspace, "analysis.py"),
+    [
+      "from pathlib import Path",
+      "import json",
+      "",
+      "ROOT = Path(__file__).resolve().parent",
+      "config = json.loads((ROOT / 'config' / 'experiment.json').read_text())",
+      "for source_file in ('run_a.csv', 'run_b.csv'):",
+      "    print((ROOT / 'raw' / source_file).read_text())",
+      "",
+    ].join("\n"),
+    "utf8"
+  );
+  await fs.writeFile(
+    path.join(dependencyRecoveryWorkspace, "tests", "test_analysis.py"),
+    "from analysis import config\n",
+    "utf8"
+  );
+  await fs.writeFile(
+    path.join(dependencyRecoveryWorkspace, "config", "experiment.json"),
+    '{"offset":10}\n',
+    "utf8"
+  );
+  await fs.writeFile(
+    path.join(dependencyRecoveryWorkspace, "raw", "run_a.csv"),
+    "sample,signal\nA,100\n",
+    "utf8"
+  );
+  await fs.writeFile(
+    path.join(dependencyRecoveryWorkspace, "raw", "run_b.csv"),
+    "sample,signal\nB,90\n",
+    "utf8"
+  );
+  await fs.writeFile(
+    path.join(dependencyRecoveryWorkspace, "raw", "unrelated.csv"),
+    "private,unrelated\nno,1\n",
+    "utf8"
+  );
+  const dependencyRecoveryState = {
+    meta: {
+      projectVerification: {
+        mutationRevision: 2,
+        lastMutation: {
+          revision: 2,
+          toolName: "apply_patch",
+          paths: ["analysis.py"],
+        },
+        discoveredTests: ["tests/test_analysis.py"],
+        testRuns: [{
+          command: "python analysis.py",
+          mutationRevision: 2,
+          passed: false,
+          failureEvidenceVersion: 2,
+          failureSignature: "source-dependency-schema-mismatch",
+          failureSummary: "File \"analysis.py\", line 7, in <module>: KeyError: signal_mv",
+        }],
+      },
+      toolLoop: {
+        recent: [
+          "config/experiment.json",
+          "raw/run_a.csv",
+          "raw/run_b.csv",
+          "raw/unrelated.csv",
+        ].map((readPath) => ({
+          toolName: "read_file",
+          path: readPath,
+          ok: true,
+          blocked: false,
+        })),
+      },
+    },
+  };
+  const dependencyRecoveryPacket = await buildFailedTestRecoveryPacket(
+    { commandCwd: dependencyRecoveryWorkspace },
+    dependencyRecoveryState
+  );
+  assert(
+    [
+      "analysis.py",
+      "config/experiment.json",
+      "raw/run_a.csv",
+      "raw/run_b.csv",
+    ].every((item) => dependencyRecoveryPacket.paths.includes(item)) &&
+      !dependencyRecoveryPacket.paths.includes("raw/unrelated.csv") &&
+      JSON.stringify(dependencyRecoveryPacket.repairPaths) === JSON.stringify(["analysis.py"]),
+    `failed-test recovery dropped previously read immutable dependencies or widened mutation scope: ${JSON.stringify(dependencyRecoveryPacket)}`
+  );
   const baselineWorkspace = path.join(tempRoot, "baseline-recovery-workspace");
   await fs.mkdir(baselineWorkspace, { recursive: true });
   const trackedBaselineSource = [

package/scripts/smoke-model-roles.js

@@ -31,14 +31,23 @@ import {
 } from "../src/scs-controller.js";
 import {
   buildScsEvidenceLedger,
+  buildTmuxGitIntent,
   deriveScsTaskContract,
   evaluateScsEvidence,
   gitActionsSatisfyContract,
   inferSuccessfulGitActionsFromCommandResult,
+  inferSuccessfulGitActionsFromTmuxCapture,
+  reconcileTmuxGitEvidenceEvents,
 } from "../src/scs-evidence.js";
 import { resolveRuntimeConfig } from "../src/config.js";
 import { classifyGoalIntent, isDirectAnswerIntent } from "../src/goal-intent.js";
 import { languageWriterDefaults } from "../src/writing-specialist.js";
+import {
+  attachVerifiedTmuxGitEvidence,
+  recordDurableEvidenceCategories,
+  rememberTmuxGitIntent,
+  sanitizeToolResult,
+} from "../src/agent-runner.js";
 
 const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 for (const key of [
@@ -1117,6 +1126,195 @@ assert(
     !committedEvaluation.missing.some((item) => item.category === "git"),
   "a successful git commit did not satisfy the explicit git requirement"
 );
+const tmuxCommitCommand = [
+  'echo "===AGINTI_REVIEW_COMMIT_START==="',
+  'git add README.md && git commit -m "finish review"',
+  'echo "===COMMIT_EXIT:$?==="',
+].join(" ; ");
+const tmuxCommitIntent = buildTmuxGitIntent(tmuxCommitCommand);
+assert(
+  tmuxCommitIntent?.actions.includes("commit") &&
+    tmuxCommitIntent.markers.includes("===AGINTI_REVIEW_COMMIT_START==="),
+  "a marked workspace tmux commit command did not retain bounded Git intent"
+);
+const tmuxCommitCapture = {
+  ok: true,
+  toolName: "tmux_capture_pane",
+  target: "review:0.0",
+  content: [
+    "===AGINTI_REVIEW_COMMIT_START===",
+    "[review abc1234] finish review",
+    " 1 file changed, 2 insertions(+)",
+    "===COMMIT_EXIT:0===",
+  ].join("\n"),
+};
+const verifiedTmuxCommit = inferSuccessfulGitActionsFromTmuxCapture(
+  tmuxCommitIntent,
+  tmuxCommitCapture
+);
+assert(
+  verifiedTmuxCommit.length === 1 && verifiedTmuxCommit[0] === "commit",
+  "a fresh marked tmux capture did not prove its successful Git commit"
+);
+assert(
+  inferSuccessfulGitActionsFromTmuxCapture(tmuxCommitIntent, {
+    ...tmuxCommitCapture,
+    content: tmuxCommitCapture.content.replace("COMMIT_EXIT:0", "COMMIT_EXIT:1"),
+  }).length === 0,
+  "a nonzero tmux commit exit marker was accepted as Git evidence"
+);
+assert(
+  inferSuccessfulGitActionsFromTmuxCapture(tmuxCommitIntent, {
+    ...tmuxCommitCapture,
+    content: tmuxCommitCapture.content.replace("AGINTI_REVIEW_COMMIT_START", "STALE_COMMIT_START"),
+  }).length === 0,
+  "a tmux capture without the current command marker was accepted as fresh Git evidence"
+);
+const tmuxEvidenceState = {
+  meta: {
+    goalContract: { revision: 2 },
+    projectVerification: { mutationRevision: 3 },
+  },
+};
+const tmuxSendResult = {
+  ok: true,
+  toolName: "tmux_send_keys",
+  target: "review:0.0",
+  sentTextSha256: "a".repeat(64),
+};
+rememberTmuxGitIntent(
+  tmuxEvidenceState,
+  { text: tmuxCommitCommand },
+  tmuxSendResult
+);
+const trackedTmuxCapture = { ...tmuxCommitCapture };
+assert(
+  attachVerifiedTmuxGitEvidence(tmuxEvidenceState, trackedTmuxCapture).includes("commit"),
+  "the same-pane tmux capture did not close the pending Git intent"
+);
+recordDurableEvidenceCategories(tmuxEvidenceState, trackedTmuxCapture);
+assert(
+  tmuxEvidenceState.meta.durableGitEvidence.some(
+    (item) =>
+      item.action === "commit" &&
+      item.goalRevision === 2 &&
+      item.mutationRevision === 3
+  ),
+  "verified tmux commit evidence was not retained at the active goal and mutation revision"
+);
+assert(
+  !tmuxEvidenceState.meta.pendingTmuxGitEvidence["review:0.0"],
+  "verified tmux Git intent remained pending after same-pane capture"
+);
+const tmuxCommitLedger = buildScsEvidenceLedger({
+  context: {
+    events: [
+      {
+        type: "tool.completed",
+        data: {
+          ...tmuxCommitCapture,
+          verifiedGitActions: verifiedTmuxCommit,
+          verifiedGitGoalRevision: 1,
+          verifiedGitMutationRevision: 1,
+        },
+      },
+    ],
+  },
+});
+assert(
+  evaluateScsEvidence(commitContract, tmuxCommitLedger).missingGitActions.length === 0,
+  "verified tmux commit evidence did not satisfy the completion contract"
+);
+const historicalTmuxEvents = [
+  { type: "goal.updated", data: { revision: 2 } },
+  {
+    type: "tool.completed",
+    data: {
+      ok: true,
+      toolName: "run_command",
+      goalRevision: 2,
+      projectMutationRevision: 3,
+      args: { command: "git status --short" },
+      exitCode: 0,
+      stdout: " M README.md",
+    },
+  },
+  {
+    type: "tool.started",
+    data: {
+      toolName: "tmux_send_keys",
+      args: { target: "review:0.0", text: tmuxCommitCommand },
+    },
+  },
+  {
+    type: "tool.completed",
+    data: {
+      ...tmuxSendResult,
+      target: "review:0.0",
+    },
+  },
+  {
+    type: "tool.completed",
+    data: {
+      ...tmuxCommitCapture,
+      content: undefined,
+      contentPreview: tmuxCommitCapture.content,
+    },
+  },
+];
+const reconciledHistoricalEvents = reconcileTmuxGitEvidenceEvents(
+  historicalTmuxEvents
+);
+assert(
+  reconciledHistoricalEvents.at(-1)?.data?.verifiedGitActions?.includes("commit") &&
+    reconciledHistoricalEvents.at(-1)?.data?.verifiedGitGoalRevision === 2 &&
+    reconciledHistoricalEvents.at(-1)?.data?.verifiedGitMutationRevision === 3,
+  "restart reconciliation did not recover revision-scoped tmux commit evidence"
+);
+assert(
+  evaluateScsEvidence(
+    commitContract,
+    buildScsEvidenceLedger({ context: { events: historicalTmuxEvents } })
+  ).missingGitActions.length === 0,
+  "historical marked tmux commit events did not satisfy the completion contract"
+);
+for (const invalidEvents of [
+  historicalTmuxEvents.map((event, index) =>
+    index === 3 ? { ...event, type: "tool.failed", data: { ...event.data, ok: false } } : event
+  ),
+  historicalTmuxEvents.map((event, index) =>
+    index === 4 ? { ...event, data: { ...event.data, target: "other:0.0" } } : event
+  ),
+  historicalTmuxEvents.map((event, index) =>
+    index === 4
+      ? {
+          ...event,
+          data: {
+            ...event.data,
+            contentPreview: event.data.contentPreview.replace("COMMIT_EXIT:0", "COMMIT_EXIT:1"),
+          },
+        }
+      : event
+  ),
+]) {
+  assert(
+    !reconcileTmuxGitEvidenceEvents(invalidEvents).at(-1)?.data?.verifiedGitActions,
+    "failed, cross-pane, or nonzero historical tmux evidence was accepted"
+  );
+}
+const sanitizedLongTmuxCapture = sanitizeToolResult({
+  ...tmuxCommitCapture,
+  content: `${"old scrollback\n".repeat(200)}${tmuxCommitCapture.content}`,
+});
+assert(
+  sanitizedLongTmuxCapture.contentTruncated === true &&
+    sanitizedLongTmuxCapture.contentTail.includes("===COMMIT_EXIT:0===") &&
+    inferSuccessfulGitActionsFromTmuxCapture(
+      tmuxCommitIntent,
+      sanitizedLongTmuxCapture
+    ).includes("commit"),
+  "truncated tmux evidence did not preserve and verify its bounded content tail"
+);
 const recoveredCommitActions = inferSuccessfulGitActionsFromCommandResult({
   ok: true,
   exitCode: 0,

package/scripts/smoke-perception-research.js

@@ -343,6 +343,10 @@ async function main() {
   assert(image.artifactPath, "read_image did not persist a perception artifact");
   assert(image.markdownArtifactPath, "read_image did not persist a Markdown perception artifact");
   assert(image.markdownPath, "read_image did not persist a workspace Markdown report");
+  assert(
+    image.markdownPath.startsWith(".aginti/artifacts/perception/"),
+    `read_image dirtied the task-owned artifact tree: ${image.markdownPath}`
+  );
   assert(
     path.basename(image.markdownPath).includes("tiny-image-analysis"),
     `read_image emitted a generic artifact filename: ${image.markdownPath}`

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

@@ -1584,6 +1584,30 @@ assertStrict.deepEqual(
   "task-owned Git completion delegated path selection back to the model"
 );
 
+const requiredCommandBeforeCommitTools = selectProgressiveTools(allTools, {
+  config: {
+    provider: "localllm",
+    artifactValidationPhase: true,
+    artifactValidationNeedsCommand: true,
+    requiredProjectCommandPending: true,
+    requiredProjectCommand: "python analysis.py",
+    artifactValidationPendingGitActions: ["commit"],
+    artifactValidationCommitPaths: ["analysis.py", "AGINTI.md"],
+  },
+  goal: "Regenerate the outputs, validate them, and commit the intended repair.",
+  profile: "data",
+});
+sameNames(
+  requiredCommandBeforeCommitTools,
+  ["run_command", "finish"],
+  "artifact Git completion preempted an outstanding exact project command"
+);
+assertStrict.deepEqual(
+  requiredCommandBeforeCommitTools[0].function.parameters.properties.command.enum,
+  ["python analysis.py"],
+  "artifact recovery exposed an open-ended command instead of the retained requirement"
+);
+
 const resumedArtifactRuntime = nextStepRuntimeConfig(
   {
     goal: "Perform a visual screenshot inspection of the generated plot and commit the intentional changes.",

package/src/agent-runner.js

@@ -147,9 +147,11 @@ import {
   finishResultClaimsBlocker,
   finishResultClaimsIncompleteWork,
   hasScsBlockerEvidence,
+  buildTmuxGitIntent,
   inferAuthoritativeReadOnlyRoutine,
   inferGitActionsFromCommand,
   inferSuccessfulGitActionsFromCommandResult,
+  inferSuccessfulGitActionsFromTmuxCapture,
   isResponseOnlyEvidenceScope,
   successfulGitCommitProvesFileMutation,
   isObservationalGitAction,
@@ -8495,7 +8497,7 @@ export function taskForbidsExternalValidatorSourceRead(config = {}, state = {})
 function recoveryEvidenceDependencies(
   sourcePath = "",
   content = "",
-  { commandCwd = "" } = {}
+  { commandCwd = "", knownReadPaths = [] } = {}
 ) {
   const explicitDependencies = [];
   const importCandidates = [];
@@ -8531,7 +8533,7 @@ function recoveryEvidenceDependencies(
     append(explicitDependencies, path.posix.normalize(raw));
   }
   for (const match of String(content || "").matchAll(
-    /^\s*[A-Za-z_][A-Za-z0-9_]*\s*=\s*[A-Za-z_][A-Za-z0-9_]*(?<segments>(?:\s*\/\s*["'][^"'\r\n]+["']){1,8})\s*$/gm
+    /\b[A-Za-z_][A-Za-z0-9_]*(?<segments>(?:\s*\/\s*["'][^"'\r\n]+["']){1,8})/g
   )) {
     const segments = [...String(match.groups?.segments || "").matchAll(/["']([^"'\r\n]+)["']/g)]
       .map((segment) => String(segment[1] || "").trim())
@@ -8540,6 +8542,22 @@ function recoveryEvidenceDependencies(
       append(explicitDependencies, path.posix.normalize(segments.join("/")));
     }
   }
+  const sourceText = String(content || "");
+  for (const item of Array.isArray(knownReadPaths) ? knownReadPaths : []) {
+    const candidate = safeRecoveryEvidencePath(item);
+    if (!candidate || safeTaskOwnedCommitPath(candidate) !== candidate) continue;
+    const basename = path.posix.basename(candidate);
+    const parentBasename = path.posix.basename(path.posix.dirname(candidate));
+    if (!basename || !sourceText.includes(basename)) continue;
+    if (
+      parentBasename &&
+      parentBasename !== "." &&
+      !sourceText.includes(parentBasename)
+    ) {
+      continue;
+    }
+    append(explicitDependencies, candidate);
+  }
   if (path.posix.extname(sourcePath).toLowerCase() === ".java") {
     const normalizedSource = String(sourcePath || "").replace(/\\/g, "/");
     const packageMatch = String(content || "").match(
@@ -8960,6 +8978,19 @@ export async function buildFailedTestRecoveryPacket(config = {}, state = {}) {
     state,
     testRun
   );
+  const knownReadPaths = (Array.isArray(state.meta?.toolLoop?.recent)
+    ? state.meta.toolLoop.recent
+    : [])
+    .filter(
+      (entry) =>
+        entry?.ok === true &&
+        entry?.blocked !== true &&
+        String(entry?.toolName || "") === "read_file"
+    )
+    .map((entry) => safeRecoveryEvidencePath(toolLoopReadEvidencePath(entry) || entry?.path))
+    .filter((item) => item && safeTaskOwnedCommitPath(item) === item)
+    .filter((item, index, items) => items.indexOf(item) === index)
+    .slice(-24);
   const queue = [
     ...failureMentionedPaths.filter(failedTestPathIsTestEvidence),
     ...(Array.isArray(verification.discoveredTests) ? verification.discoveredTests : []),
@@ -9536,7 +9567,10 @@ export async function buildFailedTestRecoveryPacket(config = {}, state = {}) {
         );
       }
     }
-    for (const dependency of recoveryEvidenceDependencies(relativePath, raw, { commandCwd })) {
+    for (const dependency of recoveryEvidenceDependencies(relativePath, raw, {
+      commandCwd,
+      knownReadPaths,
+    })) {
       if (!seen.has(dependency) && !queue.includes(dependency)) queue.push(dependency);
     }
   }
@@ -9756,6 +9790,9 @@ export function sanitizeToolResult(result) {
       safeResult.contentTruncated = false;
     } else {
       safeResult.contentPreview = safeResult.content.slice(0, TOOL_RESULT_CONTENT_PREVIEW_CHARS);
+      if (safeResult.toolName === "tmux_capture_pane") {
+        safeResult.contentTail = safeResult.content.slice(-TOOL_RESULT_CONTENT_PREVIEW_CHARS);
+      }
       safeResult.contentTruncated = true;
       delete safeResult.content;
     }
@@ -13746,7 +13783,55 @@ export function mergeDurableGitEvidence(
   return [...merged.values()].slice(-Math.max(1, Number(limit || 40)));
 }
 
-function recordDurableEvidenceCategories(state = {}, toolResult = {}) {
+export function rememberTmuxGitIntent(state = {}, args = {}, toolResult = {}) {
+  const gitIntent = toolResult?.ok ? buildTmuxGitIntent(args.text || "") : null;
+  if (!gitIntent || !toolResult?.target) return null;
+  state.meta = state.meta || {};
+  const pendingByTarget = state.meta.pendingTmuxGitEvidence || {};
+  const pending = {
+    ...gitIntent,
+    target: toolResult.target,
+    sentTextSha256: toolResult.sentTextSha256,
+    goalRevision: Math.max(0, Number(state.meta?.goalContract?.revision || 0)),
+    mutationRevision: Math.max(
+      0,
+      Number(state.meta?.projectVerification?.mutationRevision || 0)
+    ),
+  };
+  pendingByTarget[toolResult.target] = pending;
+  state.meta.pendingTmuxGitEvidence = Object.fromEntries(
+    Object.entries(pendingByTarget).slice(-8)
+  );
+  toolResult.tmuxGitIntentActions = gitIntent.actions;
+  toolResult.tmuxGitIntentMarkers = gitIntent.markers;
+  return pending;
+}
+
+export function attachVerifiedTmuxGitEvidence(state = {}, toolResult = {}) {
+  const pendingByTarget = state.meta?.pendingTmuxGitEvidence || {};
+  const pending = pendingByTarget[toolResult?.target];
+  const verifiedGitActions = inferSuccessfulGitActionsFromTmuxCapture(
+    pending,
+    toolResult
+  );
+  if (!verifiedGitActions.length) return [];
+  toolResult.verifiedGitActions = verifiedGitActions;
+  toolResult.verifiedGitSource = "tmux_capture_pane";
+  toolResult.verifiedGitGoalRevision = Math.max(
+    0,
+    Number(pending.goalRevision || 0)
+  );
+  toolResult.verifiedGitMutationRevision = Math.max(
+    0,
+    Number(pending.mutationRevision || 0)
+  );
+  toolResult.verifiedGitCommandSha256 = String(pending.sentTextSha256 || "");
+  delete pendingByTarget[toolResult.target];
+  state.meta.pendingTmuxGitEvidence = pendingByTarget;
+  return verifiedGitActions;
+}
+
+export function recordDurableEvidenceCategories(state = {}, toolResult = {}) {
   if (!toolResult || toolResult.ok === false || toolResult.blocked || toolResult.skipped) return;
   state.meta = state.meta || {};
   const categories = new Set(
@@ -13766,33 +13851,50 @@ function recordDurableEvidenceCategories(state = {}, toolResult = {}) {
     categories.add("artifact");
   }
   if (toolName === "read_image") categories.add("visual");
+  const gitActions = toolName === "run_command" && Number(toolResult.exitCode ?? 0) === 0
+    ? inferSuccessfulGitActionsFromCommandResult(toolResult)
+    : Array.isArray(toolResult.verifiedGitActions)
+      ? toolResult.verifiedGitActions
+      : [];
   if (toolName === "run_command" && Number(toolResult.exitCode ?? 0) === 0) {
     categories.add("command");
     const command = String(toolResult.args?.command || "").trim();
-    const gitActions = inferSuccessfulGitActionsFromCommandResult(toolResult);
-    if (gitActions.length) {
-      categories.add("git");
-      if (successfulGitCommitProvesFileMutation(toolResult)) categories.add("file");
-      state.meta.durableGitActions = [
-        ...new Set([
-          ...(Array.isArray(state.meta.durableGitActions) ? state.meta.durableGitActions : []),
-          ...gitActions,
-        ]),
-      ];
-      const goalRevision = Math.max(0, Number(state.meta?.goalContract?.revision || 0));
-      const existingGitEvidence = Array.isArray(state.meta.durableGitEvidence)
-        ? state.meta.durableGitEvidence
-        : [];
-      state.meta.durableGitEvidence = mergeDurableGitEvidence(existingGitEvidence, gitActions, {
-        goalRevision,
-        mutationRevision: Math.max(
-          0,
-          Number(state.meta?.projectVerification?.mutationRevision || 0)
-        ),
-      });
-    }
     if (/\b(?:pytest|unittest|npm\s+test|pnpm\s+test|yarn\s+test)\b/i.test(command)) categories.add("test");
   }
+  if (gitActions.length) {
+    categories.add("git");
+    if (
+      successfulGitCommitProvesFileMutation(toolResult) ||
+      (gitActions.includes("commit") && toolResult.verifiedGitSource === "tmux_capture_pane")
+    ) {
+      categories.add("file");
+    }
+    state.meta.durableGitActions = [
+      ...new Set([
+        ...(Array.isArray(state.meta.durableGitActions) ? state.meta.durableGitActions : []),
+        ...gitActions,
+      ]),
+    ];
+    const goalRevision = Math.max(
+      0,
+      Number(toolResult.verifiedGitGoalRevision ?? state.meta?.goalContract?.revision ?? 0)
+    );
+    const mutationRevision = Math.max(
+      0,
+      Number(
+        toolResult.verifiedGitMutationRevision ??
+          state.meta?.projectVerification?.mutationRevision ??
+          0
+      )
+    );
+    const existingGitEvidence = Array.isArray(state.meta.durableGitEvidence)
+      ? state.meta.durableGitEvidence
+      : [];
+    state.meta.durableGitEvidence = mergeDurableGitEvidence(existingGitEvidence, gitActions, {
+      goalRevision,
+      mutationRevision,
+    });
+  }
   state.meta.durableEvidenceCategories = [...categories];
 }
 
@@ -18727,6 +18829,7 @@ async function executeTool(browserState, toolCall, snapshot, config, store, obse
       }
       case "tmux_capture_pane": {
         const result = await captureTmuxPane(args, config);
+        attachVerifiedTmuxGitEvidence(state, result);
         const eventResult = sanitizeToolResult(result);
         await store.appendEvent(result.ok ? "tool.completed" : "tool.failed", eventResult);
         observers.event(result.ok ? "tool.completed" : "tool.failed", eventResult);
@@ -18734,6 +18837,7 @@ async function executeTool(browserState, toolCall, snapshot, config, store, obse
       }
       case "tmux_send_keys": {
         const result = await sendTmuxKeys(args, config);
+        rememberTmuxGitIntent(state, args, result);
         const eventResult = sanitizeToolResult(result);
         await store.appendEvent(result.ok ? "tool.completed" : "tool.failed", eventResult);
         observers.event(result.ok ? "tool.completed" : "tool.failed", eventResult);

package/src/docker-sandbox.js

@@ -196,6 +196,63 @@ export function dockerWorkspaceAliasMounts(
   return workspace === DOCKER_WORKSPACE ? [] : [workspace];
 }
 
+function pathIsWithin(parentPath, candidatePath) {
+  const relative = path.relative(parentPath, candidatePath);
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+function linkedWorktreeCommonGitDir(workspace) {
+  const dotGitPath = path.join(workspace, ".git");
+  let dotGit;
+  try {
+    if (!fsSync.statSync(dotGitPath).isFile()) return "";
+    dotGit = fsSync.readFileSync(dotGitPath, "utf8");
+  } catch {
+    return "";
+  }
+  const match = String(dotGit).match(/^gitdir:\s*(.+?)\s*$/im);
+  if (!match?.[1]) return "";
+  const gitDir = path.resolve(workspace, match[1]);
+  let commonDir = gitDir;
+  try {
+    const commonPath = path.join(gitDir, "commondir");
+    if (fsSync.existsSync(commonPath)) {
+      commonDir = path.resolve(gitDir, fsSync.readFileSync(commonPath, "utf8").trim());
+    }
+    const resolvedGitDir = fsSync.realpathSync(gitDir);
+    const resolvedCommonDir = fsSync.realpathSync(commonDir);
+    if (
+      !pathIsWithin(resolvedCommonDir, resolvedGitDir) ||
+      !fsSync.existsSync(path.join(resolvedCommonDir, "HEAD")) ||
+      !fsSync.existsSync(path.join(resolvedCommonDir, "objects"))
+    ) {
+      return "";
+    }
+    return resolvedCommonDir;
+  } catch {
+    return "";
+  }
+}
+
+export function dockerWritableGitMounts(
+  command = "",
+  config = {},
+  policy = {},
+  sandboxMode = normalizeSandboxMode(config.sandboxMode)
+) {
+  if (
+    sandboxMode !== "docker-workspace" ||
+    policy.gitOnly !== true ||
+    !/\bgit\s+(?:add|commit|rm|mv)\b/i.test(String(command || ""))
+  ) {
+    return [];
+  }
+  const workspace = path.resolve(String(config.commandCwd || process.cwd()));
+  const commonDir = linkedWorktreeCommonGitDir(workspace);
+  if (!commonDir || pathIsWithin(workspace, commonDir)) return [];
+  return uniqueHostMounts([commonDir]);
+}
+
 async function ensurePersistentDockerDirs(config) {
   const dirs = persistentDockerDirs(config);
   await Promise.all([fs.mkdir(dirs.home, { recursive: true }), fs.mkdir(dirs.cache, { recursive: true }), fs.mkdir(dirs.env, { recursive: true })]);
@@ -381,6 +438,12 @@ function dockerRunArgs(command, config, policy = evaluateCommandPolicy(command,
     "-v",
     `${mount}:${mount}:${mountMode}`,
   ]);
+  const writableGitMountArgs = dockerWritableGitMounts(
+    command,
+    config,
+    policy,
+    sandboxMode
+  ).flatMap((mount) => ["-v", `${mount}:${mount}:rw`]);
   const readOnlyArgs =
     mountMode === "ro"
       ? ["--read-only", "--tmpfs", "/tmp:rw,nosuid,nodev,size=128m"]
@@ -412,6 +475,7 @@ function dockerRunArgs(command, config, policy = evaluateCommandPolicy(command,
       ? ["-e", `GIT_CONFIG_GLOBAL=${DOCKER_GIT_CONFIG}`]
       : []),
     ...readOnlyHostMountArgs,
+    ...writableGitMountArgs,
     ...workspaceAliasMountArgs,
     "-v",
     `${config.commandCwd}:${DOCKER_WORKSPACE}:${mountMode}`,

package/src/perception-tools.js

@@ -302,7 +302,10 @@ async function persistMarkdownArtifact(store, config, subdir, stem, payload) {
   }
 
   if (config?.commandCwd) {
-    const workspaceDir = path.join(config.commandCwd, "artifacts", subdir);
+    // Perception reports are runtime evidence, not task-owned source. Keep the
+    // workspace-relative copy under the standard ignored AgInTi directory so
+    // visual validation cannot dirty an otherwise completed repository.
+    const workspaceDir = path.join(config.commandCwd, ".aginti", "artifacts", subdir);
     await fs.mkdir(workspaceDir, { recursive: true });
     const workspacePath = path.join(workspaceDir, filename);
     await fs.writeFile(workspacePath, content, "utf8");

package/src/progressive-tool-selection.js

@@ -2304,7 +2304,8 @@ export function selectProgressiveTools(
   if (
     config.taskOwnedCommitPending === true &&
     config.testFailureRepairActive !== true &&
-    config.testVerificationPending !== true
+    config.testVerificationPending !== true &&
+    config.requiredProjectCommandPending !== true
   ) {
     const available = new Map(enabled.map(({ name, tool }) => [name, tool]));
     const pendingGitActions = Array.isArray(config.taskOwnedPendingGitActions)
@@ -2332,6 +2333,18 @@ export function selectProgressiveTools(
     config.testVerificationPending !== true
   ) {
     const available = new Map(enabled.map(({ name, tool }) => [name, tool]));
+    if (
+      config.requiredProjectCommandPending === true &&
+      typeof config.requiredProjectCommand === "string" &&
+      config.requiredProjectCommand.trim()
+    ) {
+      const requiredCommand = constrainRunCommand(
+        available.get("run_command"),
+        config.requiredProjectCommand,
+        "Run this exact outstanding project command before Git completion or final artifact acceptance. Preserve the generated outputs and do not substitute another status, commit, or discovery command."
+      );
+      return [requiredCommand, finish].filter(Boolean);
+    }
     const pendingGitActions = Array.isArray(config.artifactValidationPendingGitActions)
       ? config.artifactValidationPendingGitActions.map((item) => String(item || "").toLowerCase())
       : [];

package/src/scs-evidence.js

@@ -2120,6 +2120,147 @@ export function inferSuccessfulGitActionsFromCommandResult(payload = {}) {
   return [];
 }
 
+export function buildTmuxGitIntent(command = "") {
+  const text = String(command || "");
+  // `$?` is expected in the explicit tmux exit marker. Remove only that
+  // non-command expansion before parsing; all other shell expansion remains
+  // subject to the normal ambiguity guard.
+  const parseable = text.replace(/\$\?/g, "0");
+  const actions = inferGitActionsFromCommand(parseable, {
+    requireFailurePropagation: false,
+  }).filter((action) => !isObservationalGitAction(action));
+  const markers = [
+    ...text.matchAll(/={3,}([A-Z0-9][A-Z0-9_-]{3,96}(?:START|BEGIN))={3,}/g),
+  ].map((match) => String(match[0] || ""));
+  if (!actions.length || !markers.length) return null;
+  return {
+    actions: unique(actions),
+    markers: unique(markers).slice(0, 4),
+  };
+}
+
+export function inferSuccessfulGitActionsFromTmuxCapture(intent = {}, payload = {}) {
+  if (
+    !intent ||
+    !payload ||
+    payload.ok === false ||
+    payload.blocked ||
+    String(payload.toolName || "") !== "tmux_capture_pane"
+  ) {
+    return [];
+  }
+  const content = [payload.content, payload.contentPreview, payload.contentTail]
+    .map((item) => String(item || ""))
+    .filter(Boolean)
+    .join("\n");
+  const markers = Array.isArray(intent.markers)
+    ? intent.markers.map(String).filter(Boolean)
+    : [];
+  if (!content || !markers.length || !markers.some((marker) => content.includes(marker))) {
+    return [];
+  }
+  const requested = Array.isArray(intent.actions)
+    ? intent.actions.map((item) => String(item || "").toLowerCase()).filter(Boolean)
+    : [];
+  const verified = [];
+  if (
+    requested.includes("commit") &&
+    /={3,}(?:GIT_)?COMMIT_EXIT\s*[:=]\s*0={3,}/i.test(content) &&
+    /^\[[^\]\n]+\s+[0-9a-f]{7,}\]\s+\S+/mi.test(content)
+  ) {
+    verified.push("commit");
+  }
+  return verified;
+}
+
+export function reconcileTmuxGitEvidenceEvents(events = []) {
+  const source = Array.isArray(events) ? events : [];
+  const pendingStarts = new Map();
+  const activeIntents = new Map();
+  let goalRevision = 0;
+  let mutationRevision = 0;
+
+  return source.map((event) => {
+    const type = String(event?.type || "");
+    const data = event?.data && typeof event.data === "object" ? event.data : {};
+    goalRevision = Math.max(
+      goalRevision,
+      Number(
+        data.goalRevision ??
+          (type === "goal.updated" ? data.revision : 0) ??
+          0
+      ) || 0
+    );
+    mutationRevision = Math.max(
+      mutationRevision,
+      Number(data.projectMutationRevision ?? data.mutationRevision ?? 0) || 0
+    );
+
+    const toolName = String(data.toolName || "");
+    const target = String(data.target || data.args?.target || "");
+    if (type === "tool.started" && toolName === "tmux_send_keys" && target) {
+      const intent = buildTmuxGitIntent(data.args?.text || "");
+      if (intent) {
+        pendingStarts.set(target, {
+          ...intent,
+          target,
+          goalRevision,
+          mutationRevision,
+        });
+      } else {
+        pendingStarts.delete(target);
+        activeIntents.delete(target);
+      }
+      return event;
+    }
+
+    if (["tool.completed", "tool.failed"].includes(type) && toolName === "tmux_send_keys" && target) {
+      const pending = pendingStarts.get(target);
+      pendingStarts.delete(target);
+      if (type === "tool.completed" && data.ok !== false && pending) {
+        activeIntents.set(target, {
+          ...pending,
+          sentTextSha256: String(data.sentTextSha256 || ""),
+        });
+      } else {
+        activeIntents.delete(target);
+      }
+      return event;
+    }
+
+    if (type === "tool.completed" && toolName === "tmux_capture_pane" && target) {
+      const pending = activeIntents.get(target);
+      const verifiedGitActions = inferSuccessfulGitActionsFromTmuxCapture(
+        pending,
+        data
+      );
+      if (verifiedGitActions.length) {
+        activeIntents.delete(target);
+        return {
+          ...event,
+          data: {
+            ...data,
+            verifiedGitActions,
+            verifiedGitSource: "tmux_capture_pane",
+            verifiedGitGoalRevision: Math.max(
+              0,
+              Number(pending.goalRevision || 0)
+            ),
+            verifiedGitMutationRevision: Math.max(
+              0,
+              Number(pending.mutationRevision || 0)
+            ),
+            verifiedGitCommandSha256: String(
+              pending.sentTextSha256 || ""
+            ),
+          },
+        };
+      }
+    }
+    return event;
+  });
+}
+
 export function successfulGitCommitProvesFileMutation(payload = {}) {
   if (!inferSuccessfulGitActionsFromCommandResult(payload).includes("commit")) return false;
   const output = String(payload.stdout || payload.result || "");
@@ -3955,7 +4096,9 @@ function toolPayloadToEvidence(payload = {}, source = "tool") {
   if (["read_image", "generate_image"].includes(toolName) || /\b(screenshot|visible|thumbnail|preview|image)\b/.test(text)) {
     push("visual", `${toolName || "tool"} supplied visual evidence`, payload.path || payload.outputPath || args.path || "");
   }
-  const gitActions = inferSuccessfulGitActionsFromCommandResult(payload);
+  const gitActions = Array.isArray(payload.verifiedGitActions)
+    ? payload.verifiedGitActions
+    : inferSuccessfulGitActionsFromCommandResult(payload);
   if (gitActions.length) {
     push(
       "git",
@@ -3964,8 +4107,18 @@ function toolPayloadToEvidence(payload = {}, source = "tool") {
       {
         gitAction: gitActions.at(-1),
         gitActions,
-        goalRevision: Math.max(0, Number(payload.goalRevision || 0)),
-        mutationRevision: Math.max(0, Number(payload.projectMutationRevision || 0)),
+        goalRevision: Math.max(
+          0,
+          Number(payload.verifiedGitGoalRevision ?? payload.goalRevision ?? 0)
+        ),
+        mutationRevision: Math.max(
+          0,
+          Number(
+            payload.verifiedGitMutationRevision ??
+              payload.projectMutationRevision ??
+              0
+          )
+        ),
       }
     );
   }
@@ -4038,7 +4191,9 @@ function messageToEvidence(message = {}) {
 }
 
 export function buildScsEvidenceLedger({ state = {}, context = {} } = {}) {
-  const events = Array.isArray(context.events) ? context.events : [];
+  const events = reconcileTmuxGitEvidenceEvents(
+    Array.isArray(context.events) ? context.events : []
+  );
   const messages = Array.isArray(state.messages) ? state.messages : [];
   const eventEvidence = events.flatMap(eventToEvidence);
   // Completed tools are mirrored into both the append-only event stream and