From 60ee033722a61a9ad7506b81129f8b1fa5e5cb8a Mon Sep 17 00:00:00 2001
From: limityan <limit_yan@sina.com>
Date: Mon, 3 Aug 2026 18:58:31 +0800
Subject: [PATCH] perf(test): consolidate agent runtime contract targets

---
 .../rust-build-dependency-boundaries.md       |   1 +
 docs/performance/01-compile-performance.md    |  23 +++
 scripts/check-core-boundaries.test.mjs        |   1 +
 scripts/core-boundaries/checker.mjs           |  11 +-
 .../explicit-test-topology.mjs                | 180 ++++++++++++++++++
 .../rules/source/forbidden-rules.mjs          |   2 +-
 .../rules/source/required-rules.mjs           |  28 +--
 scripts/core-boundaries/self-test.mjs         | 112 +++++++++--
 src/crates/execution/agent-runtime/AGENTS.md  |  27 +++
 src/crates/execution/agent-runtime/Cargo.toml |  21 ++
 .../tests/agent_definition_contracts.rs       |  18 ++
 .../agent_registry_contracts.rs               |   0
 .../context_profile.rs                        |   0
 .../custom_agent_mode_contracts.rs            |   0
 .../custom_subagent_contracts.rs              |   0
 .../custom_subagent_discovery_contracts.rs    |   0
 .../prompt_cache_contracts.rs                 |   0
 .../prompt_contracts.rs                       |   0
 .../skill_contracts.rs                        |   0
 .../tests/agent_interaction_contracts.rs      |  14 ++
 .../native_hook_payload_contracts.rs          |   0
 .../native_hook_settings_contracts.rs         |   0
 .../permission_contracts.rs                   |   0
 .../post_call_hook_contracts.rs               |   0
 .../post_call_hook_execution_contracts.rs     |   0
 .../user_question_tool_contracts.rs           |   0
 .../tests/agent_long_horizon_contracts.rs     |  10 +
 .../deep_research_contracts.rs                |   0
 .../deep_review_policy_contracts.rs           |   0
 .../thread_goal_contracts.rs                  |   0
 .../thread_goal_tool_handler_contracts.rs     |   0
 .../tests/agent_session_contracts.rs          |  20 ++
 .../events_contracts.rs                       |   0
 .../interaction_response_contracts.rs         |   0
 .../scheduled_job_contracts.rs                |   0
 .../scheduler_contracts.rs                    |   0
 .../sdk_smoke.rs                              |   0
 .../session_control_contracts.rs              |   0
 .../session_model_sdk.rs                      |   0
 .../session_operation_ports.rs                |   0
 .../workspace_reference_ports.rs              |   0
 41 files changed, 437 insertions(+), 31 deletions(-)
 create mode 100644 scripts/core-boundaries/explicit-test-topology.mjs
 create mode 100644 src/crates/execution/agent-runtime/tests/agent_definition_contracts.rs
 rename src/crates/execution/agent-runtime/tests/{ => agent_definition_contracts}/agent_registry_contracts.rs (100%)
 rename src/crates/execution/agent-runtime/tests/{ => agent_definition_contracts}/context_profile.rs (100%)
 rename src/crates/execution/agent-runtime/tests/{ => agent_definition_contracts}/custom_agent_mode_contracts.rs (100%)
 rename src/crates/execution/agent-runtime/tests/{ => agent_definition_contracts}/custom_subagent_contracts.rs (100%)
 rename src/crates/execution/agent-runtime/tests/{ => agent_definition_contracts}/custom_subagent_discovery_contracts.rs (100%)
 rename src/crates/execution/agent-runtime/tests/{ => agent_definition_contracts}/prompt_cache_contracts.rs (100%)
 rename src/crates/execution/agent-runtime/tests/{ => agent_definition_contracts}/prompt_contracts.rs (100%)
 rename src/crates/execution/agent-runtime/tests/{ => agent_definition_contracts}/skill_contracts.rs (100%)
 create mode 100644 src/crates/execution/agent-runtime/tests/agent_interaction_contracts.rs
 rename src/crates/execution/agent-runtime/tests/{ => agent_interaction_contracts}/native_hook_payload_contracts.rs (100%)
 rename src/crates/execution/agent-runtime/tests/{ => agent_interaction_contracts}/native_hook_settings_contracts.rs (100%)
 rename src/crates/execution/agent-runtime/tests/{ => agent_interaction_contracts}/permission_contracts.rs (100%)
 rename src/crates/execution/agent-runtime/tests/{ => agent_interaction_contracts}/post_call_hook_contracts.rs (100%)
 rename src/crates/execution/agent-runtime/tests/{ => agent_interaction_contracts}/post_call_hook_execution_contracts.rs (100%)
 rename src/crates/execution/agent-runtime/tests/{ => agent_interaction_contracts}/user_question_tool_contracts.rs (100%)
 create mode 100644 src/crates/execution/agent-runtime/tests/agent_long_horizon_contracts.rs
 rename src/crates/execution/agent-runtime/tests/{ => agent_long_horizon_contracts}/deep_research_contracts.rs (100%)
 rename src/crates/execution/agent-runtime/tests/{ => agent_long_horizon_contracts}/deep_review_policy_contracts.rs (100%)
 rename src/crates/execution/agent-runtime/tests/{ => agent_long_horizon_contracts}/thread_goal_contracts.rs (100%)
 rename src/crates/execution/agent-runtime/tests/{ => agent_long_horizon_contracts}/thread_goal_tool_handler_contracts.rs (100%)
 create mode 100644 src/crates/execution/agent-runtime/tests/agent_session_contracts.rs
 rename src/crates/execution/agent-runtime/tests/{ => agent_session_contracts}/events_contracts.rs (100%)
 rename src/crates/execution/agent-runtime/tests/{ => agent_session_contracts}/interaction_response_contracts.rs (100%)
 rename src/crates/execution/agent-runtime/tests/{ => agent_session_contracts}/scheduled_job_contracts.rs (100%)
 rename src/crates/execution/agent-runtime/tests/{ => agent_session_contracts}/scheduler_contracts.rs (100%)
 rename src/crates/execution/agent-runtime/tests/{ => agent_session_contracts}/sdk_smoke.rs (100%)
 rename src/crates/execution/agent-runtime/tests/{ => agent_session_contracts}/session_control_contracts.rs (100%)
 rename src/crates/execution/agent-runtime/tests/{ => agent_session_contracts}/session_model_sdk.rs (100%)
 rename src/crates/execution/agent-runtime/tests/{ => agent_session_contracts}/session_operation_ports.rs (100%)
 rename src/crates/execution/agent-runtime/tests/{ => agent_session_contracts}/workspace_reference_ports.rs (100%)

diff --git a/docs/architecture/rust-build-dependency-boundaries.md b/docs/architecture/rust-build-dependency-boundaries.md
index 8e16cbcfd6..8e836364da 100644
--- a/docs/architecture/rust-build-dependency-boundaries.md
+++ b/docs/architecture/rust-build-dependency-boundaries.md
@@ -136,6 +136,7 @@ DTO/contract 抽取不等于 runtime owner 迁移。迁移 owner 必须先审查
 - integration test 只依赖被测 owner 的公开契约，不通过 `product-full` 获取测试便利；窄 feature 尚不能独立编译时，应将其记录为待拆分的 owner/feature 边界并保持现有 target 声明，不得新增或扩大 `product-full` 来制造已经收敛的假象；
 - 纯解析、策略和状态转换优先使用无外部系统的 owner-local fixture；
 - 需要真实 adapter/service 的测试单独作为 feature integration target；
+- 同一 owner 内 feature、平台与依赖闭包完全相同的 integration tests，应按稳定职责收敛为少量显式 target，避免每个源文件重复编译和链接同一闭包；本地通过 `--test <target> <module>::<filter>` 保留 focused test。不同 feature、平台、进程或外部系统边界不得为减少 target 数而合并；
 - 测试常用、真实的 feature 组合，不穷举指数级组合；
 - `--all-features` 用于兼容审计，不代替目标产品的最小组合测试。
 
diff --git a/docs/performance/01-compile-performance.md b/docs/performance/01-compile-performance.md
index bfcaaaf744..c263f4af86 100644
--- a/docs/performance/01-compile-performance.md
+++ b/docs/performance/01-compile-performance.md
@@ -30,6 +30,7 @@
 | F17 | pnpm 结构小问题:tests/e2e 已在 workspace 内仍单独 install;installer 独立 Rust workspace 导致 Tauri 栈本地编译两份 | 结构 | 低 | `pnpm-workspace.yaml`、`package.json:92`、`Cargo.toml:40-42` |
 | F18 | build.rs 生成代码遍历 HashMap,输出字节序不确定 → 不可复现构建,削弱 sccache/远端缓存效果 | Rust | 低 | `src/crates/assembly/core/build.rs:303,429`、`src/apps/cli/build.rs` |
 | F19 | `[profile.dev] incremental = true` 为默认值,冗余;dev profile 无任何针对性调优 | Rust | 低 | `Cargo.toml:279-280` |
+| F20 | `bitfun-agent-runtime` 的 28 个 integration targets 已收敛为 5 个显式目标，同时保留 Unix 进程测试隔离 | Rust/Test | 已兑现 | `src/crates/execution/agent-runtime/Cargo.toml`、`tests/agent_*_contracts.rs` |
 
 ---
 
@@ -243,6 +244,27 @@ Desktop、CLI、ACP、Server 与 SDK Host 的内容、错误和生命周期完
 
 `Cargo.toml:279-280` 的 `incremental = true` 是 dev 默认值,可删;该段落是放置 F5 建议(`debug = "line-tables-only"`)的天然位置。
 
+### F20（已治理）agent-runtime integration test 重复链接
+
+`bitfun-agent-runtime` 没有可选 feature，原 28 个 integration test target 中的 27 个跨平台契约使用相同的依赖闭包，
+却在每次 `cargo test -p bitfun-agent-runtime` 时分别编译和链接。当前通过 `autotests = false` 将它们按定义、会话、
+交互和 long-horizon 职责归入 4 个 target；另保留 1 个 Unix-only 原生进程 target，避免为了减少数量而跨平台或进程
+边界合并。246 个 Unix integration tests、224 个 Windows integration tests 及原有 lib tests 均保留。现有 CI 命令和
+覆盖范围不变，未新增测试、feature、依赖或 workflow；现有边界检查会拒绝未注册入口和未被引用的叶测试文件。
+
+以下是本机观察值，不作为其他机器的固定收益承诺。测量日期 2026-08-03，基线
+`53c8c029a8b6245e810cbee0707c820bc74fb7b8`，Windows 10.0.19045、i7-10700、rustc/cargo 1.97.1；依赖预热后按
+原布局/现布局交错执行 A/B/A/B/A/B，每次运行
+`cargo clean -p bitfun-agent-runtime` 和 `cargo test -p bitfun-agent-runtime --no-run --locked --quiet`：
+
+| 布局 | 三次有效样本 | 中位数 | integration PDB |
+|---|---|---:|---:|
+| 原 28 targets | 12.48s / 15.01s / 13.63s | 13.63s | 312.3 MiB |
+| 现 5 targets | 11.90s / 11.04s / 11.31s | 11.31s | 77.4 MiB |
+
+本机包级 test 编译/链接中位数降低约 17.0%，PDB 体积降低约 75.2%。这是测试可执行目标治理，不代表第三方依赖
+或 feature 数量减少；有独立 feature、平台、进程或外部系统边界的测试仍必须保持独立 target。
+
 ---
 
 ## 三、实施建议清单(可直接派发给实施 agent)
@@ -265,6 +287,7 @@ Desktop、CLI、ACP、Server 与 SDK Host 的内容、错误和生命周期完
 | T12 | beforeBuildCommand 并行(F13):新增 `scripts/frontend-build-all.mjs` 并行跑 build:web 与 prepare:mobile-web,tauri.conf.json / tauri.dev.conf.json 的 beforeBuildCommand 指向它;dev.cjs 准备步骤改 Promise.all。验收:desktop:build 前端阶段时长≈max(两者) 而非 sum。 | `src/apps/desktop/tauri.conf.json`、`tauri.dev.conf.json`、`scripts/dev.cjs`、新脚本 | 低 |
 | T13 | bitfun-core 拆分启动(F3,长期):先跑 `cargo build --timings` 与 `cargo tree -d` 存档基线;选 1-2 个低耦合子域(如 announcement、debug-log server)试点拆出独立 crate 并保留 re-export;结合 F12 的"dev 运行时读取提示词"改造。验收:改动试点子域后 `cargo build -p bitfun-desktop` 的重编 crate 数与耗时下降。 | `src/crates/assembly/core/**`、根 `Cargo.toml` members | 中-高(架构改动,分多个 PR 渐进) |
 | T14 | 可选工具链增强(F5):提交 `.cargo/config.toml` 模板(注释形式提供 rust-lld 与 sccache 配置,默认不启用),团队自选开启;CI 冷构建可评估 sccache-action。验收:提供文档,默认行为不变。 | 新增 `.cargo/config.toml`、文档 | 低(默认关闭) |
+| T15（已完成） | agent-runtime integration target 收敛(F20):保持全部 contract test 源与现有 CI 命令不变，将 27 个跨平台契约按定义、会话、交互、long-horizon 职责归为 4 个 target，Unix 原生进程测试保持独立；focused test 使用 `--test <target> <module>::<filter>`。 | `agent-runtime/Cargo.toml`、`agent-runtime/tests/**`、现有 boundary rule 路径 | 已完成；总体 28→5，只减少重复编译/链接，不改变 feature 或依赖闭包 |
 
 ### 快速收益组合(建议第一批实施)
 T2 + T4 + T5 + T6 + T9 + T10 + T12:全部低风险,合计可显著改善日常 dev 循环(启动省 20-60s、增量链接提速、dev CPU 下降)与 build:web 时长;随后再做 T1(最大单项前端收益)、T3(打包 CI)、T7/T8(CI 结构)。
diff --git a/scripts/check-core-boundaries.test.mjs b/scripts/check-core-boundaries.test.mjs
index 9e63d4d048..69a95917aa 100644
--- a/scripts/check-core-boundaries.test.mjs
+++ b/scripts/check-core-boundaries.test.mjs
@@ -23,6 +23,7 @@ const ENTRYPOINT = new URL('./check-core-boundaries.mjs', import.meta.url);
 const MODULES = [
   './core-boundaries/checker.mjs',
   './core-boundaries/cargo-dependency-boundaries.mjs',
+  './core-boundaries/explicit-test-topology.mjs',
   './core-boundaries/manifest-feature-helpers.mjs',
   './core-boundaries/self-test.mjs',
   './core-boundaries/rules/crate-rules.mjs',
diff --git a/scripts/core-boundaries/checker.mjs b/scripts/core-boundaries/checker.mjs
index 396ec3d35a..66aea673bf 100644
--- a/scripts/core-boundaries/checker.mjs
+++ b/scripts/core-boundaries/checker.mjs
@@ -1,7 +1,6 @@
 import { existsSync, readdirSync, readFileSync, statSync } from 'fs';
-import { join, relative } from 'path';
+import { dirname, join, relative } from 'path';
 import { fileURLToPath } from 'url';
-import { dirname } from 'path';
 
 import {
   dependencyProfileRules,
@@ -36,6 +35,11 @@ import {
   unexpectedReachableLocalFeatures,
 } from './manifest-feature-helpers.mjs';
 import { checkCargoDependencyBoundariesSafely } from './cargo-dependency-boundaries.mjs';
+import {
+  agentRuntimeIntegrationTestTargets,
+  checkAgentRuntimeIntegrationTestTopology,
+  validateExplicitIntegrationTestTopology,
+} from './explicit-test-topology.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const ROOT = join(__dirname, '..', '..');
@@ -1086,6 +1090,8 @@ export function runCoreBoundaryCheck() {
       hasPluginWildcardReexport,
       createFacadeLineChecker,
       escapeRegex,
+      validateExplicitIntegrationTestTopology,
+      agentRuntimeIntegrationTestTargets,
     });
     console.log('Core boundary check self-test passed.');
     return;
@@ -1093,6 +1099,7 @@ export function runCoreBoundaryCheck() {
 
   checkCrateLayoutRules();
   failures.push(...checkCargoDependencyBoundariesSafely({ root: ROOT, crateLayoutRules }));
+  failures.push(...checkAgentRuntimeIntegrationTestTopology(ROOT));
 
   for (const rule of forbiddenManifestDependencyRules) {
     checkForbiddenManifestDependencyRule(rule);
diff --git a/scripts/core-boundaries/explicit-test-topology.mjs b/scripts/core-boundaries/explicit-test-topology.mjs
new file mode 100644
index 0000000000..010cd72431
--- /dev/null
+++ b/scripts/core-boundaries/explicit-test-topology.mjs
@@ -0,0 +1,180 @@
+import { readdirSync, readFileSync } from 'node:fs';
+import { join, posix, relative } from 'node:path';
+
+export const agentRuntimeIntegrationTestTargets = [
+  { name: 'agent_definition_contracts', path: 'tests/agent_definition_contracts.rs' },
+  { name: 'agent_interaction_contracts', path: 'tests/agent_interaction_contracts.rs' },
+  { name: 'agent_long_horizon_contracts', path: 'tests/agent_long_horizon_contracts.rs' },
+  { name: 'agent_session_contracts', path: 'tests/agent_session_contracts.rs' },
+  { name: 'native_hook_execution_contracts', path: 'tests/native_hook_execution_contracts.rs' },
+];
+
+function parseExplicitTestTargets(manifestText) {
+  const targets = [];
+  let current = null;
+  const finishCurrent = () => {
+    if (current) {
+      targets.push(current);
+      current = null;
+    }
+  };
+
+  for (const line of manifestText.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (trimmed === '[[test]]') {
+      finishCurrent();
+      current = {};
+      continue;
+    }
+    if (trimmed.startsWith('[')) {
+      finishCurrent();
+      continue;
+    }
+    const field = current && trimmed.match(/^(name|path)\s*=\s*"([^"]+)"\s*$/);
+    if (field) {
+      current[field[1]] = field[2];
+    }
+  }
+  finishCurrent();
+  return targets;
+}
+
+function packageDisablesAutotests(manifestText) {
+  let inPackage = false;
+  for (const line of manifestText.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith('[')) {
+      inPackage = trimmed === '[package]';
+      continue;
+    }
+    if (inPackage && /^autotests\s*=\s*false\s*$/.test(trimmed)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function parseFlatRootModules(root, source, errors) {
+  const references = [];
+  const lines = source.split(/\r?\n/);
+  let valid = true;
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index].trim();
+    if (line === '' || line.startsWith('//!')) {
+      continue;
+    }
+    const pathAttribute = line.match(/^#\[path\s*=\s*"([^"]+)"\]$/);
+    const moduleDeclaration = lines[index + 1]?.trim().match(/^mod\s+([A-Za-z0-9_]+)\s*;$/);
+    if (!pathAttribute || !moduleDeclaration) {
+      errors.push(`grouped test root ${root} contains unsupported line ${index + 1}`);
+      valid = false;
+      continue;
+    }
+    references.push({ path: pathAttribute[1], moduleName: moduleDeclaration[1] });
+    index += 1;
+  }
+  return valid ? references : [];
+}
+
+export function validateExplicitIntegrationTestTopology({
+  manifestText,
+  expectedTargets,
+  topLevelRustFiles,
+  rootSources,
+  leafRustFiles,
+}) {
+  const errors = [];
+  if (!packageDisablesAutotests(manifestText)) {
+    errors.push('[package] must keep autotests = false');
+  }
+
+  const expectedTargetEntries = expectedTargets.map(({ name, path }) => `${name}=${path}`).sort();
+  const actualTargetEntries = parseExplicitTestTargets(manifestText)
+    .map(({ name, path }) => `${name ?? '<missing-name>'}=${path ?? '<missing-path>'}`)
+    .sort();
+  if (actualTargetEntries.join('\n') !== expectedTargetEntries.join('\n')) {
+    errors.push(`explicit test targets must be exactly: ${expectedTargetEntries.join(', ')}`);
+  }
+
+  const expectedRoots = expectedTargets.map(({ path }) => path).sort();
+  if ([...topLevelRustFiles].sort().join('\n') !== expectedRoots.join('\n')) {
+    errors.push(`top-level test roots must be exactly: ${expectedRoots.join(', ')}`);
+  }
+
+  const leaves = new Set(leafRustFiles);
+  const referenceCounts = new Map();
+  for (const root of expectedRoots) {
+    const source = rootSources.get(root);
+    if (source === undefined) {
+      errors.push(`missing explicit test root: ${root}`);
+      continue;
+    }
+    const wrapperDir = `${root.slice(0, -'.rs'.length)}/`;
+    const ownsLeaves = [...leaves].some((leaf) => leaf.startsWith(wrapperDir));
+    if (!ownsLeaves) {
+      continue;
+    }
+    for (const reference of parseFlatRootModules(root, source, errors)) {
+      const leaf = posix.normalize(posix.join(posix.dirname(root), reference.path));
+      if (!leaf.startsWith(wrapperDir)) {
+        errors.push(`grouped test root ${root} may only reference leaves under ${wrapperDir}`);
+        continue;
+      }
+      if (!leaves.has(leaf)) {
+        errors.push(`test root ${root} references missing leaf: ${leaf}`);
+        continue;
+      }
+      const expectedModuleName = posix.basename(leaf, '.rs');
+      if (reference.moduleName !== expectedModuleName) {
+        errors.push(`test leaf ${leaf} must use module name ${expectedModuleName}`);
+      }
+      referenceCounts.set(leaf, (referenceCounts.get(leaf) ?? 0) + 1);
+    }
+  }
+
+  for (const leaf of [...leaves].sort()) {
+    const count = referenceCounts.get(leaf) ?? 0;
+    if (count !== 1) {
+      errors.push(`test leaf ${leaf} must be referenced exactly once; found ${count}`);
+    }
+  }
+  return errors;
+}
+
+function collectRustFiles(dir, testsDir, files) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      collectRustFiles(path, testsDir, files);
+    } else if (entry.isFile() && entry.name.endsWith('.rs')) {
+      files.push(`tests/${relative(testsDir, path).replaceAll('\\', '/')}`);
+    }
+  }
+}
+
+export function checkAgentRuntimeIntegrationTestTopology(root) {
+  const crateDir = join(root, 'src', 'crates', 'execution', 'agent-runtime');
+  const testsDir = join(crateDir, 'tests');
+  const manifestPath = join(crateDir, 'Cargo.toml');
+  const topLevelRustFiles = [];
+  const leafRustFiles = [];
+  const rootSources = new Map();
+
+  for (const entry of readdirSync(testsDir, { withFileTypes: true })) {
+    if (entry.isFile() && entry.name.endsWith('.rs')) {
+      const repoPath = `tests/${entry.name}`;
+      topLevelRustFiles.push(repoPath);
+      rootSources.set(repoPath, readFileSync(join(testsDir, entry.name), 'utf8'));
+    } else if (entry.isDirectory()) {
+      collectRustFiles(join(testsDir, entry.name), testsDir, leafRustFiles);
+    }
+  }
+
+  return validateExplicitIntegrationTestTopology({
+    manifestText: readFileSync(manifestPath, 'utf8'),
+    expectedTargets: agentRuntimeIntegrationTestTargets,
+    topLevelRustFiles,
+    rootSources,
+    leafRustFiles,
+  }).map((message) => ({ path: manifestPath, line: 1, message }));
+}
diff --git a/scripts/core-boundaries/rules/source/forbidden-rules.mjs b/scripts/core-boundaries/rules/source/forbidden-rules.mjs
index dea61a3289..36f61f805e 100644
--- a/scripts/core-boundaries/rules/source/forbidden-rules.mjs
+++ b/scripts/core-boundaries/rules/source/forbidden-rules.mjs
@@ -139,7 +139,7 @@ export const forbiddenContentRules = [
     ],
   },
   {
-    path: 'src/crates/execution/agent-runtime/tests/sdk_smoke.rs',
+    path: 'src/crates/execution/agent-runtime/tests/agent_session_contracts/sdk_smoke.rs',
     patterns: [
       {
         regex: /\bbitfun_runtime_services::test_support\b/,
diff --git a/scripts/core-boundaries/rules/source/required-rules.mjs b/scripts/core-boundaries/rules/source/required-rules.mjs
index 9020689cdb..076890eb3b 100644
--- a/scripts/core-boundaries/rules/source/required-rules.mjs
+++ b/scripts/core-boundaries/rules/source/required-rules.mjs
@@ -743,7 +743,7 @@ export const requiredContentRules = [
     ],
   },
   {
-    path: 'src/crates/execution/agent-runtime/tests/sdk_smoke.rs',
+    path: 'src/crates/execution/agent-runtime/tests/agent_session_contracts/sdk_smoke.rs',
     reason:
       'agent-runtime SDK smoke tests must prove the facade works with injected fake provider, services, tools, harnesses, and hooks without core',
     patterns: [
@@ -1367,7 +1367,7 @@ export const requiredContentRules = [
     ],
   },
   {
-    path: 'src/crates/execution/agent-runtime/tests/deep_review_policy_contracts.rs',
+    path: 'src/crates/execution/agent-runtime/tests/agent_long_horizon_contracts/deep_review_policy_contracts.rs',
     reason:
       'agent-runtime DeepReview owner must keep behavior-equivalence contracts for policy, queue state, tool context, report enrichment, and cache updates',
     patterns: [
@@ -1402,7 +1402,7 @@ export const requiredContentRules = [
     ],
   },
   {
-    path: 'src/crates/execution/agent-runtime/tests/prompt_cache_contracts.rs',
+    path: 'src/crates/execution/agent-runtime/tests/agent_definition_contracts/prompt_cache_contracts.rs',
     reason:
       'agent-runtime prompt-cache owner must keep behavior-equivalence contracts for cache identity, expiry, invalidation, and scope-key shape',
     patterns: [
@@ -1696,7 +1696,7 @@ export const requiredContentRules = [
     ],
   },
   {
-    path: 'src/crates/execution/agent-runtime/tests/agent_registry_contracts.rs',
+    path: 'src/crates/execution/agent-runtime/tests/agent_definition_contracts/agent_registry_contracts.rs',
     reason:
       'agent-runtime agent registry owner must keep behavior-equivalence contracts for visibility, availability, shared mode config, and source ordering',
     patterns: [
@@ -1834,7 +1834,7 @@ export const requiredContentRules = [
     ],
   },
   {
-    path: 'src/crates/execution/agent-runtime/tests/custom_subagent_discovery_contracts.rs',
+    path: 'src/crates/execution/agent-runtime/tests/agent_definition_contracts/custom_subagent_discovery_contracts.rs',
     reason:
       'agent-runtime custom subagent discovery owner must keep behavior-equivalence contracts for BitFun directory priority, foreign directory exclusion, and load errors',
     patterns: [
@@ -1851,7 +1851,7 @@ export const requiredContentRules = [
     ],
   },
   {
-    path: 'src/crates/execution/agent-runtime/tests/custom_subagent_contracts.rs',
+    path: 'src/crates/execution/agent-runtime/tests/agent_definition_contracts/custom_subagent_contracts.rs',
     reason:
       'agent-runtime custom subagent owner must keep behavior-equivalence contracts for defaults and front-matter serialization decisions',
     patterns: [
@@ -1937,7 +1937,7 @@ export const requiredContentRules = [
     ],
   },
   {
-    path: 'src/crates/execution/agent-runtime/tests/post_call_hook_contracts.rs',
+    path: 'src/crates/execution/agent-runtime/tests/agent_interaction_contracts/post_call_hook_contracts.rs',
     reason:
       'agent-runtime post-call hook owner must keep behavior-equivalence contracts for successful tool-call hook routing',
     patterns: [
@@ -1960,7 +1960,7 @@ export const requiredContentRules = [
     ],
   },
   {
-    path: 'src/crates/execution/agent-runtime/tests/post_call_hook_execution_contracts.rs',
+    path: 'src/crates/execution/agent-runtime/tests/agent_interaction_contracts/post_call_hook_execution_contracts.rs',
     reason:
       'agent-runtime post-call hook owner must keep concrete-executor routing behavior-equivalence contracts',
     patterns: [
@@ -2089,7 +2089,7 @@ export const requiredContentRules = [
     ],
   },
   {
-    path: 'src/crates/execution/agent-runtime/tests/scheduler_contracts.rs',
+    path: 'src/crates/execution/agent-runtime/tests/agent_session_contracts/scheduler_contracts.rs',
     reason:
       'agent-runtime scheduler owner must keep behavior-equivalence contracts for background delivery, queueing, reply suppression, steering, round injection, and turn outcomes',
     patterns: [
@@ -2225,7 +2225,7 @@ export const requiredContentRules = [
     ],
   },
   {
-    path: 'src/crates/execution/agent-runtime/tests/thread_goal_contracts.rs',
+    path: 'src/crates/execution/agent-runtime/tests/agent_long_horizon_contracts/thread_goal_contracts.rs',
     reason:
       'agent-runtime thread-goal owner must keep behavior-equivalence contracts for goal creation, continuation limits, budget reporting, and wire response shape',
     patterns: [
@@ -2253,7 +2253,7 @@ export const requiredContentRules = [
     ],
   },
   {
-    path: 'src/crates/execution/agent-runtime/tests/prompt_contracts.rs',
+    path: 'src/crates/execution/agent-runtime/tests/agent_definition_contracts/prompt_contracts.rs',
     reason:
       'agent-runtime prompt owner must keep behavior-equivalence contracts for user context and reminder ordering',
     patterns: [
@@ -2291,7 +2291,7 @@ export const requiredContentRules = [
     ],
   },
   {
-    path: 'src/crates/execution/agent-runtime/tests/events_contracts.rs',
+    path: 'src/crates/execution/agent-runtime/tests/agent_session_contracts/events_contracts.rs',
     reason:
       'agent-runtime event owner must keep behavior-equivalence contracts for event wire labels',
     patterns: [
@@ -2441,7 +2441,7 @@ export const requiredContentRules = [
     ],
   },
   {
-    path: 'src/crates/execution/agent-runtime/tests/scheduled_job_contracts.rs',
+    path: 'src/crates/execution/agent-runtime/tests/agent_session_contracts/scheduled_job_contracts.rs',
     reason:
       'agent-runtime scheduled-job owner must keep behavior-equivalence contracts for wire shape, retry, coalescing, one-shot, missing-session, and restart recovery semantics',
     patterns: [
@@ -2732,7 +2732,7 @@ export const requiredContentRules = [
     ],
   },
   {
-    path: 'src/crates/execution/agent-runtime/tests/deep_research_contracts.rs',
+    path: 'src/crates/execution/agent-runtime/tests/agent_long_horizon_contracts/deep_research_contracts.rs',
     reason:
       'agent-runtime must keep behavior-equivalence contracts for DeepResearch citation renumbering',
     patterns: [
diff --git a/scripts/core-boundaries/self-test.mjs b/scripts/core-boundaries/self-test.mjs
index c5a5541010..2ae6fd33d9 100644
--- a/scripts/core-boundaries/self-test.mjs
+++ b/scripts/core-boundaries/self-test.mjs
@@ -29,6 +29,8 @@ export function runManifestParserSelfTest({
   hasPluginWildcardReexport,
   createFacadeLineChecker,
   escapeRegex,
+  validateExplicitIntegrationTestTopology,
+  agentRuntimeIntegrationTestTargets,
 }) {
   const positiveCases = [
     'bitfun-core = { path = "../core" }',
@@ -55,6 +57,88 @@ export function runManifestParserSelfTest({
     }
   }
 
+  const explicitTestManifest = [
+    '[package]',
+    'autotests = false',
+    ...agentRuntimeIntegrationTestTargets.flatMap(({ name, path }) => [
+      '[[test]]',
+      `name = "${name}"`,
+      `path = "${path}"`,
+    ]),
+    '[lints]',
+  ].join('\n');
+  const explicitTestRoots = new Map(
+    agentRuntimeIntegrationTestTargets.map(({ path }) => [path, '']),
+  );
+  explicitTestRoots.set(
+    'tests/agent_definition_contracts.rs',
+    '#[path = "agent_definition_contracts/prompt_contracts.rs"]\nmod prompt_contracts;',
+  );
+  const explicitTestFixture = {
+    manifestText: explicitTestManifest,
+    expectedTargets: agentRuntimeIntegrationTestTargets,
+    topLevelRustFiles: agentRuntimeIntegrationTestTargets.map(({ path }) => path),
+    rootSources: explicitTestRoots,
+    leafRustFiles: ['tests/agent_definition_contracts/prompt_contracts.rs'],
+  };
+  const topologyErrors = validateExplicitIntegrationTestTopology(explicitTestFixture);
+  if (topologyErrors.length > 0) {
+    throw new Error(`valid explicit integration-test topology failed: ${topologyErrors.join('; ')}`);
+  }
+  const orphanErrors = validateExplicitIntegrationTestTopology({
+    ...explicitTestFixture,
+    leafRustFiles: [
+      ...explicitTestFixture.leafRustFiles,
+      'tests/agent_definition_contracts/orphan_contracts.rs',
+    ],
+  });
+  if (!orphanErrors.some((error) => error.includes('orphan_contracts.rs'))) {
+    throw new Error('explicit integration-test topology must reject an orphan leaf test');
+  }
+  const wrongSectionErrors = validateExplicitIntegrationTestTopology({
+    ...explicitTestFixture,
+    manifestText: explicitTestManifest.replace(
+      '[package]\nautotests = false',
+      '[package]\n[package.metadata.test-topology]\nautotests = false',
+    ),
+  });
+  if (!wrongSectionErrors.some((error) => error.includes('[package]'))) {
+    throw new Error('explicit integration-test topology must read autotests from [package] only');
+  }
+  const commentedReferenceErrors = validateExplicitIntegrationTestTopology({
+    ...explicitTestFixture,
+    rootSources: new Map([
+      ...explicitTestRoots,
+      [
+        'tests/agent_definition_contracts.rs',
+        '/*\n#[path = "agent_definition_contracts/prompt_contracts.rs"]\nmod prompt_contracts;\n*/',
+      ],
+    ]),
+  });
+  if (!commentedReferenceErrors.some((error) => error.includes('prompt_contracts.rs'))) {
+    throw new Error('explicit integration-test topology must reject a commented-out leaf reference');
+  }
+  const duplicateReferenceErrors = validateExplicitIntegrationTestTopology({
+    ...explicitTestFixture,
+    rootSources: new Map([
+      ...explicitTestRoots,
+      [
+        'tests/agent_definition_contracts.rs',
+        `${explicitTestRoots.get('tests/agent_definition_contracts.rs')}\n${explicitTestRoots.get('tests/agent_definition_contracts.rs')}`,
+      ],
+    ]),
+  });
+  if (!duplicateReferenceErrors.some((error) => error.includes('found 2'))) {
+    throw new Error('explicit integration-test topology must reject a duplicate leaf reference');
+  }
+  const unexpectedRootErrors = validateExplicitIntegrationTestTopology({
+    ...explicitTestFixture,
+    topLevelRustFiles: [...explicitTestFixture.topLevelRustFiles, 'tests/unregistered.rs'],
+  });
+  if (!unexpectedRootErrors.some((error) => error.includes('top-level test roots'))) {
+    throw new Error('explicit integration-test topology must reject an unregistered test root');
+  }
+
   const parsedDeps = parseManifestDependencies([
     '[dependencies]',
     'reqwest = { workspace = true, optional = true }',
@@ -2373,7 +2457,7 @@ export function runManifestParserSelfTest({
       ],
     },
     {
-      path: 'src/crates/execution/agent-runtime/tests/sdk_smoke.rs',
+      path: 'src/crates/execution/agent-runtime/tests/agent_session_contracts/sdk_smoke.rs',
       contracts: [
         'sdk_facade_exposes_versioned_preview_compatibility_contract',
         'sdk_facade_runs_with_fake_provider_and_local_event_stream',
@@ -2411,7 +2495,7 @@ export function runManifestParserSelfTest({
       ],
     },
     {
-      path: 'src/crates/execution/agent-runtime/tests/agent_registry_contracts.rs',
+      path: 'src/crates/execution/agent-runtime/tests/agent_definition_contracts/agent_registry_contracts.rs',
       contracts: [
         'visibility_policy_supports_public_restricted_hidden_and_denied_parents',
         'availability_preserves_builtin_project_and_user_override_layering',
@@ -2454,14 +2538,14 @@ export function runManifestParserSelfTest({
       ],
     },
     {
-      path: 'src/crates/execution/agent-runtime/tests/custom_subagent_discovery_contracts.rs',
+      path: 'src/crates/execution/agent-runtime/tests/agent_definition_contracts/custom_subagent_discovery_contracts.rs',
       contracts: [
         'custom_subagent_discovery_preserves_bitfun_priority_and_ignores_foreign_agent_dirs',
         'custom_subagent_discovery_reports_parse_errors_without_dropping_valid_files',
       ],
     },
     {
-      path: 'src/crates/execution/agent-runtime/tests/custom_subagent_contracts.rs',
+      path: 'src/crates/execution/agent-runtime/tests/agent_definition_contracts/custom_subagent_contracts.rs',
       contracts: [
         'custom_subagent_defaults_match_existing_front_matter_contract',
         'custom_subagent_tool_front_matter_keeps_existing_comma_format',
@@ -2487,7 +2571,7 @@ export function runManifestParserSelfTest({
       ],
     },
     {
-      path: 'src/crates/execution/agent-runtime/tests/post_call_hook_contracts.rs',
+      path: 'src/crates/execution/agent-runtime/tests/agent_interaction_contracts/post_call_hook_contracts.rs',
       contracts: [
         'successful_tool_call_routes_to_shared_context_measurement_hook',
         'runtime_hook_registry_preserves_order_timeout_and_error_policy',
@@ -2496,7 +2580,7 @@ export function runManifestParserSelfTest({
       ],
     },
     {
-      path: 'src/crates/execution/agent-runtime/tests/post_call_hook_execution_contracts.rs',
+      path: 'src/crates/execution/agent-runtime/tests/agent_interaction_contracts/post_call_hook_execution_contracts.rs',
       contracts: ['successful_tool_post_call_executor_runs_deep_review_measurement_route'],
     },
     {
@@ -2672,7 +2756,7 @@ export function runManifestParserSelfTest({
       ],
     },
     {
-      path: 'src/crates/execution/agent-runtime/tests/scheduler_contracts.rs',
+      path: 'src/crates/execution/agent-runtime/tests/agent_session_contracts/scheduler_contracts.rs',
       contracts: [
         'background_delivery_injects_when_session_is_processing',
         'background_delivery_starts_agent_session_follow_up_when_session_is_not_processing',
@@ -2710,7 +2794,7 @@ export function runManifestParserSelfTest({
       ],
     },
     {
-      path: 'src/crates/execution/agent-runtime/tests/thread_goal_contracts.rs',
+      path: 'src/crates/execution/agent-runtime/tests/agent_long_horizon_contracts/thread_goal_contracts.rs',
       contracts: [
         'set_thread_goal_creates_new_active_goal_with_trimmed_objective',
         'continuation_outcome_increments_active_goal_and_builds_plan',
@@ -2792,7 +2876,7 @@ export function runManifestParserSelfTest({
       contracts: ['DialogTurnCancellationTokenStore', 'get_or_insert_new', 'is_cancelled'],
     },
     {
-      path: 'src/crates/execution/agent-runtime/tests/prompt_cache_contracts.rs',
+      path: 'src/crates/execution/agent-runtime/tests/agent_definition_contracts/prompt_cache_contracts.rs',
       contracts: [
         'prompt_cache_policy_keeps_existing_default_persistence_ttl',
         'prompt_cache_lookup_preserves_identity_and_expiry_semantics',
@@ -2800,7 +2884,7 @@ export function runManifestParserSelfTest({
       ],
     },
     {
-      path: 'src/crates/execution/agent-runtime/tests/prompt_contracts.rs',
+      path: 'src/crates/execution/agent-runtime/tests/agent_definition_contracts/prompt_contracts.rs',
       contracts: [
         'user_context_policy_preserves_order_and_deduplicates_sections',
         'tool_listing_sections_render_only_present_sections',
@@ -2812,7 +2896,7 @@ export function runManifestParserSelfTest({
       contracts: ['FinishReason', 'session_state_label', 'turn_outcome_kind'],
     },
     {
-      path: 'src/crates/execution/agent-runtime/tests/events_contracts.rs',
+      path: 'src/crates/execution/agent-runtime/tests/agent_session_contracts/events_contracts.rs',
       contracts: [
         'finish_reason_display_preserves_wire_labels',
         'session_state_labels_match_existing_event_wire_values',
@@ -2878,7 +2962,7 @@ export function runManifestParserSelfTest({
       ],
     },
     {
-      path: 'src/crates/execution/agent-runtime/tests/scheduled_job_contracts.rs',
+      path: 'src/crates/execution/agent-runtime/tests/agent_session_contracts/scheduled_job_contracts.rs',
       contracts: [
         'manual_trigger_coalesces_existing_pending_run',
         'due_scheduled_trigger_coalesces_when_active_or_pending',
@@ -3998,7 +4082,7 @@ export function runManifestParserSelfTest({
       contracts: ['renumber_research_report', 'ResearchCitationRenumberOutput', 'ResearchCitationDisplayMapEntry', 'rejected_index_rows_dropped', 'should_post_process_research_report'],
     },
     {
-      path: 'src/crates/execution/agent-runtime/tests/deep_research_contracts.rs',
+      path: 'src/crates/execution/agent-runtime/tests/agent_long_horizon_contracts/deep_research_contracts.rs',
       contracts: ['deep_research_citation_renumber_owner_preserves_report_and_display_map_contracts', 'deep_research_citation_renumber_owner_is_idempotent_without_citations'],
     },
     {
@@ -4760,7 +4844,7 @@ async fn release_baseline_claim(release: BaselineClaimRelease) -> Result<(), Dis
   }
 
   const sdkSmokeRuleText = forbiddenRuleTextForPath(
-    'src/crates/execution/agent-runtime/tests/sdk_smoke.rs',
+    'src/crates/execution/agent-runtime/tests/agent_session_contracts/sdk_smoke.rs',
   );
   for (const forbiddenSdkSmokeImport of [
     'bitfun_runtime_services::test_support',
diff --git a/src/crates/execution/agent-runtime/AGENTS.md b/src/crates/execution/agent-runtime/AGENTS.md
index 68cfb26228..16ba17d8a0 100644
--- a/src/crates/execution/agent-runtime/AGENTS.md
+++ b/src/crates/execution/agent-runtime/AGENTS.md
@@ -61,10 +61,37 @@ port-backed `sdk` / `AgentRuntime` facade that can be built and tested without
   outside this crate until a reviewed migration proves behavior equivalence.
 - Add focused tests before moving any runtime decision into this crate.
 
+## Test Target Layout
+
+Integration contracts use five explicit Cargo targets so package-level checks
+do not relink the same feature-free dependency closure for every source file,
+while platform-specific process tests retain executable-level isolation:
+
+| Target | Owns |
+|---|---|
+| `agent_definition_contracts` | Agent definitions, discovery, prompts, prompt cache, and skills |
+| `agent_session_contracts` | Events, scheduling, sessions, SDK behavior, and workspace-reference ports |
+| `agent_interaction_contracts` | Permissions, questions, and hook execution |
+| `agent_long_horizon_contracts` | DeepResearch, DeepReview, and long-running thread-goal behavior |
+| `native_hook_execution_contracts` | Unix-only native process execution, timeout, and cleanup behavior |
+
+Add a contract to the nearest existing target. Do not add another top-level
+integration target unless it requires a genuinely different feature,
+platform, process, or dependency boundary. Use `--lib <filter>` for a focused
+library test, or `--test <target> <module>::<filter>` for a focused public
+contract test.
+
+Grouped target roots stay flat: apart from module documentation, they contain
+only direct `#[path = "..."]` / `mod ...;` pairs, and every leaf `.rs` file is
+referenced exactly once. Isolated platform or process targets keep their test
+implementation in the root file. The core-boundary check enforces this shape
+so `autotests = false` cannot silently omit a new contract.
+
 ## Verification
 
 ```bash
 cargo test -p bitfun-agent-runtime
+cargo test -p bitfun-agent-runtime --test agent_definition_contracts prompt_contracts::
 node scripts/check-core-boundaries.mjs
 cargo check -p bitfun-core --features product-full
 ```
diff --git a/src/crates/execution/agent-runtime/Cargo.toml b/src/crates/execution/agent-runtime/Cargo.toml
index 689aab3e59..f00acf416e 100644
--- a/src/crates/execution/agent-runtime/Cargo.toml
+++ b/src/crates/execution/agent-runtime/Cargo.toml
@@ -4,6 +4,7 @@ version.workspace = true
 authors.workspace = true
 edition.workspace = true
 description = "Agent runtime contracts and owner decisions for BitFun"
+autotests = false
 
 [lib]
 name = "bitfun_agent_runtime"
@@ -37,5 +38,25 @@ tokio-util = { workspace = true }
 [dev-dependencies]
 tokio = { workspace = true, features = ["rt-multi-thread"] }
 
+[[test]]
+name = "agent_definition_contracts"
+path = "tests/agent_definition_contracts.rs"
+
+[[test]]
+name = "agent_session_contracts"
+path = "tests/agent_session_contracts.rs"
+
+[[test]]
+name = "agent_interaction_contracts"
+path = "tests/agent_interaction_contracts.rs"
+
+[[test]]
+name = "agent_long_horizon_contracts"
+path = "tests/agent_long_horizon_contracts.rs"
+
+[[test]]
+name = "native_hook_execution_contracts"
+path = "tests/native_hook_execution_contracts.rs"
+
 [lints]
 workspace = true
diff --git a/src/crates/execution/agent-runtime/tests/agent_definition_contracts.rs b/src/crates/execution/agent-runtime/tests/agent_definition_contracts.rs
new file mode 100644
index 0000000000..519ec16eb3
--- /dev/null
+++ b/src/crates/execution/agent-runtime/tests/agent_definition_contracts.rs
@@ -0,0 +1,18 @@
+//! Agent definition, discovery, prompt, and skill contracts.
+
+#[path = "agent_definition_contracts/agent_registry_contracts.rs"]
+mod agent_registry_contracts;
+#[path = "agent_definition_contracts/context_profile.rs"]
+mod context_profile;
+#[path = "agent_definition_contracts/custom_agent_mode_contracts.rs"]
+mod custom_agent_mode_contracts;
+#[path = "agent_definition_contracts/custom_subagent_contracts.rs"]
+mod custom_subagent_contracts;
+#[path = "agent_definition_contracts/custom_subagent_discovery_contracts.rs"]
+mod custom_subagent_discovery_contracts;
+#[path = "agent_definition_contracts/prompt_cache_contracts.rs"]
+mod prompt_cache_contracts;
+#[path = "agent_definition_contracts/prompt_contracts.rs"]
+mod prompt_contracts;
+#[path = "agent_definition_contracts/skill_contracts.rs"]
+mod skill_contracts;
diff --git a/src/crates/execution/agent-runtime/tests/agent_registry_contracts.rs b/src/crates/execution/agent-runtime/tests/agent_definition_contracts/agent_registry_contracts.rs
similarity index 100%
rename from src/crates/execution/agent-runtime/tests/agent_registry_contracts.rs
rename to src/crates/execution/agent-runtime/tests/agent_definition_contracts/agent_registry_contracts.rs
diff --git a/src/crates/execution/agent-runtime/tests/context_profile.rs b/src/crates/execution/agent-runtime/tests/agent_definition_contracts/context_profile.rs
similarity index 100%
rename from src/crates/execution/agent-runtime/tests/context_profile.rs
rename to src/crates/execution/agent-runtime/tests/agent_definition_contracts/context_profile.rs
diff --git a/src/crates/execution/agent-runtime/tests/custom_agent_mode_contracts.rs b/src/crates/execution/agent-runtime/tests/agent_definition_contracts/custom_agent_mode_contracts.rs
similarity index 100%
rename from src/crates/execution/agent-runtime/tests/custom_agent_mode_contracts.rs
rename to src/crates/execution/agent-runtime/tests/agent_definition_contracts/custom_agent_mode_contracts.rs
diff --git a/src/crates/execution/agent-runtime/tests/custom_subagent_contracts.rs b/src/crates/execution/agent-runtime/tests/agent_definition_contracts/custom_subagent_contracts.rs
similarity index 100%
rename from src/crates/execution/agent-runtime/tests/custom_subagent_contracts.rs
rename to src/crates/execution/agent-runtime/tests/agent_definition_contracts/custom_subagent_contracts.rs
diff --git a/src/crates/execution/agent-runtime/tests/custom_subagent_discovery_contracts.rs b/src/crates/execution/agent-runtime/tests/agent_definition_contracts/custom_subagent_discovery_contracts.rs
similarity index 100%
rename from src/crates/execution/agent-runtime/tests/custom_subagent_discovery_contracts.rs
rename to src/crates/execution/agent-runtime/tests/agent_definition_contracts/custom_subagent_discovery_contracts.rs
diff --git a/src/crates/execution/agent-runtime/tests/prompt_cache_contracts.rs b/src/crates/execution/agent-runtime/tests/agent_definition_contracts/prompt_cache_contracts.rs
similarity index 100%
rename from src/crates/execution/agent-runtime/tests/prompt_cache_contracts.rs
rename to src/crates/execution/agent-runtime/tests/agent_definition_contracts/prompt_cache_contracts.rs
diff --git a/src/crates/execution/agent-runtime/tests/prompt_contracts.rs b/src/crates/execution/agent-runtime/tests/agent_definition_contracts/prompt_contracts.rs
similarity index 100%
rename from src/crates/execution/agent-runtime/tests/prompt_contracts.rs
rename to src/crates/execution/agent-runtime/tests/agent_definition_contracts/prompt_contracts.rs
diff --git a/src/crates/execution/agent-runtime/tests/skill_contracts.rs b/src/crates/execution/agent-runtime/tests/agent_definition_contracts/skill_contracts.rs
similarity index 100%
rename from src/crates/execution/agent-runtime/tests/skill_contracts.rs
rename to src/crates/execution/agent-runtime/tests/agent_definition_contracts/skill_contracts.rs
diff --git a/src/crates/execution/agent-runtime/tests/agent_interaction_contracts.rs b/src/crates/execution/agent-runtime/tests/agent_interaction_contracts.rs
new file mode 100644
index 0000000000..4ff9513d38
--- /dev/null
+++ b/src/crates/execution/agent-runtime/tests/agent_interaction_contracts.rs
@@ -0,0 +1,14 @@
+//! Permission, question, and hook interaction contracts.
+
+#[path = "agent_interaction_contracts/native_hook_payload_contracts.rs"]
+mod native_hook_payload_contracts;
+#[path = "agent_interaction_contracts/native_hook_settings_contracts.rs"]
+mod native_hook_settings_contracts;
+#[path = "agent_interaction_contracts/permission_contracts.rs"]
+mod permission_contracts;
+#[path = "agent_interaction_contracts/post_call_hook_contracts.rs"]
+mod post_call_hook_contracts;
+#[path = "agent_interaction_contracts/post_call_hook_execution_contracts.rs"]
+mod post_call_hook_execution_contracts;
+#[path = "agent_interaction_contracts/user_question_tool_contracts.rs"]
+mod user_question_tool_contracts;
diff --git a/src/crates/execution/agent-runtime/tests/native_hook_payload_contracts.rs b/src/crates/execution/agent-runtime/tests/agent_interaction_contracts/native_hook_payload_contracts.rs
similarity index 100%
rename from src/crates/execution/agent-runtime/tests/native_hook_payload_contracts.rs
rename to src/crates/execution/agent-runtime/tests/agent_interaction_contracts/native_hook_payload_contracts.rs
diff --git a/src/crates/execution/agent-runtime/tests/native_hook_settings_contracts.rs b/src/crates/execution/agent-runtime/tests/agent_interaction_contracts/native_hook_settings_contracts.rs
similarity index 100%
rename from src/crates/execution/agent-runtime/tests/native_hook_settings_contracts.rs
rename to src/crates/execution/agent-runtime/tests/agent_interaction_contracts/native_hook_settings_contracts.rs
diff --git a/src/crates/execution/agent-runtime/tests/permission_contracts.rs b/src/crates/execution/agent-runtime/tests/agent_interaction_contracts/permission_contracts.rs
similarity index 100%
rename from src/crates/execution/agent-runtime/tests/permission_contracts.rs
rename to src/crates/execution/agent-runtime/tests/agent_interaction_contracts/permission_contracts.rs
diff --git a/src/crates/execution/agent-runtime/tests/post_call_hook_contracts.rs b/src/crates/execution/agent-runtime/tests/agent_interaction_contracts/post_call_hook_contracts.rs
similarity index 100%
rename from src/crates/execution/agent-runtime/tests/post_call_hook_contracts.rs
rename to src/crates/execution/agent-runtime/tests/agent_interaction_contracts/post_call_hook_contracts.rs
diff --git a/src/crates/execution/agent-runtime/tests/post_call_hook_execution_contracts.rs b/src/crates/execution/agent-runtime/tests/agent_interaction_contracts/post_call_hook_execution_contracts.rs
similarity index 100%
rename from src/crates/execution/agent-runtime/tests/post_call_hook_execution_contracts.rs
rename to src/crates/execution/agent-runtime/tests/agent_interaction_contracts/post_call_hook_execution_contracts.rs
diff --git a/src/crates/execution/agent-runtime/tests/user_question_tool_contracts.rs b/src/crates/execution/agent-runtime/tests/agent_interaction_contracts/user_question_tool_contracts.rs
similarity index 100%
rename from src/crates/execution/agent-runtime/tests/user_question_tool_contracts.rs
rename to src/crates/execution/agent-runtime/tests/agent_interaction_contracts/user_question_tool_contracts.rs
diff --git a/src/crates/execution/agent-runtime/tests/agent_long_horizon_contracts.rs b/src/crates/execution/agent-runtime/tests/agent_long_horizon_contracts.rs
new file mode 100644
index 0000000000..dec83990f2
--- /dev/null
+++ b/src/crates/execution/agent-runtime/tests/agent_long_horizon_contracts.rs
@@ -0,0 +1,10 @@
+//! DeepResearch, DeepReview, and long-running thread-goal contracts.
+
+#[path = "agent_long_horizon_contracts/deep_research_contracts.rs"]
+mod deep_research_contracts;
+#[path = "agent_long_horizon_contracts/deep_review_policy_contracts.rs"]
+mod deep_review_policy_contracts;
+#[path = "agent_long_horizon_contracts/thread_goal_contracts.rs"]
+mod thread_goal_contracts;
+#[path = "agent_long_horizon_contracts/thread_goal_tool_handler_contracts.rs"]
+mod thread_goal_tool_handler_contracts;
diff --git a/src/crates/execution/agent-runtime/tests/deep_research_contracts.rs b/src/crates/execution/agent-runtime/tests/agent_long_horizon_contracts/deep_research_contracts.rs
similarity index 100%
rename from src/crates/execution/agent-runtime/tests/deep_research_contracts.rs
rename to src/crates/execution/agent-runtime/tests/agent_long_horizon_contracts/deep_research_contracts.rs
diff --git a/src/crates/execution/agent-runtime/tests/deep_review_policy_contracts.rs b/src/crates/execution/agent-runtime/tests/agent_long_horizon_contracts/deep_review_policy_contracts.rs
similarity index 100%
rename from src/crates/execution/agent-runtime/tests/deep_review_policy_contracts.rs
rename to src/crates/execution/agent-runtime/tests/agent_long_horizon_contracts/deep_review_policy_contracts.rs
diff --git a/src/crates/execution/agent-runtime/tests/thread_goal_contracts.rs b/src/crates/execution/agent-runtime/tests/agent_long_horizon_contracts/thread_goal_contracts.rs
similarity index 100%
rename from src/crates/execution/agent-runtime/tests/thread_goal_contracts.rs
rename to src/crates/execution/agent-runtime/tests/agent_long_horizon_contracts/thread_goal_contracts.rs
diff --git a/src/crates/execution/agent-runtime/tests/thread_goal_tool_handler_contracts.rs b/src/crates/execution/agent-runtime/tests/agent_long_horizon_contracts/thread_goal_tool_handler_contracts.rs
similarity index 100%
rename from src/crates/execution/agent-runtime/tests/thread_goal_tool_handler_contracts.rs
rename to src/crates/execution/agent-runtime/tests/agent_long_horizon_contracts/thread_goal_tool_handler_contracts.rs
diff --git a/src/crates/execution/agent-runtime/tests/agent_session_contracts.rs b/src/crates/execution/agent-runtime/tests/agent_session_contracts.rs
new file mode 100644
index 0000000000..9cad89f6dc
--- /dev/null
+++ b/src/crates/execution/agent-runtime/tests/agent_session_contracts.rs
@@ -0,0 +1,20 @@
+//! Session, scheduler, event, SDK, and workspace-reference contracts.
+
+#[path = "agent_session_contracts/events_contracts.rs"]
+mod events_contracts;
+#[path = "agent_session_contracts/interaction_response_contracts.rs"]
+mod interaction_response_contracts;
+#[path = "agent_session_contracts/scheduled_job_contracts.rs"]
+mod scheduled_job_contracts;
+#[path = "agent_session_contracts/scheduler_contracts.rs"]
+mod scheduler_contracts;
+#[path = "agent_session_contracts/sdk_smoke.rs"]
+mod sdk_smoke;
+#[path = "agent_session_contracts/session_control_contracts.rs"]
+mod session_control_contracts;
+#[path = "agent_session_contracts/session_model_sdk.rs"]
+mod session_model_sdk;
+#[path = "agent_session_contracts/session_operation_ports.rs"]
+mod session_operation_ports;
+#[path = "agent_session_contracts/workspace_reference_ports.rs"]
+mod workspace_reference_ports;
diff --git a/src/crates/execution/agent-runtime/tests/events_contracts.rs b/src/crates/execution/agent-runtime/tests/agent_session_contracts/events_contracts.rs
similarity index 100%
rename from src/crates/execution/agent-runtime/tests/events_contracts.rs
rename to src/crates/execution/agent-runtime/tests/agent_session_contracts/events_contracts.rs
diff --git a/src/crates/execution/agent-runtime/tests/interaction_response_contracts.rs b/src/crates/execution/agent-runtime/tests/agent_session_contracts/interaction_response_contracts.rs
similarity index 100%
rename from src/crates/execution/agent-runtime/tests/interaction_response_contracts.rs
rename to src/crates/execution/agent-runtime/tests/agent_session_contracts/interaction_response_contracts.rs
diff --git a/src/crates/execution/agent-runtime/tests/scheduled_job_contracts.rs b/src/crates/execution/agent-runtime/tests/agent_session_contracts/scheduled_job_contracts.rs
similarity index 100%
rename from src/crates/execution/agent-runtime/tests/scheduled_job_contracts.rs
rename to src/crates/execution/agent-runtime/tests/agent_session_contracts/scheduled_job_contracts.rs
diff --git a/src/crates/execution/agent-runtime/tests/scheduler_contracts.rs b/src/crates/execution/agent-runtime/tests/agent_session_contracts/scheduler_contracts.rs
similarity index 100%
rename from src/crates/execution/agent-runtime/tests/scheduler_contracts.rs
rename to src/crates/execution/agent-runtime/tests/agent_session_contracts/scheduler_contracts.rs
diff --git a/src/crates/execution/agent-runtime/tests/sdk_smoke.rs b/src/crates/execution/agent-runtime/tests/agent_session_contracts/sdk_smoke.rs
similarity index 100%
rename from src/crates/execution/agent-runtime/tests/sdk_smoke.rs
rename to src/crates/execution/agent-runtime/tests/agent_session_contracts/sdk_smoke.rs
diff --git a/src/crates/execution/agent-runtime/tests/session_control_contracts.rs b/src/crates/execution/agent-runtime/tests/agent_session_contracts/session_control_contracts.rs
similarity index 100%
rename from src/crates/execution/agent-runtime/tests/session_control_contracts.rs
rename to src/crates/execution/agent-runtime/tests/agent_session_contracts/session_control_contracts.rs
diff --git a/src/crates/execution/agent-runtime/tests/session_model_sdk.rs b/src/crates/execution/agent-runtime/tests/agent_session_contracts/session_model_sdk.rs
similarity index 100%
rename from src/crates/execution/agent-runtime/tests/session_model_sdk.rs
rename to src/crates/execution/agent-runtime/tests/agent_session_contracts/session_model_sdk.rs
diff --git a/src/crates/execution/agent-runtime/tests/session_operation_ports.rs b/src/crates/execution/agent-runtime/tests/agent_session_contracts/session_operation_ports.rs
similarity index 100%
rename from src/crates/execution/agent-runtime/tests/session_operation_ports.rs
rename to src/crates/execution/agent-runtime/tests/agent_session_contracts/session_operation_ports.rs
diff --git a/src/crates/execution/agent-runtime/tests/workspace_reference_ports.rs b/src/crates/execution/agent-runtime/tests/agent_session_contracts/workspace_reference_ports.rs
similarity index 100%
rename from src/crates/execution/agent-runtime/tests/workspace_reference_ports.rs
rename to src/crates/execution/agent-runtime/tests/agent_session_contracts/workspace_reference_ports.rs