git:20261018.0fac997 to git:20261022.288e4c4
86 added, 20 removed. Audit A to A.
# Managed Agent Server
These instructions apply to this directory and its descendants. They supplement
the [repository AGENTS.md](../../AGENTS.md); its simplicity, design,
self-audit, and PR requirements still apply. When changing another module,
also read the instructions that apply there.
## Scope and References
This is the standalone Spring Boot control plane for the Hosted Harness. Keep
DataWorks and other product-specific integrations outside this module. Preserve
the ownership boundary between control-plane lifecycle state, Runtime Broker
execution bindings, and Hosted Harness execution.
Use the [README](README.md) for setup, authentication, deployment, and test
profiles. Keep detailed procedures there rather than duplicating them here.
## Library Reuse
- Prefer JDK APIs and the declared Apache Commons libraries over new generic
helpers. Use `org.apache.commons.lang3.StringUtils` for null-safe blank checks
and truncation; do not introduce another string utility class or wrappers
that only repeat those operations.
- Use Commons Codec `DigestUtils` for raw SHA-256 operations and
`getSha256Digest()` for incremental digest initialization. Keep streaming
limits, heartbeat checks, and length-prefixed inputs intact. Use `HmacUtils`
for HMAC with a fresh instance per call; preserve signature input bytes,
output encoding, constant-time comparisons, and exception mappings.
- Use `StringUtils.isNumeric` when the existing validation accepts Unicode
digits. Keep ASCII-only protocol checks explicit.
- Preserve UTF-8 encoding, digest prefixes, and the existing JSON
canonicalization rules.
- Preserve domain-specific semantics: title `unicodeBlank` also recognizes
NBSP and BOM, so it is not interchangeable with `StringUtils.isBlank`.
- Reuse fully configured `ObjectMapper` instances and inject existing Spring
components rather than constructing them for each call. Keep protocol JSON
configuration fixed; application-wide mapper settings must not change stored
bytes or digests.
- Declare directly used libraries in this module's POM. Let Spring Boot manage
their versions rather than relying on sibling or storage SDK dependencies.
## Build and Verification
- Use JDK 21 and Maven 3.8.9 or newer. Run the following commands from this
- directory. On a fresh checkout, install the sibling dependencies first:
+ The repository's General workflow delegates Java-only verification to this
+ file. The policy below governs this module's local verification, including
+ invoked skills, subagents, automations and PR follow-ups. Reference this
+ section instead of copying its rules into prompts or monitoring skills such
+ as `babysit-pr`. Changes in other packages still follow their applicable root
+ and module rules, including the root build/typecheck requirement for
+ cross-language changes.
+ ### Local validation scope and budget
+
+ 1. **Select by changed behavior.** Cover the current increment and affected
+ callers, contracts and consumers. A new commit SHA, rebase or review round
+ alone does not require repeating tests; inspect what actually changed.
+ 2. **Reuse valid evidence.** Do not repeat a successful check while its tested
+ source, tests, dependencies, toolchain, generated inputs and runtime
+ configuration remain applicable. Record the command, tested state and
+ outcome. When an input changes, rerun only checks whose evidence it
+ invalidates. Preserve failed attempts; an isolated pass does not clear an
+ unexplained wider failure.
+ 3. **Preflight the environment.** Check required toolchain versions, build
+ prerequisites and service configuration before expensive tests. Fix an
+ environment mismatch before retrying the affected check; a full suite is
+ not an environment diagnostic.
+ 4. **Share one local budget.** Unless the user explicitly sets another budget,
+ spend at most 10 minutes on this module's local verification per requested
+ change, including prerequisite setup, builds, tests and retries. Subagents
+ and review rounds share that budget; a new SHA or continuation message does
+ not reset it. Give commands a timeout bounded by the remaining budget. At
+ exhaustion, stop local checks, clean up task-owned resources and record
+ incomplete checks for CI. Do not silently extend the budget or keep adding
+ checks. This budget does not waive checks required for other changed packages.
+ 5. **Keep full gates in CI.** Local validation prioritizes focused regression
+ and the minimum real integration path. CI owns this module's required full
+ suites and profiles; do not weaken their selectors or coverage guards.
+ Report local passes, failures, skips and CI gaps separately. Until the
+ required CI gates pass on the revision being accepted, say acceptance is
+ pending; if CI does not cover a required check, keep that gap explicit.
+ 6. **Expand only with evidence.** Name a concrete failure, changed shared
+ contract or specific unresolved risk and the additional check that would
+ resolve it. "More confidence" alone is insufficient. Expansion remains
+ within the local budget; otherwise hand it to CI. Self-audit checks the
+ validity of evidence without automatically rerunning it.
+
+ ### Maven and MySQL checks
+
+ Use JDK 21 and Maven 3.8.9 or newer; run Maven from this directory.
+
+ Before testing, check the toolchain and that the installed sibling SDK matches
+ the source being tested. Reuse a valid build; otherwise install it once into
+ the task's isolated Maven repository to avoid another checkout's same-version
+ artifact. Use the same task-specific `-Dmaven.repo.local` setting for installation
+ and subsequent Maven commands (it may be supplied through `MAVEN_ARGS`):
+
```bash
mvn -f ../sdk-java/qwencode/pom.xml -DskipTests -Dgpg.skip=true install
```
- The native CSI conformance tests also load built Core and CLI JavaScript. On a
- fresh worktree, follow the root dependency setup and run the root build once
- to prepare `packages/core/dist` and `packages/cli/dist` before the full Maven
- suite. Maven does not build those prerequisites.
+ Native CSI conformance tests also load built Core and CLI JavaScript. When
+ selecting those tests, check `packages/core/dist` and `packages/cli/dist` and
+ build missing or stale prerequisites under the root dependency instructions.
+ Maven does not build them. Setup and build time count toward the local budget.
- For Java changes, run the affected tests first, then the module verification:
+ For local Java changes, select the affected classes and their consumers:
```bash
- mvn -Dtest=ChangedClassTest test
- mvn verify
+ mvn -Dtest=ChangedClassTest test checkstyle:check
```
- Replace `ChangedClassTest` with the affected test classes. `mvn verify` runs the
- unit/H2 tests, Checkstyle, and the SpotBugs high-confidence gate. Java formatting
- and style follow the existing
+ Replace `ChangedClassTest` with the affected test classes. Do not follow a
+ successful focused run with unconditional local `mvn verify`. CI runs the full
+ unit/H2 suite, Checkstyle and SpotBugs through `mvn verify`; broader local checks
+ need the concrete evidence and remaining budget required by this module's policy.
+ Java formatting and style follow the existing
[Checkstyle rules](../sdk-java/qwencode/qwen-code-checks.xml). Justify any new SpotBugs
exclusion in the PR; do not disable a gate to make verification pass.
- SQL, transaction, concurrency, or recovery changes also require the
- `mysql-integration` profile against a disposable MySQL 8.4 database. Changes to
- Hosted execution or failure recovery require the matching Hosted/fault profiles
- in [pom.xml](pom.xml). Use the README and the repository's
+ SQL, transaction, concurrency, or recovery changes require real MySQL evidence:
+ locally select the affected `mysql-integration` cases against a disposable
+ MySQL 8.4 database within budget, and leave the complete profile to CI. Hosted
+ execution or failure recovery changes similarly need the relevant real-process
+ path locally and the matching full Hosted/fault profiles in CI. Profiles are in
+ [pom.xml](pom.xml). Focused local reports prove only their selected cases; the
+ complete-source-tree report guard belongs to unfiltered full runs. Use the README and the repository's
[Java workflow](../../.github/workflows/sdk-java.yml) for setup and profile
parameters. H2 tests alone do not establish MySQL or process-recovery behavior.
- Report skipped or unavailable checks explicitly.
+ If the required real path cannot run locally within budget, record it as pending
+ CI rather than substituting H2 or claiming acceptance.
- For changes to shared contracts or TypeScript consumers, also run the affected
- consumer tests and the root build/typecheck requirements. Documentation-only
- changes need formatting and reference checks.
+ Before MySQL tests, verify the effective server version, task-owned database
+ URL/credentials and required permissions. Check settings needed by the selected
+ cases: large-object tests require `max_allowed_packet >= 134217728`; the
+ `mysql-integration` Linux CI containers disable native AIO with `--innodb-use-native-aio=0`; the MySQL leg also uses `--skip-log-bin`. Follow the workflow's
+ actual startup settings and record local platform deviations. Multi-fork runs
+ need a distinct MySQL instance per fork to isolate server-wide deadlock counters.
+ Repair an invalid environment before running tests; report unavailable checks
+ and remaining CI work explicitly.
+
+ For shared-contract or TypeScript-consumer changes, also follow the root
+ build/typecheck requirements and run affected consumer tests. The local Maven
+ work follows this module's budget; CI retains the full cross-language gates.
+ Documentation-only changes need formatting and reference checks and do not
+ invalidate unchanged Java test results.
Maven report output under `target/` (javadoc `reports/apidocs`, JaCoCo
`site/jacoco`) contains generated JavaScript that the repository-root ESLint
sweep does not ignore, so a root `npm run lint` fails while those directories
exist. Run `mvn clean` or delete the `target/` directories before running root
checks in the same checkout.
## Code Review
- Preserve each changed route's tenant isolation, actor checks, Workspace
grants, and internal credentials. A tenant header alone must not authorize
protected Workspace or artifact access; preserve the documented loopback and
signed-authentication boundaries.
- Keep admitted operations and recovery decisions durable in SQL. Verify retry
idempotency and writer lease/generation checks across restarts: a stale owner
must not commit durable state or release a newer owner's resources.
- Server and Broker use the
[shared schema baseline](src/main/resources/db/managed-schema/V1__managed_schema.sql).
Keep initialization and validation consistent across Server and Broker. Preserve
refusal of legacy, partial, and foreign catalogs; do not revive archived
migrations or use Flyway repair/history edits to bypass that refusal. Follow
the README's current schema policy rather than assuming an upgrade path.
- Public and WebShell API changes must keep the
[OpenAPI contract](src/main/resources/openapi/managed-agent-public-api.openapi.json),
mapped routes, `SurfaceRegistry`, and contract tests consistent. Run
`ManagedAgentApiContractTest` and `SurfaceRegistryGateTest` for those changes.
Regenerate WebShell types from the repository root with
`npm run generate:managed-agent-api --workspace=packages/web-shell` and verify
affected consumers; update the contract rather than hand-editing generated
types.