@lazyingart/agintiflow 0.20.181 → 0.20.182

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

@@ -138,6 +138,22 @@ aginti "start a tmux session named demo, run ls in it, keep it open, and tell me
 
 The agent should use `tmux_start_session`, `tmux_send_keys`, and `tmux_capture_pane`, not Docker `run_command`. In Docker sandbox mode, tmux commands must stay inside the project. In host mode, tmux command text is still governed by host shell policy; if a tmux command is blocked, present the suggested rerun path instead of trying tmux as a workaround. For trusted whole-host tmux work, use the host recipe above.
 
+Long download or long command:
+
+```bash
+aginti "download this large zip with wget -c, verify the final byte count, and do not burn model steps polling it"
+```
+
+The agent should use `start_long_job` once instead of repeatedly calling `wait`, `run_command`, or `tmux_capture_pane`. The tool creates `.aginti/long-jobs/<job-id>/status.json`, stdout/stderr logs, a supervisor log, and an optional status card. For resumable downloads, the agent should first determine `Content-Length` when practical, then call `start_long_job` with:
+
+- `command`: a resumable transfer such as `wget -c URL -O file.zip`
+- `expectedOutputPath`: the downloaded file
+- `expectedSizeBytes`: the expected byte count
+- `verifyCommand`: a deterministic check such as `unzip -t file.zip` or `sha256sum -c`
+- `restartOnFailure`: `true` when the transfer command is safe to resume
+
+After `start_long_job` succeeds, the model loop should finish with the job id and status path. Later status checks should use `long_job_status` or direct shell inspection of the status JSON. This keeps multi-hour I/O under a shell supervisor instead of consuming model tokens and step budget.
+
 ## Future Persistent Container Mode
 
 A useful next runtime mode is a service container:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lazyingart/agintiflow",
-  "version": "0.20.181",
+  "version": "0.20.182",
   "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",
@@ -63,6 +63,7 @@
     "scripts/smoke-capabilities.js",
     "scripts/smoke-auto-update.js",
     "scripts/smoke-inbox.js",
+    "scripts/smoke-long-jobs.js",
     "scripts/smoke-mcp.js",
     "scripts/fixtures/mcp-stdio-smoke-server.mjs",
     "scripts/smoke-model-roles.js",
@@ -106,6 +107,7 @@
     "smoke:skillmesh": "node scripts/smoke-skillmesh.js",
     "smoke:toolchain-docker": "node scripts/smoke-toolchain-docker.js",
     "smoke:inbox": "node scripts/smoke-inbox.js",
+    "smoke:long-jobs": "node scripts/smoke-long-jobs.js",
     "smoke:mcp": "node scripts/smoke-mcp.js",
     "smoke:model-roles": "node scripts/smoke-model-roles.js",
     "smoke:platform": "node scripts/smoke-platform.js",
@@ -125,7 +127,7 @@
     "storage:migrate": "node bin/aginti-cli.js storage migrate",
     "publish:env": "node scripts/npm-publish-from-env.js publish --access public",
     "publish:env:whoami": "node scripts/npm-publish-from-env.js whoami",
-    "test": "npm run check && npm run smoke:runtime-compat && npm run smoke:autoupdate && npm run smoke:web-api && npm run smoke:web-ui && npm run smoke:web-autostart && npm run smoke:webapp-command && npm run smoke:web-port-fallback && npm run smoke:docker-command && npm run smoke:coding-tools && npm run smoke:dynamic-step-budget && npm run smoke:aaps-adapter && npm run smoke:auxiliary-tools && npm run smoke:perception-research && npm run smoke:auth && npm run smoke:canvas-artifacts && npm run smoke:capabilities && npm run smoke:mcp && npm run smoke:model-roles && npm run smoke:platform && npm run smoke:permission-modes && npm run smoke:skills && npm run smoke:skillmesh && npm run smoke:tmux-tools && npm run smoke:cli-chat && npm run smoke:inbox",
+    "test": "npm run check && npm run smoke:runtime-compat && npm run smoke:autoupdate && npm run smoke:web-api && npm run smoke:web-ui && npm run smoke:web-autostart && npm run smoke:webapp-command && npm run smoke:web-port-fallback && npm run smoke:docker-command && npm run smoke:coding-tools && npm run smoke:dynamic-step-budget && npm run smoke:aaps-adapter && npm run smoke:auxiliary-tools && npm run smoke:perception-research && npm run smoke:auth && npm run smoke:canvas-artifacts && npm run smoke:capabilities && npm run smoke:mcp && npm run smoke:model-roles && npm run smoke:platform && npm run smoke:permission-modes && npm run smoke:skills && npm run smoke:skillmesh && npm run smoke:tmux-tools && npm run smoke:long-jobs && npm run smoke:cli-chat && npm run smoke:inbox",
     "pack:dry-run": "npm pack --dry-run",
     "smoke:capabilities": "node scripts/smoke-capabilities.js"
   },

package/scripts/smoke-long-jobs.js

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { checkToolUse } from "../src/guardrails.js";
+import { longJobStatus, startLongJob } from "../src/long-job-tools.js";
+import { tmuxAvailable } from "../src/tmux-tools.js";
+
+const workspace = await fs.mkdtemp(path.join(os.tmpdir(), "agintiflow-long-job-"));
+const config = {
+  allowShellTool: true,
+  allowDestructive: true,
+  allowPasswords: true,
+  commandCwd: workspace,
+  sandboxMode: "host",
+  useDockerSandbox: false,
+};
+const dockerConfig = {
+  ...config,
+  allowDestructive: false,
+  allowPasswords: false,
+  useDockerSandbox: true,
+  sandboxMode: "docker-workspace",
+  packageInstallPolicy: "allow",
+};
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+try {
+  if (!(await tmuxAvailable())) {
+    console.log(JSON.stringify({ ok: true, skipped: true, reason: "tmux is not installed" }, null, 2));
+    process.exit(0);
+  }
+
+  const noShell = checkToolUse({
+    toolName: "start_long_job",
+    args: { command: "printf ok > out.txt" },
+    config: { ...config, allowShellTool: false },
+  });
+  assert.equal(noShell.allowed, false, "start_long_job should require shell capability");
+
+  const outsidePath = path.join(os.tmpdir(), "aginti-long-job-outside.txt");
+  const outsideGuard = checkToolUse({
+    toolName: "start_long_job",
+    args: { name: "outside", command: `cat ${outsidePath}` },
+    config: dockerConfig,
+  });
+  assert.equal(outsideGuard.allowed, false, "Docker-mode long jobs should block outside host absolute paths");
+
+  const start = await startLongJob(
+    {
+      name: "smoke-download-style",
+      command: "printf 'abc123' > download.bin",
+      expectedOutputPath: "download.bin",
+      expectedSizeBytes: 6,
+      verifyCommand: "grep -q abc download.bin",
+      pollIntervalSeconds: 5,
+      note: "Smoke test for durable long command handoff.",
+    },
+    config
+  );
+  assert.equal(start.ok, true, start.error || start.reason);
+  assert.equal(start.background, true, "long job should return as a background handoff");
+  assert.match(start.statusPath, /^\.aginti\/long-jobs\//, "status path should be project-local");
+
+  let status = null;
+  for (let i = 0; i < 30; i += 1) {
+    await sleep(250);
+    status = await longJobStatus({ jobId: start.jobId }, config);
+    assert.equal(status.ok, true, status.reason);
+    if (["completed", "failed"].includes(status.state)) break;
+  }
+  assert.equal(status?.state, "completed", `long job did not complete: ${JSON.stringify(status)}`);
+  assert.equal(status.outputBytes, 6, "expected-size progress was not recorded");
+  assert.equal(status.verifyExitCode, 0, "verify command did not pass");
+
+  const output = await fs.readFile(path.join(workspace, "download.bin"), "utf8");
+  assert.equal(output, "abc123", "job output content mismatch");
+  await fs.access(path.join(workspace, start.statusPath));
+  await fs.access(path.join(workspace, start.stdoutPath));
+  await fs.access(path.join(workspace, start.stderrPath));
+  await fs.access(path.join(workspace, start.supervisorLogPath));
+
+  console.log(
+    JSON.stringify(
+      {
+        ok: true,
+        workspace,
+        jobId: start.jobId,
+        statusPath: start.statusPath,
+        state: status.state,
+        outputBytes: status.outputBytes,
+        verifyExitCode: status.verifyExitCode,
+      },
+      null,
+      2
+    )
+  );
+} finally {
+  await fs.rm(workspace, { recursive: true, force: true }).catch(() => {});
+}

package/src/agent-runner.js

@@ -41,6 +41,7 @@ import { browserStateReconciliationGuidance } from "./browser-automation-guidanc
 import { summarizeMcpConfig } from "./mcp/config.js";
 import { isMcpBridgeTool } from "./mcp/policy.js";
 import { executeMcpBridgeTool } from "./mcp/tool-bridge.js";
+import { longJobStatus, startLongJob } from "./long-job-tools.js";
 import {
   buildSupervisorInstruction,
   createScsPlan,
@@ -612,7 +613,7 @@ async function createInitialState(config, sessionId) {
           "If an operation fails but a directory, artifact, or file already exists, treat it as pre-existing unless you have evidence this run created or updated it. Verify expected outputs before claiming success.",
           "For validation/evidence commands, remember that grep exits 1 on zero matches. If zero matches is the expected clean result, use `grep -c PATTERN file || true`, split evidence checks into independent commands, or use awk/python so a clean zero count does not stop an `&&` chain.",
           config.allowShellTool
-            ? "Host tmux tools are available for long-running terminals: list sessions, capture panes, send safe keys/text, and start detached sessions. Prefer these tools for monitoring long installs/tests/dev servers without blocking; capture before sending input and never send secrets or sudo passwords. Do not start or install tmux inside Docker run_command containers because those containers are short-lived. In Docker sandbox mode, tmux start/send commands must stay workspace-write-bound; prefer run_command for read-only host absolute path inspection through read-only mounts, and ask for --sandbox-mode host for trusted whole-host write/system work." +
+            ? "For downloads, long I/O, long tests/builds, model jobs, or any command with an ETA of minutes or hours, prefer start_long_job over wait loops. start_long_job creates a durable tmux-backed status ledger, stdout/stderr logs, optional expected-size verification, and returns immediately; after it starts, report the job id/status path and finish instead of polling with model steps. Host tmux tools are also available for interactive terminals: list sessions, capture panes, send safe keys/text, and start detached sessions. Capture before sending input and never send secrets or sudo passwords. Do not start or install tmux inside Docker run_command containers because those containers are short-lived. In Docker sandbox mode, tmux and long-job commands must stay workspace-write-bound; prefer run_command for read-only host absolute path inspection through read-only mounts, and ask for --sandbox-mode host for trusted whole-host write/system work." +
               " For one-shot tmux commands, redirect stdout/stderr and exit status to a durable workspace log or keep the pane alive for capture; if capture fails because the session ended, do not infer output or exit status."
             : "",
           config.allowShellTool && config.useDockerSandbox
@@ -653,7 +654,7 @@ async function createInitialState(config, sessionId) {
           browserStateReconciliationGuidance(),
           "Use the canvas tunnel for outputs the user would likely want to inspect visually, such as figures, PDFs, screenshots, images, important markdown, or generated files. When no save path is specified, choose a descriptive non-conflicting workspace path near the working directory and keep it there.",
           "For environment or system-maintenance work, use the configured sandbox and package policy; Docker workspace mode is the preferred place for installs and toolchain setup.",
-          "For long-running work, create a durable checkpoint or artifact at each completed phase, then continue with the next concrete phase until the requested outcome is actually complete or blocked by a real dependency.",
+          "For long-running work, create durable checkpoints. If a single command will run for minutes or hours, hand it to start_long_job with verification hooks and finish with the status path instead of keeping the model loop alive.",
           "If the user asks to open a generated local website or file, use open_workspace_file for a file or preview_workspace for a static site. Do not keep retrying the same localhost URL when a preview fails.",
           "Docker language/toolchain installs should prefer /aginti-env or project files so they persist across runs; apt/apk changes are ephemeral unless the image is rebuilt.",
           "If the run is close to the max-step limit, finish with the best complete artifact and honest limitations instead of starting a new approach.",
@@ -1402,6 +1403,16 @@ function sanitizeToolArgs(toolName, args) {
         : safeArgs.referenceImages,
     };
   }
+  if (toolName === "start_long_job") {
+    return {
+      ...safeArgs,
+      command: typeof args.command === "string" ? `[${Buffer.byteLength(args.command, "utf8")} bytes sha256=${hashForLog(args.command)}]` : safeArgs.command,
+      verifyCommand:
+        typeof args.verifyCommand === "string"
+          ? `[${Buffer.byteLength(args.verifyCommand, "utf8")} bytes sha256=${hashForLog(args.verifyCommand)}]`
+          : safeArgs.verifyCommand,
+    };
+  }
   return safeArgs;
 }
 
@@ -1589,7 +1600,7 @@ async function captureSyntheticSnapshot(store, step, config) {
           : `Shell tool available in: ${config.commandCwd} on ${platformLabel(platform)}. Use OS-compatible commands; prefer WSL/Docker for bash-heavy workflows on Windows. If a broad host command is blocked, split it into narrow allowed probes or existing helper scripts before treating the task as blocked.`
         : "Shell tool disabled.",
       config.allowShellTool
-        ? "Host tmux tools available: tmux_list_sessions, tmux_capture_pane, tmux_send_keys, tmux_start_session. Use them for long-running jobs and agent terminals; capture before sending input. Tmux captures include old scrollback, so after a restart require a fresh run marker, heartbeat, PID, or log/status timestamp before treating capture text as current evidence. Docker run_command containers are ephemeral, so tmux there will not persist. In Docker sandbox mode, tmux start/send commands must stay workspace-write-bound; when sending text into a shell pane, tmux follows the same Docker workspace command policy as run_command and is not a bypass for package installs, destructive git history rewrites, or broad shell text. Prefer run_command for read-only host absolute path inspection through read-only mounts. Use --sandbox-mode host for trusted whole-host write/system work. In host mode, tmux startup/send command text follows the same host shell policy as run_command; if a broad host command is blocked, present the approval/rerun path instead of trying tmux as a workaround. For one-shot tmux commands, redirect output and exit status to a durable workspace log or keep the pane alive for capture; if capture fails because the session ended, do not infer output or exit status."
+        ? "Long-job tool available: start_long_job for downloads, long I/O, long tests/builds, model jobs, and any command with an ETA of minutes or hours. It starts a durable tmux-backed supervisor, writes status/log files, supports expected-size and verifyCommand checks, and returns immediately; do not keep the model loop alive to poll it. Use long_job_status later for explicit status requests. Host tmux tools are also available: tmux_list_sessions, tmux_capture_pane, tmux_send_keys, tmux_start_session. Use tmux for interactive terminals; capture before sending input. Tmux captures include old scrollback, so after a restart require a fresh run marker, heartbeat, PID, or log/status timestamp before treating capture text as current evidence. Docker run_command containers are ephemeral, so tmux there will not persist. In Docker sandbox mode, tmux start/send commands must stay workspace-write-bound; when sending text into a shell pane, tmux follows the same Docker workspace command policy as run_command and is not a bypass for package installs, destructive git history rewrites, or broad shell text. Prefer run_command for read-only host absolute path inspection through read-only mounts. Use --sandbox-mode host for trusted whole-host write/system work. In host mode, tmux startup/send command text follows the same host shell policy as run_command; if a broad host command is blocked, present the approval/rerun path instead of trying tmux as a workaround. For one-shot tmux commands, redirect output and exit status to a durable workspace log or keep the pane alive for capture; if capture fails because the session ended, do not infer output or exit status."
         : "",
       config.allowFileTools
         ? `Workspace file tools available in: ${config.commandCwd}. Use inspect_project first for large or unfamiliar codebases, then search/read exact files before editing. Use workspace-relative paths. Use apply_patch for code edits; it supports exact single-file replacement and multi-file Codex-style/unified patches. For new standalone generated content, pick a descriptive non-conflicting filename and avoid overwriting unless explicitly requested.`
@@ -2017,6 +2028,48 @@ async function executeTool(browserState, toolCall, snapshot, config, store, obse
         observers.event(result.ok ? "tool.completed" : "tool.failed", eventResult);
         return result;
       }
+      case "start_long_job": {
+        const result = await startLongJob(args, config);
+        const eventResult = sanitizeToolResult(result);
+        await store.appendEvent(result.ok ? "tool.completed" : "tool.failed", eventResult);
+        observers.event(result.ok ? "tool.completed" : "tool.failed", eventResult);
+        if (result.ok) {
+          await store.appendEvent("long_job.started", eventResult);
+          observers.event("long_job.started", eventResult);
+          if (result.statusMarkdownPath) {
+            const normalized = normalizeCanvasPayload(
+              {
+                title: `Long job: ${result.name || result.jobId}`,
+                kind: "markdown",
+                path: result.statusMarkdownPath,
+                note: `Background job ${result.jobId} is running; status: ${result.statusPath}`,
+                selected: false,
+              },
+              config
+            );
+            if (normalized.ok) {
+              const persisted = await persistCanvasPayloadFile(normalized.payload, { config, store });
+              if (persisted.ok) {
+                const canvasItem = {
+                  ...persisted.payload,
+                  toolName: "start_long_job",
+                  commandCwd: config.commandCwd,
+                };
+                await store.appendEvent("canvas.item", canvasItem);
+                observers.event("canvas.item", canvasItem);
+              }
+            }
+          }
+        }
+        return result;
+      }
+      case "long_job_status": {
+        const result = await longJobStatus(args, config);
+        const eventResult = sanitizeToolResult(result);
+        await store.appendEvent(result.ok ? "tool.completed" : "tool.failed", eventResult);
+        observers.event(result.ok ? "tool.completed" : "tool.failed", eventResult);
+        return result;
+      }
       case "delegate_agent": {
         const wrapperResult = await runAgentWrapper(
           {

package/src/guardrails.js

@@ -2,6 +2,7 @@ import { evaluateCommandPolicy } from "./command-policy.js";
 import { checkWorkspaceToolUse, WORKSPACE_TOOL_NAMES } from "./workspace-tools.js";
 import { normalizeWrapperName } from "./tool-wrappers.js";
 import { checkTmuxToolUse, TMUX_TOOL_NAMES } from "./tmux-tools.js";
+import { checkLongJobToolUse, LONG_JOB_TOOL_NAMES } from "./long-job-tools.js";
 import { checkMcpToolUse, isMcpBridgeTool } from "./mcp/policy.js";
 
 const DESTRUCTIVE_KEYWORDS = [
@@ -88,6 +89,10 @@ export function checkToolUse({ toolName, args, snapshot, config }) {
     return checkTmuxToolUse(toolName, args, config);
   }
 
+  if (LONG_JOB_TOOL_NAMES.includes(toolName)) {
+    return checkLongJobToolUse(toolName, args, config);
+  }
+
   if (toolName === "open_url") {
     if (!/^https?:\/\//.test(String(args.url || ""))) {
       return { allowed: false, reason: "Only http and https URLs are allowed." };

package/src/long-job-tools.js

@@ -0,0 +1,581 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import fsp from "node:fs/promises";
+import path from "node:path";
+import { execFile as execFileCallback } from "node:child_process";
+import { promisify } from "node:util";
+import { evaluateCommandPolicy } from "./command-policy.js";
+import { redactSensitiveText } from "./redaction.js";
+
+const execFile = promisify(execFileCallback);
+const JOB_NAME_PATTERN = /^[A-Za-z0-9_.+-]{1,80}$/;
+const JOB_ID_PATTERN = /^[A-Za-z0-9_.+-]{8,140}$/;
+const SECRET_PATTERN = /(api[_-]?key|auth[_-]?token|npm[_-]?token|_authToken|password|passwd|secret|bearer\s+[A-Za-z0-9._-]+)/i;
+const ABSOLUTE_PATH_PATTERN = /(^|[\s"'`=(:])((?:\/[A-Za-z0-9._@%+~:-]+)+\/?)/g;
+const ALWAYS_ALLOWED_ABSOLUTE_PATHS = new Set(["/dev/null"]);
+const MAX_COMMAND_BYTES = 12000;
+const DEFAULT_POLL_INTERVAL_SECONDS = 60;
+
+export const LONG_JOB_TOOL_NAMES = ["start_long_job", "long_job_status"];
+
+function safeEnv() {
+  return {
+    PATH: process.env.PATH || "/usr/local/bin:/usr/bin:/bin",
+    HOME: process.env.HOME || "/tmp",
+    TERM: process.env.TERM || "xterm-256color",
+    SHELL: process.env.SHELL || "/bin/bash",
+  };
+}
+
+function clampInteger(value, fallback, min, max) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) return fallback;
+  return Math.min(Math.max(Math.trunc(parsed), min), max);
+}
+
+function isInsideDirectory(root, candidate) {
+  const relative = path.relative(root, candidate);
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+function workspaceRoot(config = {}) {
+  return path.resolve(config.commandCwd || process.cwd());
+}
+
+function isTrustedWholeHost(config = {}) {
+  return config.sandboxMode === "host" && Boolean(config.allowDestructive);
+}
+
+function normalizeJobName(raw = "") {
+  const value = String(raw || "aginti-long-job")
+    .trim()
+    .replace(/[^A-Za-z0-9_.+-]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 48);
+  return value || "aginti-long-job";
+}
+
+function makeJobId(name = "") {
+  const stamp = new Date().toISOString().replace(/[-:.TZ]/g, "").slice(0, 14);
+  const suffix = crypto.randomBytes(4).toString("hex");
+  return `${normalizeJobName(name)}-${stamp}-${suffix}`;
+}
+
+function tmuxSessionName(jobId = "") {
+  const base = `aginti-job-${jobId}`.replace(/[^A-Za-z0-9_.+-]+/g, "-");
+  if (base.length <= 80) return base;
+  const hash = crypto.createHash("sha1").update(base).digest("hex").slice(0, 10);
+  return `${base.slice(0, 68)}-${hash}`;
+}
+
+function uniqueAbsolutePaths(text = "") {
+  const paths = new Set();
+  for (const match of String(text || "").matchAll(ABSOLUTE_PATH_PATTERN)) {
+    const candidate = match[2];
+    if (!candidate || candidate.startsWith("//")) continue;
+    paths.add(candidate.replace(/[),.;]+$/g, ""));
+  }
+  return [...paths].filter(Boolean);
+}
+
+function checkWorkspaceBoundText(text = "", config = {}, label = "long job command") {
+  if (!config.useDockerSandbox && isTrustedWholeHost(config)) return { ok: true };
+  const root = workspaceRoot(config);
+  for (const candidate of uniqueAbsolutePaths(text)) {
+    if (ALWAYS_ALLOWED_ABSOLUTE_PATHS.has(candidate)) continue;
+    const resolved = path.resolve(candidate);
+    if (!isInsideDirectory(root, resolved)) {
+      return {
+        ok: false,
+        reason: `${label} references an absolute host path outside the configured workspace: ${candidate}. Use a workspace-relative path or trusted host mode for whole-host work.`,
+      };
+    }
+  }
+  return { ok: true };
+}
+
+function resolveCwd(config = {}, rawCwd = ".") {
+  const root = workspaceRoot(config);
+  const requested = String(rawCwd || ".").trim() || ".";
+  const cwd = path.isAbsolute(requested) ? path.resolve(requested) : path.resolve(root, requested);
+  if (!isTrustedWholeHost(config) && !isInsideDirectory(root, cwd)) {
+    return { ok: false, reason: "Long-job cwd must stay inside the configured workspace unless trusted host mode is enabled." };
+  }
+  return { ok: true, cwd, root };
+}
+
+function resolveExpectedOutput(config = {}, cwd = "", rawPath = "") {
+  const value = String(rawPath || "").trim();
+  if (!value) return { ok: true, outputPath: "", outputPathAbs: "" };
+  const root = workspaceRoot(config);
+  const absolute = path.isAbsolute(value) ? path.resolve(value) : path.resolve(cwd || root, value);
+  if (!isTrustedWholeHost(config) && !isInsideDirectory(root, absolute)) {
+    return {
+      ok: false,
+      reason: "Expected output path must stay inside the configured workspace unless trusted host mode is enabled.",
+    };
+  }
+  return {
+    ok: true,
+    outputPath: isInsideDirectory(root, absolute) ? path.relative(root, absolute) || "." : absolute,
+    outputPathAbs: absolute,
+  };
+}
+
+async function runTmux(args, options = {}) {
+  try {
+    const result = await execFile("tmux", args, {
+      timeout: options.timeout ?? 12000,
+      maxBuffer: options.maxBuffer ?? 128 * 1024,
+      env: safeEnv(),
+      signal: options.signal,
+    });
+    return {
+      ok: true,
+      stdout: redactSensitiveText(result.stdout || ""),
+      stderr: redactSensitiveText(result.stderr || ""),
+    };
+  } catch (error) {
+    const message = redactSensitiveText(error instanceof Error ? error.message : String(error));
+    return {
+      ok: false,
+      stdout: redactSensitiveText(String(error?.stdout || "")),
+      stderr: redactSensitiveText(String(error?.stderr || message)),
+      error: message,
+      exitCode: Number.isInteger(error?.code) ? error.code : 1,
+    };
+  }
+}
+
+function shellQuote(value = "") {
+  return `'${String(value).replace(/'/g, `'\\''`)}'`;
+}
+
+function supervisorSource() {
+  return String.raw`import fs from "node:fs";
+import fsp from "node:fs/promises";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const jobDir = path.dirname(fileURLToPath(import.meta.url));
+const jobPath = path.join(jobDir, "job.json");
+const statusPath = path.join(jobDir, "status.json");
+const eventsPath = path.join(jobDir, "events.jsonl");
+const stdoutPath = path.join(jobDir, "stdout.log");
+const stderrPath = path.join(jobDir, "stderr.log");
+const verifyStdoutPath = path.join(jobDir, "verify_stdout.log");
+const verifyStderrPath = path.join(jobDir, "verify_stderr.log");
+const supervisorLogPath = path.join(jobDir, "supervisor.log");
+const job = JSON.parse(await fsp.readFile(jobPath, "utf8"));
+let status = {
+  jobId: job.jobId,
+  name: job.name,
+  state: "starting",
+  createdAt: job.createdAt,
+  updatedAt: new Date().toISOString(),
+  cwd: job.cwd,
+  session: job.session,
+  command: job.displayCommand || job.command,
+  expectedOutputPath: job.expectedOutputPath || "",
+  expectedSizeBytes: job.expectedSizeBytes || 0,
+  restartOnFailure: Boolean(job.restartOnFailure),
+  pollIntervalSeconds: job.pollIntervalSeconds,
+  attempt: 0,
+  pid: null,
+  exitCode: null,
+  verifyExitCode: null,
+  outputBytes: 0,
+  percent: null,
+  reason: "",
+};
+
+function now() {
+  return new Date().toISOString();
+}
+
+async function appendLog(message) {
+  await fsp.appendFile(supervisorLogPath, now() + " " + message + "\n");
+}
+
+async function appendEvent(type, data = {}) {
+  await fsp.appendFile(eventsPath, JSON.stringify({ type, at: now(), ...data }) + "\n");
+}
+
+function outputStats() {
+  if (!job.expectedOutputPathAbs) return { exists: false, bytes: 0, percent: null };
+  try {
+    const stat = fs.statSync(job.expectedOutputPathAbs);
+    const bytes = stat.size;
+    const expected = Number(job.expectedSizeBytes || 0);
+    return {
+      exists: true,
+      bytes,
+      percent: expected > 0 ? Math.min(100, (bytes / expected) * 100) : null,
+    };
+  } catch {
+    return { exists: false, bytes: 0, percent: null };
+  }
+}
+
+async function writeStatus(patch = {}) {
+  const stats = outputStats();
+  status = {
+    ...status,
+    ...patch,
+    outputExists: stats.exists,
+    outputBytes: stats.bytes,
+    percent: stats.percent,
+    updatedAt: now(),
+  };
+  const tmp = statusPath + ".tmp";
+  await fsp.writeFile(tmp, JSON.stringify(status, null, 2));
+  await fsp.rename(tmp, statusPath);
+}
+
+function outputComplete() {
+  if (!job.expectedOutputPathAbs) return true;
+  const stats = outputStats();
+  if (!stats.exists) return false;
+  const expected = Number(job.expectedSizeBytes || 0);
+  return expected > 0 ? stats.bytes === expected : stats.bytes > 0;
+}
+
+function deadlineExceeded() {
+  return Number(job.timeoutSeconds || 0) > 0 && Date.now() >= job.startedEpochMs + Number(job.timeoutSeconds) * 1000;
+}
+
+async function delay(ms) {
+  await new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function runShell(command, { stdout, stderr, label }) {
+  await appendEvent(label + ".started", { command });
+  const shell = process.env.SHELL || "/bin/bash";
+  return await new Promise((resolve) => {
+    let timedOut = false;
+    const child = spawn(shell, ["-lc", command], {
+      cwd: job.cwd,
+      env: { ...process.env, AGINTI_LONG_JOB_ID: job.jobId, AGINTI_LONG_JOB_DIR: jobDir },
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    status.pid = child.pid || null;
+    writeStatus({ state: label === "verify" ? "verifying" : "running", pid: status.pid }).catch(() => {});
+    const out = fs.createWriteStream(stdout, { flags: "a" });
+    const err = fs.createWriteStream(stderr, { flags: "a" });
+    child.stdout.on("data", (chunk) => out.write(chunk));
+    child.stderr.on("data", (chunk) => err.write(chunk));
+    const timeoutMs = Number(job.timeoutSeconds || 0) > 0 ? Math.max(1, job.startedEpochMs + Number(job.timeoutSeconds) * 1000 - Date.now()) : 0;
+    const timer = timeoutMs
+      ? setTimeout(() => {
+          timedOut = true;
+          try {
+            child.kill("SIGTERM");
+          } catch {}
+          setTimeout(() => {
+            try {
+              child.kill("SIGKILL");
+            } catch {}
+          }, 5000).unref?.();
+        }, timeoutMs)
+      : null;
+    child.on("close", async (code, signal) => {
+      if (timer) clearTimeout(timer);
+      out.end();
+      err.end();
+      await appendEvent(label + ".finished", { exitCode: code, signal: signal || "", timedOut });
+      resolve({ exitCode: Number.isInteger(code) ? code : 1, signal: signal || "", timedOut });
+    });
+    child.on("error", async (error) => {
+      if (timer) clearTimeout(timer);
+      out.end();
+      err.end();
+      await appendEvent(label + ".failed", { error: error.message || String(error) });
+      resolve({ exitCode: 1, signal: "", timedOut, error: error.message || String(error) });
+    });
+  });
+}
+
+await fsp.mkdir(jobDir, { recursive: true });
+await appendLog("long job supervisor starting: " + job.jobId);
+await appendEvent("job.started", { jobId: job.jobId, session: job.session });
+job.startedEpochMs = Date.now();
+await writeStatus({ state: "starting", startedAt: now() });
+
+const interval = setInterval(() => {
+  if (status.state === "running" || status.state === "verifying" || status.state === "restarting") {
+    writeStatus({ heartbeatAt: now() }).catch(() => {});
+  }
+}, Math.max(1, Number(job.pollIntervalSeconds || 60)) * 1000);
+interval.unref?.();
+
+let attempt = 0;
+while (true) {
+  attempt += 1;
+  await writeStatus({ state: "running", attempt, pid: null, exitCode: null, reason: "" });
+  await appendLog("attempt " + attempt + " started");
+  const result = await runShell(job.command, { stdout: stdoutPath, stderr: stderrPath, label: "command" });
+  await writeStatus({ exitCode: result.exitCode, pid: null });
+
+  const complete = result.exitCode === 0 && outputComplete();
+  if (complete) {
+    if (job.verifyCommand) {
+      const verify = await runShell(job.verifyCommand, { stdout: verifyStdoutPath, stderr: verifyStderrPath, label: "verify" });
+      await writeStatus({ verifyExitCode: verify.exitCode, pid: null });
+      if (verify.exitCode === 0) {
+        await writeStatus({ state: "completed", completedAt: now(), reason: "command and verification succeeded" });
+        await appendEvent("job.completed", { verifyExitCode: verify.exitCode });
+        await appendLog("job completed");
+        process.exit(0);
+      }
+      await writeStatus({ state: "failed", failedAt: now(), reason: "verify command exited " + verify.exitCode });
+      await appendEvent("job.failed", { reason: "verify command exited " + verify.exitCode });
+      await appendLog("job failed: verify exit " + verify.exitCode);
+      process.exit(1);
+    }
+    await writeStatus({ state: "completed", completedAt: now(), reason: "command succeeded" });
+    await appendEvent("job.completed", { exitCode: result.exitCode });
+    await appendLog("job completed");
+    process.exit(0);
+  }
+
+  const reason = result.exitCode !== 0 ? "command exited " + result.exitCode : "expected output is missing or incomplete";
+  if (job.restartOnFailure && !deadlineExceeded()) {
+    await writeStatus({ state: "restarting", reason, restartedAt: now() });
+    await appendEvent("job.restarting", { attempt, reason });
+    await appendLog("restarting after attempt " + attempt + ": " + reason);
+    await delay(Math.max(1, Number(job.pollIntervalSeconds || 60)) * 1000);
+    continue;
+  }
+
+  await writeStatus({ state: "failed", failedAt: now(), reason });
+  await appendEvent("job.failed", { attempt, reason });
+  await appendLog("job failed: " + reason);
+  process.exit(1);
+}`;
+}
+
+function buildStatusMarkdown(job = {}) {
+  return [
+    `# Long Job: ${job.name}`,
+    "",
+    `- Job ID: \`${job.jobId}\``,
+    `- State file: \`${job.statusPath}\``,
+    `- Session: \`${job.session}\``,
+    `- CWD: \`${job.cwd}\``,
+    job.expectedOutputPath ? `- Expected output: \`${job.expectedOutputPath}\`` : "",
+    job.expectedSizeBytes ? `- Expected size: ${job.expectedSizeBytes} bytes` : "",
+    `- Stdout log: \`${job.stdoutPath}\``,
+    `- Stderr log: \`${job.stderrPath}\``,
+    `- Supervisor log: \`${job.supervisorLogPath}\``,
+    "",
+    "This is a durable background job. The model loop should not poll it. Use `long_job_status` or read the status JSON later.",
+  ]
+    .filter(Boolean)
+    .join("\n");
+}
+
+export function checkLongJobToolUse(toolName, args = {}, config = {}) {
+  if (!config.allowShellTool) {
+    return { allowed: false, reason: "Long jobs require the shell tool to be enabled.", category: "long-job" };
+  }
+  if (toolName === "long_job_status") {
+    const jobId = String(args.jobId || "").trim();
+    if (!jobId) return { allowed: false, reason: "long_job_status requires jobId.", category: "long-job" };
+    if (!JOB_ID_PATTERN.test(jobId)) return { allowed: false, reason: "Invalid long job id.", category: "long-job" };
+    return { allowed: true, category: "long-job" };
+  }
+  if (toolName !== "start_long_job") return { allowed: true, category: "long-job" };
+
+  const name = normalizeJobName(args.name || "aginti-long-job");
+  if (!JOB_NAME_PATTERN.test(name)) {
+    return { allowed: false, reason: "Long job name must use letters, numbers, dot, underscore, plus, or dash.", category: "long-job" };
+  }
+  const command = String(args.command || "").trim();
+  if (!command) return { allowed: false, reason: "start_long_job requires command.", category: "long-job" };
+  if (Buffer.byteLength(command, "utf8") > MAX_COMMAND_BYTES) {
+    return { allowed: false, reason: "Long job command is too large.", category: "long-job" };
+  }
+  if (SECRET_PATTERN.test(command)) {
+    return { allowed: false, reason: "Long job command appears to contain a secret.", category: "long-job" };
+  }
+  const cwd = resolveCwd(config, args.cwd || ".");
+  if (!cwd.ok) return { allowed: false, reason: cwd.reason, category: "long-job" };
+  const workspaceBound = checkWorkspaceBoundText(command, config, "Long job command");
+  if (!workspaceBound.ok) return { allowed: false, reason: workspaceBound.reason, category: "long-job" };
+  const policy = evaluateCommandPolicy(command, config);
+  if (!policy.allowed) {
+    return {
+      allowed: false,
+      reason: `Long job command is blocked by shell policy: ${policy.reason}`,
+      category: policy.category || "long-job",
+      needsApproval: policy.needsApproval,
+    };
+  }
+  const verifyCommand = String(args.verifyCommand || "").trim();
+  if (verifyCommand) {
+    if (SECRET_PATTERN.test(verifyCommand)) {
+      return { allowed: false, reason: "Long job verify command appears to contain a secret.", category: "long-job" };
+    }
+    const verifyWorkspaceBound = checkWorkspaceBoundText(verifyCommand, config, "Long job verify command");
+    if (!verifyWorkspaceBound.ok) return { allowed: false, reason: verifyWorkspaceBound.reason, category: "long-job" };
+    const verifyPolicy = evaluateCommandPolicy(verifyCommand, config);
+    if (!verifyPolicy.allowed) {
+      return {
+        allowed: false,
+        reason: `Long job verify command is blocked by shell policy: ${verifyPolicy.reason}`,
+        category: verifyPolicy.category || "long-job",
+        needsApproval: verifyPolicy.needsApproval,
+      };
+    }
+  }
+  const output = resolveExpectedOutput(config, cwd.cwd, args.expectedOutputPath || "");
+  if (!output.ok) return { allowed: false, reason: output.reason, category: "long-job" };
+  return { allowed: true, category: "long-job" };
+}
+
+export async function startLongJob(args = {}, config = {}) {
+  const guard = checkLongJobToolUse("start_long_job", args, config);
+  if (!guard.allowed) {
+    return {
+      ok: false,
+      blocked: true,
+      toolName: "start_long_job",
+      reason: guard.reason,
+      category: guard.category,
+      needsApproval: guard.needsApproval,
+    };
+  }
+
+  const name = normalizeJobName(args.name || "aginti-long-job");
+  const command = String(args.command || "").trim();
+  const verifyCommand = String(args.verifyCommand || "").trim();
+  const cwd = resolveCwd(config, args.cwd || ".");
+  const output = resolveExpectedOutput(config, cwd.cwd, args.expectedOutputPath || "");
+  const root = cwd.root;
+  const jobId = makeJobId(name);
+  const session = tmuxSessionName(jobId);
+  const jobDir = path.join(root, ".aginti", "long-jobs", jobId);
+  const relativeJobDir = path.relative(root, jobDir) || ".";
+  const statusPath = path.join(relativeJobDir, "status.json");
+  const statusMarkdownPath = path.join(relativeJobDir, "status.md");
+  const supervisorPath = path.join(jobDir, "supervisor.mjs");
+  const stdoutPath = path.join(relativeJobDir, "stdout.log");
+  const stderrPath = path.join(relativeJobDir, "stderr.log");
+  const supervisorLogPath = path.join(relativeJobDir, "supervisor.log");
+  const expectedSizeBytes = clampInteger(args.expectedSizeBytes, 0, 0, Number.MAX_SAFE_INTEGER);
+  const pollIntervalSeconds = clampInteger(
+    args.pollIntervalSeconds,
+    DEFAULT_POLL_INTERVAL_SECONDS,
+    5,
+    3600
+  );
+  const timeoutSeconds = clampInteger(args.timeoutSeconds, 0, 0, 60 * 60 * 24 * 14);
+
+  await fsp.mkdir(jobDir, { recursive: true });
+  const metadata = {
+    jobId,
+    name,
+    session,
+    createdAt: new Date().toISOString(),
+    cwd: cwd.cwd,
+    command: redactSensitiveText(command),
+    displayCommand: redactSensitiveText(command),
+    rawCommandSha256: crypto.createHash("sha256").update(command).digest("hex"),
+    verifyCommand: verifyCommand ? redactSensitiveText(verifyCommand) : "",
+    expectedOutputPath: output.outputPath,
+    expectedOutputPathAbs: output.outputPathAbs,
+    expectedSizeBytes,
+    restartOnFailure: Boolean(args.restartOnFailure),
+    pollIntervalSeconds,
+    timeoutSeconds,
+    statusPath,
+    stdoutPath,
+    stderrPath,
+    supervisorLogPath,
+    note: redactSensitiveText(String(args.note || "")),
+  };
+  await fsp.writeFile(path.join(jobDir, "job.json"), JSON.stringify({ ...metadata, command, verifyCommand }, null, 2));
+  await fsp.writeFile(supervisorPath, supervisorSource());
+  await fsp.writeFile(path.join(jobDir, "command.txt"), `${command}\n`);
+  if (verifyCommand) await fsp.writeFile(path.join(jobDir, "verify.txt"), `${verifyCommand}\n`);
+  await fsp.writeFile(path.join(jobDir, "status.md"), buildStatusMarkdown(metadata));
+  await fsp.writeFile(path.join(jobDir, "events.jsonl"), "");
+  await fsp.writeFile(
+    path.join(jobDir, "status.json"),
+    JSON.stringify({ ...metadata, state: "created", outputBytes: 0, percent: null, updatedAt: new Date().toISOString() }, null, 2)
+  );
+
+  const tmux = await runTmux(
+    ["new-session", "-d", "-s", session, "-c", cwd.cwd, `${shellQuote(process.execPath)} ${shellQuote(supervisorPath)}`],
+    { timeout: 12000, signal: config.abortSignal }
+  );
+  if (!tmux.ok) {
+    return {
+      ok: false,
+      toolName: "start_long_job",
+      error: tmux.stderr || tmux.error,
+      reason: "Failed to start durable tmux long job. Ensure tmux is installed or use a shorter blocking command.",
+      jobId,
+      statusPath,
+    };
+  }
+
+  return {
+    ok: true,
+    toolName: "start_long_job",
+    jobId,
+    name,
+    session,
+    target: `${session}:0.0`,
+    cwd: cwd.cwd,
+    statusPath,
+    statusMarkdownPath,
+    eventsPath: path.join(relativeJobDir, "events.jsonl"),
+    stdoutPath,
+    stderrPath,
+    supervisorLogPath,
+    expectedOutputPath: output.outputPath,
+    expectedSizeBytes,
+    restartOnFailure: Boolean(args.restartOnFailure),
+    pollIntervalSeconds,
+    timeoutSeconds,
+    background: true,
+    deferredVerification: true,
+    result: `Started durable background job ${jobId}. Status: ${statusPath}. Logs: ${stdoutPath}, ${stderrPath}.`,
+    instruction:
+      "Long job is running in tmux. Do not keep the model loop alive to poll it; report the job id and status path, then finish unless the user explicitly asked for an interactive status check.",
+  };
+}
+
+export async function longJobStatus(args = {}, config = {}) {
+  const jobId = String(args.jobId || "").trim();
+  if (!JOB_ID_PATTERN.test(jobId)) {
+    return { ok: false, blocked: true, toolName: "long_job_status", reason: "Invalid or missing long job id." };
+  }
+  const root = workspaceRoot(config);
+  const statusAbs = path.join(root, ".aginti", "long-jobs", jobId, "status.json");
+  try {
+    const status = JSON.parse(await fsp.readFile(statusAbs, "utf8"));
+    let sessionAlive = null;
+    if (status.session) {
+      const alive = await runTmux(["has-session", "-t", status.session], { timeout: 4000, signal: config.abortSignal });
+      sessionAlive = Boolean(alive.ok);
+    }
+    return {
+      ok: true,
+      toolName: "long_job_status",
+      jobId,
+      statusPath: path.relative(root, statusAbs),
+      sessionAlive,
+      ...status,
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      toolName: "long_job_status",
+      jobId,
+      reason: `Could not read long job status: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+}

package/src/model-client.js

@@ -463,13 +463,26 @@ function mockCommandForGoal(goal = "") {
 function mockShouldPreferShellForGoal(goal = "") {
   const text = String(goal || "");
   return (
-    /\b(?:command|shell|terminal|pwd|working directory|current working directory|safe command|run command|review focus|code review|git status|git diff|changed files)\b/i.test(
+    /\b(?:command|shell|terminal|pwd|working directory|current working directory|safe command|run command|review focus|code review|git status|git diff|changed files|download|wget|curl|long[- ]running|background job|large file)\b/i.test(
       text
     ) ||
-    /当前工作目录|工作目录|命令|终端/.test(text)
+    /当前工作目录|工作目录|命令|终端|下载|后台|长时间/.test(text)
   );
 }
 
+function mockLongJobToolForGoal(goal = "") {
+  const text = String(goal || "").toLowerCase();
+  if (!/\b(download|wget|curl|long[- ]running|hours?|background|durable job|large file)\b|下载|后台|长时间/.test(text)) return null;
+  return mockToolCall("start_long_job", {
+    name: "mock-long-job",
+    command: "printf 'mock long job complete\\n' > mock-long-job-output.txt",
+    expectedOutputPath: "mock-long-job-output.txt",
+    verifyCommand: "grep -q complete mock-long-job-output.txt",
+    pollIntervalSeconds: 5,
+    note: "Mock long-job handoff smoke.",
+  });
+}
+
 function mockPathForGoal(goal = "") {
   const text = String(goal);
   if (/\bAGINTI\.md\b|project instructions|remember (?:that|this)|durable preference/i.test(text)) return "AGINTI.md";
@@ -693,7 +706,7 @@ export async function createPlan(client, config, state) {
             ? `Shell tool is enabled in ${config.commandCwd}. Host platform: ${platformLabel(platform)}. In Docker, this path is mounted as /workspace with persistent /aginti-env and /aginti-cache mounts, and common host data roots such as the user's home parent are mounted read-only at their original absolute paths for inspection. Use relative paths or /workspace for outputs and writes. Absolute host paths are acceptable for read-only inspection when visible, but do not write outside /workspace unless the user approves host mode. Permission mode: ${config.permissionMode || "normal"}. Sandbox mode: ${config.sandboxMode}. Package install policy: ${config.packageInstallPolicy}. For npm/pip/conda/venv setup, explain the need and wait for approval unless policy is allow. Do not run npx aginti, npm exec aginti, or nested aginti diagnostics from this shell; they may resolve stale project packages or create recursive agent sessions. On native Windows host mode, prefer PowerShell/cmd-compatible commands or WSL/Docker for bash-like toolchains.`
             : "",
           config.allowShellTool
-            ? "Host tmux tools are enabled for long-running sessions. Plan to use tmux_start_session for durable jobs, tmux_capture_pane to monitor, tmux_send_keys to interact after capture, and tmux_list_sessions to discover existing sessions. Tmux captures include old scrollback, so after a restart require a fresh run marker, heartbeat, PID, or log/status timestamp before treating capture text as current evidence. Do not install or run tmux inside Docker run_command containers; those containers are short-lived and cannot preserve tmux servers. In Docker sandbox mode, tmux startup/send commands are still workspace-write-bound and shell-pane text follows the same Docker workspace command policy as run_command: use relative project paths for writes and outputs. Read-only inspection of visible host absolute paths is allowed through run_command's read-only mounts; do not use tmux as a workaround for package installs, destructive git rewrites, or broad shell commands. In host mode, tmux startup/send command text follows the same host shell policy as run_command; if blocked, present the suggested approval/rerun path instead of trying tmux as a workaround. Ask for --sandbox-mode host --allow-destructive before trusted whole-host write/system work."
+            ? "Long-job tools are enabled for downloads, long I/O, long tests/builds, model jobs, and any command likely to run for minutes or hours. Plan to use start_long_job with expectedOutputPath/expectedSizeBytes/verifyCommand when applicable; it creates a durable tmux-backed supervisor and returns immediately, so do not keep the model loop alive with wait/poll steps. Use long_job_status only when the user explicitly asks for status later. Host tmux tools are also enabled for interactive durable sessions. Use tmux_start_session for manual terminals, tmux_capture_pane to monitor, tmux_send_keys to interact after capture, and tmux_list_sessions to discover existing sessions. Tmux captures include old scrollback, so after a restart require a fresh run marker, heartbeat, PID, or log/status timestamp before treating capture text as current evidence. Do not install or run tmux inside Docker run_command containers; those containers are short-lived and cannot preserve tmux servers. In Docker sandbox mode, tmux/long-job commands are still workspace-write-bound and shell-pane text follows the same Docker workspace command policy as run_command: use relative project paths for writes and outputs. Read-only inspection of visible host absolute paths is allowed through run_command's read-only mounts; do not use tmux as a workaround for package installs, destructive git rewrites, or broad shell commands. In host mode, tmux startup/send command text follows the same host shell policy as run_command; if blocked, present the suggested approval/rerun path instead of trying tmux as a workaround. Ask for --sandbox-mode host --allow-destructive before trusted whole-host write/system work."
             : "",
           config.allowFileTools
             ? `Workspace file tools are enabled in ${config.commandCwd}: inspect_project, list_files, read_file, search_files, write_file, apply_patch, open_workspace_file, preview_workspace. For large or unfamiliar repos, plan to call inspect_project first, then search/read AGINTI.md/AGENTS.md/README/manifests and exact files. apply_patch supports exact single-file replacements and Codex-style/unified multi-file patches; prefer it for edits after reading relevant context. Keep all paths workspace-relative, for example plot_fx.svg or docs/report.tex, and avoid secrets. For newly generated standalone prose/docs/stories/assets, choose a descriptive non-conflicting filename from the topic/language instead of generic names like story.txt or output.txt; do not overwrite existing files unless the user explicitly asked to update/replace/overwrite that file. For generated local HTML/SVG/PDF/static sites, plan to use open_workspace_file or preview_workspace rather than starting a localhost server inside Docker.`
@@ -742,7 +755,7 @@ export async function createPlan(client, config, state) {
           "For environment or system-maintenance work, prefer project-local dry-run plans/scripts unless the configured policy explicitly allows stronger actions.",
           "Docker language/toolchain installs should prefer /aginti-env or project files so they persist across runs; apt/apk changes are ephemeral unless the image is rebuilt.",
           "If a localhost/browser preview fails, do not loop on the same URL. Switch to open_workspace_file or preview_workspace, or finish with the local path and honest limitation.",
-          "If the run is close to the max-step limit, finish with the best complete artifact and honest limitations instead of starting a new approach.",
+          "If a command will take minutes or hours, hand it to start_long_job and finish with the durable status path instead of burning model steps. If the run is close to the max-step limit, finish with the best complete artifact and honest limitations instead of starting a new approach.",
           "Plan for a complete result, not endless exploration; finish once the request is satisfied and checks have passed or been honestly skipped.",
           "Return a numbered plan only.",
         ]
@@ -1239,6 +1252,65 @@ export async function requestNextStep(client, config, messages) {
     tools.splice(
       -1,
       0,
+      {
+        type: "function",
+        function: {
+          name: "start_long_job",
+          description:
+            "Start a durable tmux-backed background job for downloads, long I/O, long tests/builds, model jobs, or any command expected to take minutes or hours. This tool writes .aginti/long-jobs/<jobId>/status.json plus stdout/stderr/supervisor logs and returns immediately. Use expectedOutputPath, expectedSizeBytes, restartOnFailure, and verifyCommand for resumable downloads. After this tool succeeds, do not keep the model loop alive with wait/poll calls; finish with the job id and status path unless the user explicitly asked for an immediate one-time status check.",
+          parameters: {
+            type: "object",
+            properties: {
+              name: { type: "string", description: "Short safe job name, e.g. dataset-download or latex-build." },
+              command: { type: "string", description: "Shell command to run under the active shell policy. Do not include secrets." },
+              cwd: { type: "string", description: "Workspace-relative cwd for the job. Defaults to ." },
+              expectedOutputPath: {
+                type: "string",
+                description: "Optional expected output file path. Relative paths are resolved from cwd. Used for progress and completion checks.",
+              },
+              expectedSizeBytes: {
+                type: "integer",
+                description: "Optional exact expected output size in bytes, e.g. Content-Length for downloads.",
+              },
+              verifyCommand: {
+                type: "string",
+                description: "Optional shell verification after the main command succeeds, e.g. unzip -t file.zip or sha256sum -c checksums.txt.",
+              },
+              restartOnFailure: {
+                type: "boolean",
+                description: "Restart command when it exits before expected output is complete. Useful with wget -c/curl -C resumable downloads.",
+              },
+              pollIntervalSeconds: {
+                type: "integer",
+                description: "Shell supervisor status update and restart delay, 5 to 3600 seconds. Defaults to 60.",
+              },
+              timeoutSeconds: {
+                type: "integer",
+                description: "Optional overall timeout. 0 means no timeout.",
+              },
+              note: { type: "string", description: "Short human note for the status card." },
+            },
+            required: ["command"],
+            additionalProperties: false,
+          },
+        },
+      },
+      {
+        type: "function",
+        function: {
+          name: "long_job_status",
+          description:
+            "Read the deterministic status JSON for a previously started start_long_job. Use only when the user asks for status or when a later run explicitly needs to verify a background job; do not poll this repeatedly inside one model loop.",
+          parameters: {
+            type: "object",
+            properties: {
+              jobId: { type: "string", description: "Job id returned by start_long_job." },
+            },
+            required: ["jobId"],
+            additionalProperties: false,
+          },
+        },
+      },
       {
         type: "function",
         function: {
@@ -1637,6 +1709,10 @@ export async function requestNextStep(client, config, messages) {
     }
 
     if (config.allowShellTool && mockShouldPreferShellForGoal(config.goal)) {
+      const longJobTool = mockLongJobToolForGoal(config.goal);
+      if (longJobTool) {
+        return mockChatResponse("Mock mode will start a durable long job instead of polling in the model loop.", [longJobTool]);
+      }
       return mockChatResponse("Mock mode will use the guarded shell tool for an explicitly local command task.", [
         mockToolCall("run_command", { command: mockCommandForGoal(config.goal) }),
       ]);

package/src/scs-evidence.js

@@ -625,6 +625,18 @@ function toolPayloadToEvidence(payload = {}, source = "tool") {
   if (toolName === "run_command" || payload.stdout || Number.isInteger(payload.exitCode)) {
     push("command", `exit=${payload.exitCode ?? 0} stdout=${compact(payload.stdout || "", 260)}`, args.command || "");
   }
+  if (["start_long_job", "long_job_status"].includes(toolName)) {
+    push(
+      "command",
+      `${toolName} ${payload.state ? `state=${payload.state}` : payload.background ? "background=true" : ""} status=${payload.statusPath || ""}`,
+      payload.statusPath || payload.expectedOutputPath || args.command || ""
+    );
+    push(
+      "artifact",
+      `${toolName} produced durable status/log artifact paths`,
+      payload.statusMarkdownPath || payload.statusPath || payload.expectedOutputPath || ""
+    );
+  }
   if (["open_url", "click", "type", "scroll", "press", "back"].includes(toolName) || /\b(browser|chrome|cdp|playwright|selenium|upload|attach|submit|click|tab|page)\b/.test(text)) {
     push("browser", `${toolName || "browser tool"} affected or inspected browser/UI state`, payload.url || args.url || args.command || "");
   }