@lazyingart/agintiflow 0.20.331 → 0.20.336-integration.2

package/README.md

@@ -409,6 +409,7 @@ More detail:
 - [docs/auxiliary-image-generation.md](docs/auxiliary-image-generation.md)
 - [docs/perception-and-web-research.md](docs/perception-and-web-research.md)
 - [docs/deep-research-engine.md](docs/deep-research-engine.md)
+- [docs/integration-deep-research.md](docs/integration-deep-research.md)
 - [docs/cli-i18n.md](docs/cli-i18n.md)
 - [docs/skillmesh.md](docs/skillmesh.md)
 
@@ -420,6 +421,7 @@ More detail:
 | AgentLink | [docs/agentlink.md](docs/agentlink.md) |
 | Model selection and roles | [docs/model-selection.md](docs/model-selection.md) |
 | Local-first provider and agent boundary | [docs/local-first-agent-runtime.md](docs/local-first-agent-runtime.md) |
+| Replaceable integration worker coordination | [docs/integration-worker-directory.md](docs/integration-worker-directory.md) |
 | SCS mode | [docs/student-committee-supervisor.md](docs/student-committee-supervisor.md) |
 | Large-codebase engineering | [docs/large-codebase-engineering.md](docs/large-codebase-engineering.md) |
 | Runtime modes and autonomy | [docs/runtime-modes-and-autonomy.md](docs/runtime-modes-and-autonomy.md) |

package/bin/aginti-document-worker-runtime-check.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+import { verifyIntegrationDocumentWorkerNodeRuntime } from "../src/integration-document-worker-runtime.js";
+
+if (process.argv.length !== 2) {
+  process.stderr.write("aginti-document-worker-runtime-check: RUNTIME_IDENTITY_INVALID\n");
+  process.exitCode = 1;
+} else {
+  verifyIntegrationDocumentWorkerNodeRuntime().catch(() => {
+    process.stderr.write("aginti-document-worker-runtime-check: RUNTIME_IDENTITY_INVALID\n");
+    process.exitCode = 1;
+  });
+}

package/bin/aginti-document-worker.js

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

package/bin/aginti-execution-worker.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+import {
+  createProductionExecutionWorkerServer,
+  installExecutionWorkerShutdownHandlers,
+  loadExecutionWorkerServerConfig,
+} from "../src/execution-worker-server.js";
+
+try {
+  const config = await loadExecutionWorkerServerConfig();
+  const runtime = await createProductionExecutionWorkerServer({ config });
+  installExecutionWorkerShutdownHandlers(runtime.server);
+  console.log(JSON.stringify({
+    ok: true,
+    service: "aginti-execution-worker",
+    workerId: config.workerId,
+    runtimeBundleRootDigest: config.runtimeBundleRootDigest,
+    listener: runtime.address,
+  }));
+} catch (error) {
+  console.error(JSON.stringify({
+    ok: false,
+    service: "aginti-execution-worker",
+    code: typeof error?.code === "string" ? error.code : "EXECUTION_WORKER_START_FAILED",
+  }));
+  process.exitCode = 1;
+}

package/bin/aginti-integration-analysis-state.js

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

package/bin/aginti-integration-analysis.js

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

package/bin/aginti-public-research.js

@@ -9,6 +9,7 @@ function optionValue(argv, name) {
 const argv = process.argv.slice(2);
 if (argv.includes("--help") || argv.includes("-h")) {
   console.log("Usage: aginti-public-research [--host 127.0.0.1] [--port 3211]");
+  console.log("Use --port 0 to let the operating system allocate an ephemeral loopback port.");
   console.log("Starts only the fail-closed public research API; it does not start AgInTiFlow Studio or chat.");
   process.exit(0);
 }

package/bin/aginti-worker-directory.js

@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+
+import {
+  INTEGRATION_WORKER_DIRECTORY_PLATFORMS,
+  INTEGRATION_WORKER_DIRECTORY_ROLES,
+  createIntegrationWorkerDirectory,
+} from "../src/integration-worker-directory.js";
+import { createSystemdExecutionWorkerBindingAuthority } from "../src/integration-execution-worker-router.js";
+
+const HELP = `Usage: aginti-worker-directory <command> [options]
+
+Read commands:
+  status
+  events
+  resolve --role <role>
+
+Mutation commands:
+  enroll --node-id <id> --binding-id <id> --platform <platform> --roles <role,...>
+  renew --node-id <id>
+  switch --role <role> --node-id <id> --expected-generation <n>
+  rollback --role <role> --expected-generation <n>
+  finalize --role <role> --expected-generation <n>
+  retire --node-id <id>
+  remove --node-id <id>
+
+The command reads only the fixed owner-only manifest and systemd credentials.
+It never accepts an endpoint, host, port, URL, token, or credential name.
+
+Roles: ${INTEGRATION_WORKER_DIRECTORY_ROLES.join(", ")}
+Platforms: ${INTEGRATION_WORKER_DIRECTORY_PLATFORMS.join(", ")}
+`;
+
+const COMMAND_FLAGS = Object.freeze({
+  status: Object.freeze([]),
+  events: Object.freeze([]),
+  resolve: Object.freeze(["role"]),
+  enroll: Object.freeze(["node-id", "binding-id", "platform", "roles"]),
+  renew: Object.freeze(["node-id"]),
+  switch: Object.freeze(["role", "node-id", "expected-generation"]),
+  rollback: Object.freeze(["role", "expected-generation"]),
+  finalize: Object.freeze(["role", "expected-generation"]),
+  retire: Object.freeze(["node-id"]),
+  remove: Object.freeze(["node-id"]),
+});
+const PROBED_COMMANDS = new Set(["enroll", "renew", "switch", "rollback"]);
+
+function usage(message) {
+  const error = new Error(message);
+  error.code = "WORKER_DIRECTORY_CLI_USAGE";
+  error.status = 400;
+  throw error;
+}
+
+function parse(argv) {
+  if (argv.length === 0 || argv[0] === "--help" || argv[0] === "-h" || argv[0] === "help") {
+    return Object.freeze({ command: "help", options: Object.freeze({}) });
+  }
+  const command = argv[0];
+  const allowed = COMMAND_FLAGS[command];
+  if (!allowed) usage(`Unknown command: ${command}`);
+  const options = {};
+  for (let index = 1; index < argv.length; index += 2) {
+    const flag = argv[index];
+    const value = argv[index + 1];
+    if (typeof flag !== "string" || !flag.startsWith("--") || value === undefined) {
+      usage("Options must use --name value pairs.");
+    }
+    const name = flag.slice(2);
+    if (!allowed.includes(name)) usage(`Unsupported option for ${command}: --${name}`);
+    if (Object.prototype.hasOwnProperty.call(options, name)) usage(`Duplicate option: --${name}`);
+    options[name] = value;
+  }
+  for (const name of allowed) {
+    if (!Object.prototype.hasOwnProperty.call(options, name)) usage(`Missing option: --${name}`);
+  }
+  if (Object.prototype.hasOwnProperty.call(options, "expected-generation")) {
+    generation(options["expected-generation"]);
+  }
+  return Object.freeze({ command, options: Object.freeze(options) });
+}
+
+function generation(value) {
+  if (!/^(?:0|[1-9][0-9]{0,8})$/u.test(String(value || ""))) {
+    usage("--expected-generation must be a non-negative integer.");
+  }
+  return Number(value);
+}
+
+function roles(value) {
+  const result = String(value || "").split(",").filter(Boolean);
+  if (!result.length || result.some((role) => !INTEGRATION_WORKER_DIRECTORY_ROLES.includes(role))) {
+    usage("--roles contains an unsupported role.");
+  }
+  return result;
+}
+
+async function openDirectory(command) {
+  if (!PROBED_COMMANDS.has(command)) {
+    return Object.freeze({
+      directory: await createIntegrationWorkerDirectory({
+        probe: async () => {
+          throw new Error("worker probe is unavailable for this read-only command");
+        },
+      }),
+      close() {},
+    });
+  }
+  const authority = await createSystemdExecutionWorkerBindingAuthority();
+  try {
+    const directory = await createIntegrationWorkerDirectory({
+      probe: (candidate) => authority.probe(candidate),
+    });
+    return Object.freeze({ directory, close: () => authority.close() });
+  } catch (error) {
+    authority.close();
+    throw error;
+  }
+}
+
+async function dispatch(parsed) {
+  if (parsed.command === "help") return HELP;
+  const opened = await openDirectory(parsed.command);
+  const { directory } = opened;
+  const options = parsed.options;
+  try {
+    switch (parsed.command) {
+      case "status":
+        return directory.status();
+      case "events":
+        return directory.events();
+      case "resolve":
+        return directory.resolve(options.role);
+      case "enroll":
+        return directory.enroll({
+          nodeId: options["node-id"],
+          bindingId: options["binding-id"],
+          platform: options.platform,
+          roles: roles(options.roles),
+        });
+      case "renew":
+        return directory.renew(options["node-id"]);
+      case "switch":
+        return directory.switchRole(options.role, options["node-id"], {
+          expectedGeneration: generation(options["expected-generation"]),
+        });
+      case "rollback":
+        return directory.rollbackRole(options.role, {
+          expectedGeneration: generation(options["expected-generation"]),
+        });
+      case "finalize":
+        return directory.finalizeRole(options.role, {
+          expectedGeneration: generation(options["expected-generation"]),
+        });
+      case "retire":
+        return directory.retire(options["node-id"]);
+      case "remove":
+        return directory.remove(options["node-id"]);
+      default:
+        usage("Unsupported command.");
+    }
+  } finally {
+    opened.close();
+  }
+}
+
+try {
+  const parsed = parse(process.argv.slice(2));
+  const result = await dispatch(parsed);
+  process.stdout.write(typeof result === "string" ? result : `${JSON.stringify(result, null, 2)}\n`);
+} catch (error) {
+  process.stderr.write(`${JSON.stringify({
+    error: {
+      code: error?.code || "WORKER_DIRECTORY_CLI_FAILED",
+      message: error?.message || "Worker directory command failed.",
+    },
+  })}\n`);
+  process.exitCode = 1;
+}

package/docs/integration-analysis-state-migration.md

@@ -0,0 +1,47 @@
+# Integration analysis state migration
+
+`aginti-integration-analysis-state` performs the forward-only storage-floor migration from canonical analysis state v2 to v3. It always processes every scope in one state root and does not accept a scope selector.
+
+Stop the analysis service, then run the command as the operating-system user that owns the state root:
+
+```sh
+aginti-integration-analysis-state migrate \
+  --offline \
+  --state-root /absolute/owner-only/analysis-state
+```
+
+The command requires `--offline`. Its migration contract denies network access and does not load service configuration, credentials, model clients, search clients, or document-worker clients. Run it inside the same host network sandbox used for offline maintenance when the host provides one.
+
+The migrator fails closed unless the root, `scopes` directory, every scope directory, and every `state.json` file have their expected canonical paths, current-user ownership, owner-only modes, and safe link counts. It takes the analysis-session ownership lock, performs a read-only validation of every scope before changing anything, accepts only canonical v2 or already-valid canonical v3 records, and refuses the entire migration if any persisted run is not terminal. A recognized crash-left temporary file is validated during this read-only pass and removed only after the whole root passes preflight.
+
+A live analysis service or migrator always blocks the command. A lock left by a killed process becomes reclaimable only after 60 seconds and only when its schema, cryptographic owner token, PID, boot ID, process start identity, and acquisition timestamp are valid and that exact process identity is no longer live. This permits bounded crash recovery without breaking a live owner.
+
+Each v2 record receives empty document-intent arrays and run lineage inferred by the runtime's own parser. The state revision and all existing semantics remain unchanged. The runtime's canonical encoder recomputes the envelope digest. Each converted scope is written to an owner-only temporary file, fsynced, atomically renamed, verified, and followed by a directory fsync.
+
+Conversion is resumable without a rollback journal: completed scopes are valid v3, untouched scopes remain valid v2, and a rerun accepts that mixed state and continues forward. Scope directories are processed by explicit lowercase-hex code-unit order, independent of host locale. A second run over an all-v3 root does not rewrite files.
+
+Successful output contains only counts, fixed contract fields, and aggregate SHA-256-derived digests. It never prints root paths, scope identifiers, principals, browser sessions, thread/run identifiers, prompts, messages, artifacts, or document content.
+
+## Lock-held prewrite handshake
+
+An operator that must complete an external durable cutover step between validation and the first state mutation can enable the prewrite gate:
+
+```sh
+aginti-integration-analysis-state migrate \
+  --offline \
+  --state-root /absolute/owner-only/analysis-state \
+  --prewrite-gate-nonce "$cutover_nonce" \
+  --prewrite-gate-timeout-ms 120000
+```
+
+Both gate flags are required together. The nonce must be exactly 64 lowercase hexadecimal characters. The timeout must be an integer from 1 through 600000 milliseconds. Generate a fresh unpredictable nonce in the controller for each attempt; do not reuse a nonce across independent cutovers.
+
+The command takes `.analysis-session-owner.lock`, validates the complete root, computes every canonical v3 target, and writes one JSON gate record to stdout. It continues holding that same lock while it waits on stdin. The gate record is deterministic for a given nonce, timeout, current state, and target plan. It contains only fixed protocol fields, counts, aggregate digests, and a derived storage-state label; it never exposes a scope identity or path.
+
+`sourceV2ScopeCount` and `sourceV3ScopeCount` always sum to `scopeCount`. `migrationTemporaryCount` counts validated crash-left migration temporary files and cannot exceed `scopeCount`. `currentStorageState` is derived from the source counts: `empty` for zero scopes, `all-v2` when every nonempty scope is v2, `all-v3` when every nonempty scope is v3, and `mixed` only when both source versions are present. A controller can therefore apply its marker/storage matrix without releasing the lock. The `targetAggregateDigest` is computed solely from each scope's canonical v3 output, so it remains identical for equivalent all-v2, partially migrated, and all-v3 roots even though their current-state metadata differs.
+
+The controller must first durably complete and verify its external cutover step. It then writes the gate record's `requiredAck` value followed by exactly one LF byte to the migrator's stdin and closes its stdin write side. The migrator accepts the acknowledgement only after observing EOF, so the complete input must be exactly `requiredAck + "\n"` with no trailing byte. The single configured timeout covers receipt of both those bytes and EOF. The acknowledgement is bound to the nonce, target aggregate, and migration contract. Do not reconstruct or normalize it when the exact emitted value can be relayed.
+
+Until that exact acknowledgement is received, the migrator does not remove a crash-left migration temporary file and does not create, replace, or rewrite any state or migration-temporary file. EOF, a mismatched acknowledgement, input failure, or timeout fails closed, releases the ownership lock, and leaves the preflight state untouched. After acknowledgement, the normal resumable migration runs under the continuously held lock. A second JSON line is written only after final verification and is the ordinary migration result.
+
+The gate is a synchronization boundary, not remote authentication: stdout reveals the required acknowledgement by design. The controller is responsible for withholding it until its separately authenticated durable action is complete. Keep the analysis service stopped for the whole command, including the acknowledgement wait.

package/docs/integration-deep-research.md

@@ -0,0 +1,9 @@
+# Integrated deep research
+
+The durable analysis API promotes only explicit deep-research instructions such as “perform deep research” or “全面研究”. Ordinary questions and ordinary Search requests stay on their existing fast paths.
+
+An eligible run uses the private LazyEdge-bound LocalLLM task protocol at the exact `create`, `status`, and `cancel` routes. AgInTi fixes the model alias, limits the depth to `quick`, `standard`, or `deep`, polls one stable task identity, cancels incomplete work on abort, and accepts only bounded no-cache responses. Exact domain, DOI, arXiv, and image-grounded requests retain the stricter one-shot Search path instead of weakening their constraints.
+
+The completed report is accepted only with at least one safe source and valid one-based citations. Every source is preserved in one authority-bound `sources` artifact. A pure research request returns that validated report directly; a combined document, file, or execution request carries it forward as untrusted evidence for the remaining agent work.
+
+Search/research intent, task activity, artifacts, failures, and terminal state use the same durable session ledger as other Agent work. The next message in the thread does not inherit stale research authority or completed activity. Public capabilities advertise the optional `localllm/research-task/v2` protocol while retaining the original Search contract for older Web clients.

package/docs/integration-worker-directory.md

@@ -0,0 +1,99 @@
+# Integration worker directory
+
+Status: the durable directory, leased execution router, fixed-manifest binding authority, and production preference path are implemented and smoke-tested. Production remains on the fixed client until a manifest and initial assignment are installed and accepted.
+
+AgInTi owns durable worker identity, role assignment, migration, rollback, drain, retirement, and removal. LazyEdge owns only authenticated transport and admission checks. LocalLLM and other worker services own their role-specific model or tool execution. Callers cannot choose a URL or credential.
+
+## Stored state
+
+The directory stores only:
+
+- a stable node ID and opaque transport binding ID;
+- platform and declared roles;
+- short-lived admission evidence derived from readiness and capability probes;
+- generation-checked role assignments;
+- bounded execution leases used to drain an old worker safely;
+- an integrity-sealed, hash-chained transition ledger.
+
+It does not store endpoints, bearer tokens, cookies, passkeys, or other credentials. The default owner-only state root is `/var/lib/agintiflow-integration/worker-directory`; tests and isolated deployments can supply another absolute root.
+
+## Admission contract
+
+Enrollment and every switch or rollback require fresh probe evidence. Lease acquisition for the assigned node also refreshes evidence under the directory mutation lock when the stored admission is expired or cannot cover the requested lease TTL; sufficiently fresh admissions are reused without probing. Evidence binds the node and opaque binding, role set, transport kind, release and capability digests, canary digest, supported protocols, observation time, and expiry. Admission lifetime is at most ten minutes.
+
+The probe belongs to the trusted coordinator bootstrap. Candidate input containing an endpoint or credential is rejected before any probe or write. A later transport-binding adapter may resolve an opaque binding to a systemd credential and LazyEdge route, but that adapter must remain outside caller input.
+
+## Migration lifecycle
+
+1. Enroll and probe a candidate.
+2. Assign a role with the expected current generation.
+3. Acquire bounded leases for work accepted under that generation.
+4. Switch the role to a freshly probed replacement. New leases resolve to the replacement immediately; old leases remain attached to the previous node.
+5. Roll back while the previous-node pointer is retained, or finalize only after its leases drain.
+6. Retire and remove an unassigned, unleased node.
+
+Every mutation is serialized by an owner-only directory lock and committed with an atomic protected JSON replacement. Corrupt integrity seals, event chains, symlinks, hardlinks, malformed records, stale evidence, and generation conflicts fail closed.
+
+## Leased execution routing
+
+The analysis coordinator now has a routed mode. It acquires one execution lease before capability validation, refreshing the assigned node admission first if needed, resolves that lease to the opaque binding, opens the binding through an AgInTi-owned authority, and renews the lease heartbeat through job start, polling, cancellation, terminal-ledger validation, artifact retrieval, and artifact callbacks. Lease renewal refreshes admission for the leased node when the current evidence cannot cover the next lease TTL, even after the role has switched to a replacement. A role switch affects only later leases, so an in-flight job never changes workers halfway through its protocol.
+
+The router revalidates the worker capability digest against the admitted node evidence before starting a job. It releases the lease on success, cancellation, or failure only after the routed operation has settled. If lease renewal fails and the worker-side operation refuses to settle within the bounded cancellation drain, the router returns the renewal failure but keeps the durable lease for natural expiry so finalization/removal cannot race an unproven worker cleanup. A successful operation is not reported if its lease release cannot be committed; deterministic job identity allows the caller to retry safely.
+
+## Current limitation and next integration step
+
+Production composition prefers the routed coordinator when `/etc/agintiflow-integration/execution-worker-bindings.json` exists. It falls back to the fixed loopback client only when that file is absent. An unsafe, malformed, changed, or internally conflicting manifest fails startup; it never causes a silent downgrade. Activation still requires an initial directory assignment and real restart/cutover evidence.
+
+The manifest is secret-free but security-sensitive and must be a canonical, non-symlinked, single-link `0600` file in a trusted, non-writable directory. Each binding contains only:
+
+```json
+{
+  "schemaVersion": "aginti-integration-execution-worker-binding-v1",
+  "bindingId": "binding_local_workstation_01",
+  "transport": "local-loopback-http-v1",
+  "host": "127.0.0.1",
+  "port": 18130,
+  "credentialName": "execution-worker-token"
+}
+```
+
+The local binding is locked to `127.0.0.1:18130` and the existing fixed credential. LazyEdge bindings are also loopback-only from AgInTi's perspective and use reserved relay ports `18131` through `18194`, with distinct `execution-worker-binding-*` systemd credential names. Binding IDs, ports, and credential names must all be unique. Remote hosts, URLs, arbitrary ports, inline tokens, and caller-supplied credential names are rejected.
+
+The service unit must install every named credential with `LoadCredential=`. The binding client reads only the credential selected by a branded manifest record, validates the read-only systemd credential mount and file identity, then attests the binding ID, transport, manifest digest, and exact loopback endpoint. A manifest change requires a controlled service restart.
+
+The transition ledger currently refuses further transitions after its conservative capacity is reached rather than truncating audit history. Durable ledger segmentation is required before treating this coordinator as an unattended long-lived fleet registry.
+
+## Verification
+
+```bash
+npm run smoke:integration-worker-directory
+```
+
+The directory smoke covers workstation-to-Jetson migration, live-lease drain blocking, automatic acquire-time admission renewal, two-way rollback, finalization, retirement/removal, persisted restart recovery, expired-lease sweeping, stale and mismatched admission rejection, caller endpoint/credential rejection, invalid randomness, and fail-closed corruption, symlink, and hardlink cases.
+
+`npm run smoke:integration-analysis-coordinator` additionally proves that an in-flight job stays pinned to worker A during a switch, logical lease-heartbeats cross the 60-second lease and five-minute admission boundaries, finalization waits for its lease, uncooperative cancellation never drops the pin early, the next job uses worker B, and capability/admission divergence fails closed without leaking a settled lease.
+
+`npm run smoke:integration-execution-worker-binding-config` covers manifest canonicalization, local and LazyEdge port policy, uniqueness, fixed-path loading, branded bindings, and rejection of URL/token/endpoint injection.
+
+## Local operator commands
+
+Directory changes are local operator actions. The CLI exposes no transport or credential flags:
+
+```bash
+aginti-worker-directory status
+aginti-worker-directory enroll \
+  --node-id node_local_workstation_01 \
+  --binding-id binding_local_workstation_01 \
+  --platform workstation \
+  --roles execution
+aginti-worker-directory switch \
+  --role execution \
+  --node-id node_local_workstation_01 \
+  --expected-generation 0
+aginti-worker-directory rollback --role execution --expected-generation 2
+aginti-worker-directory finalize --role execution --expected-generation 2
+aginti-worker-directory retire --node-id node_old_workstation_01
+aginti-worker-directory remove --node-id node_old_workstation_01
+```
+
+Every switch and rollback requires the exact current generation. Enrollment, renewal, switching, and rollback load the fixed manifest and probe the selected worker through its branded systemd binding. Read-only status and event inspection do not require a credential. CLI output contains state and digests but no secrets.

package/docs/labcanvas-chatops-fallback.md

@@ -38,6 +38,88 @@ AGINTI_EVIDENCE_SCOPE_JSON: {"mode":"task","request":"Create the requested PDF f
 
 For `chat-response`, ordinary conversation and routing do not require file or command evidence. `host-managed-response` is for content-only subtasks such as a LaTeX body, translation, completion audit, or scheduled lesson where LabCanvas owns persistence, compilation, validation, and delivery. For `task`, evidence requirements are inferred only from the exact request, not from surrounding wrapper prose. Artifact requests still require real artifacts.
 
+## Completion-Audit Artifact Coverage
+
+A completion audit cannot mark an exact task item covered merely because its
+candidate contains a substantive text answer. When that item directly asks to
+create, attach, send, save, download, or otherwise deliver a file, the
+candidate must contain compatible material artifact evidence.
+
+Accepted evidence includes structured `files`, `artifacts`, `attachments`, or
+deliverable records with a matching extension, MIME type, or media kind. A
+nonempty `generated_pdf_content` field also satisfies a PDF requirement when
+the host owns compilation. Plain prose such as `the PDF was sent` does not.
+The boundary covers document, image, video, audio, archive, and common CAD
+formats in English, Chinese, and Japanese.
+
+Artifact intent remains scoped to the output. Reading `report.pdf`, analyzing
+an attached video, or returning a summary of a video does not require the input
+file to be returned. Explicit `do not attach a PDF` wording likewise remains a
+text-only request. A completion audit also enforces explicit negative delivery
+contracts. It cannot cover `create no files or attachments` when the structured
+candidate contains outbound files or generated document/media content. A
+format-specific exclusion such as `send PDF only; do not attach Markdown`
+rejects only the forbidden format. If another exact request item in the same
+packet positively requires an artifact, that independent requirement remains
+valid instead of being erased by the first item's preference.
+
+An invalid audit receives one bounded repair; repeated invalid coverage fails
+closed with the exact task item retained as missing and classified as an
+artifact requirement. LabCanvas still owns transport, compilation, validation,
+and delivery.
+
+## Source-Free Hypotheses And Experiment Plans
+
+A scheduled inspiration may explicitly ask for an original, falsifiable idea
+without supplying a fresh literature manifest. That is different from claiming
+that a paper, benchmark, or completed experiment proves the idea. AgInTi accepts
+the former only when the response locally labels it as the assistant's own
+unverified hypothesis or prediction.
+
+Numeric settings in a proposed experiment, such as group counts, durations, or
+sampling intervals, are treated as protocol parameters rather than observed
+benchmark results. The exception is narrow: wording that claims an experiment
+already found, validated, achieved, or improved a result remains evidence
+gated, as do named papers, journals, datasets, and external research tools.
+This keeps quiet-period inspiration useful when a hosted provider hands off to
+LocalLLM without allowing proposal language to launder unsupported facts.
+
+## Bounded Media Source Quality
+
+When a response-only packet explicitly asks AgInTi to summarize actual speech,
+the packet's transcript is the speech authority. A title, description, author,
+or hashtag may identify the source, but it cannot substitute for speech.
+
+AgInTi checks a structured bounded transcript before accepting the response. A
+long transcript with no content, implausibly little content, or extreme
+repetition is treated as unusable. The backend receives one bounded repair turn
+that must:
+
+- disclose that the actual speech cannot be summarized reliably;
+- avoid inferring speech, visuals, or events from metadata;
+- label any metadata-based theme explicitly as title- or description-based;
+- preserve the caller's JSON schema and truthful delivery flags.
+
+If the repair repeats the unsupported summary, the turn stops with a
+schema-compatible limitation instead of recording invented content as a
+successful response. Reliable transcripts and requests that only ask to
+identify supplied metadata are unaffected. Exact-source download,
+transcription, attachments, and chat delivery remain host-owned routines.
+
+## Fail-Closed Envelope Integrity
+
+A response-only safety stop must preserve an explicit caller JSON envelope.
+This applies when a backend repeats an unsupported source claim and when it
+fails the JSON contract itself after the single bounded repair turn. The
+fallback object keeps every required top-level key, value type, and declared
+string enum; it places the private diagnostic in a non-enum field such as
+`message`, `summary`, or `reason`. It never replaces a route enum with prose.
+
+The session remains stopped and does not record `session.finished`. Envelope
+preservation only lets the host parse and recover the task reliably; it does
+not convert the failed turn into success, select a provider, or change any
+LabCanvas queue, schedule, transport, or routing policy.
+
 ## Provider Tool-Batch Recovery
 
 AgInTi requests one effectful tool call at a time, but some OpenAI-compatible
@@ -52,6 +134,63 @@ oversized batch still stop with `tool_contract_violation`. A host may resume
 the same saved session with another provider after that categorized stop; it
 must not replay the original request or duplicate earlier side effects.
 
+## Secret-Bearing Derived Content
+
+Private source packets can legitimately contain signed media URLs, cookies, or
+token-shaped fields that must not be copied into a reader-facing artifact.
+Workspace secret guards remain authoritative: the proposed write is blocked
+before any file mutation.
+
+That block is a content-correction event, not a request for stronger runtime
+permission. AgInTi receives one bounded automatic recovery instruction to
+remove the private field or replace its value with `[REDACTED]`, retain the
+useful non-sensitive content, and write the originally requested derived
+artifact. It must not edit the authoritative source record merely to sanitize a
+summary, repeat the blocked value, or expose the value in its final response.
+Other protected-path, outside-workspace, destructive, and
+permission-sensitive blocks keep their existing approval behavior.
+
+## Local Artifact Preview Recovery
+
+`open_url` is only for remote `http` and `https` sources. A fallback model may
+still copy a local artifact path into a `file://` URL when it intends to inspect
+a generated PDF, HTML page, image, or text file. The remote-browser guard keeps
+that URL blocked, but the mistake is a tool-selection error rather than a
+request for stronger permission.
+
+AgInTi receives one bounded automatic correction. It converts the local URL to
+an authorized workspace-relative path and chooses `open_workspace_file` for a
+single rendered file, `preview_workspace` for a static site or directory, or
+`read_file` when textual inspection is enough. It must not retry `open_url`,
+start a temporary localhost server, or ask the user to elevate the sandbox.
+The replacement workspace tool still enforces its normal path and read-root
+rules, so an outside-workspace or protected target remains blocked.
+
+## Current-Turn Response Fidelity
+
+Response-only prompts contain host control metadata and may contain prior
+bot-authored messages for conversational continuity. Neither is an answer to
+the current inbound message. AgInTiFlow therefore rejects two exact replay
+forms before accepting completion:
+
+- a returned JSON object that is identical to an
+  `AGINTI_EVIDENCE_SCOPE_JSON` control envelope;
+- a substantive primary response field that exactly repeats a prior
+  `is_self: true` chat message while the current message asks something else.
+
+The backend receives one bounded repair turn that identifies the current
+message as authoritative and preserves any explicit JSON key and type
+contract. A current message that explicitly requests a verbatim repetition is
+accepted. Merely quoting an earlier bot message to ask about it is not a repeat
+request.
+
+The replay check runs again after transcript-quality and source-free-evidence
+repairs. This prevents one validator from replacing a rejected answer with
+stale context that a later stage would otherwise accept. A repeated replay
+fails closed in the caller's parseable envelope, leaves the session stopped,
+and never records `session.finished`. This does not alter LabCanvas routing,
+provider priority, queues, schedules, transports, or chat coalescing.
+
 ## Local Context Recovery
 
 LocalLLM planning compacts oversized goals to a bounded head-and-tail representation. Runtime compaction retains the first request and latest interruptions. A `LocalContextBudgetError` triggers one compact-and-retry cycle at the same step and records private recovery events. It does not authorize replaying task side effects.