Authored by Claude Opus 4.7 (Claude Code). Session continuation from cloud-deployment-trial sprint.

FAIR-band: under-target [15/30] — operator-direction (focus on multi-user cloud deployment, 2-lane coordination; #11942 AC2 is production-scale residual). Live verifier: GPT 17 / Claude 15 over last 30 merged PRs.

Evidence: L1 (262/262 PASS across orchestrator-tree; 3 new AC2 tests covering serialized, bounded-parallel, and gate-timeout paths).

Refs #11942 Related: #11790 (parent MVP), #11952 (sibling AC3+AC4 slice merged earlier this sprint)

Summary

Addresses #11942 AC2 (concurrency-limit gate). AC1 (per-repo jitter/backoff) remains tracked as a separate independent PR.

Reactive concurrencyLimit + concurrencyGateTimeoutMs config on TenantRepoSyncService. Per-repo git/ingest work acquires a semaphore slot before cloneIfMissing/fetch/buildIngestEnvelope/ingestSourceFiles; releases on completion (success or failure). Slot-acquisition timeout surfaces the stable KB_TENANT_REPO_SYNC_CONCURRENCY_GATE_TIMEOUT error code that was pre-declared (as "reserved") in #11952 AC3+AC4 — it now has an active emitter.

Operator-direction continuation: this is the next cloud-deployment-trial-readiness substrate after the 5-PR sprint that just landed. Multi-tenant deployments are at CPU/network-exhaustion risk if all tenantRepos[] entries run their git clone+fetch+ingest in parallel; AC2 caps it conservatively.

Changes

Architectural shift

Before: syncTenantRepos ran for (const repo of repos) { ... } — strictly serial. Single-tenant trial deployments were fine, but multi-tenant runs would either (a) be serialized regardless of network headroom (loses throughput), or (b) need an external orchestration layer to cap parallelism.

After:

• concurrencyLimit_ reactive config slot (default 2) caps simultaneous git/ingest work within one runTask invocation
• concurrencyGateTimeoutMs_ reactive config slot (default 30000) caps slot-wait time
• createConcurrencySemaphore({limit, timeoutMs}) private helper provides the in-memory semaphore primitive (FIFO queue, optional timeout-rejecting with TenantRepoSyncError(KB_TENANT_REPO_SYNC_CONCURRENCY_GATE_TIMEOUT))
• Sequential for...of converted to Promise.all(repos.map(async ...)) with semaphore-guarded entry; per-repo failure isolation contract preserved via try/finally + the existing per-repo catch block

Behavioral expectations

• Default config (concurrencyLimit: 2): up to 2 repos process in parallel. For trial deployments with 1-2 tenants, behavior is identical to pre-AC2. For multi-tenant cloud deployments, this provides automatic conservative parallelism.
• concurrencyLimit: 1: serializes (matches pre-AC2 MVP shape; useful for capacity-constrained deployments).
• concurrencyLimit > 2: higher parallelism for deployments with verified network/CPU headroom.
• concurrencyGateTimeoutMs: 0: disables the timeout (slots wait indefinitely until release).
• Live config reactivity: a fresh semaphore is created per runTask invocation from current reactive config values, so operator edits to concurrencyLimit / concurrencyGateTimeoutMs take effect on the next cycle without daemon restart.

File-level breakdown

• ai/daemons/orchestrator/services/TenantRepoSyncService.mjs

  • Add KB_TENANT_REPO_SYNC_CONCURRENCY_GATE_TIMEOUT to the import block
  • New private createConcurrencySemaphore({limit, timeoutMs}) helper (~45 LOC) implementing async Promise-based semaphore with FIFO queue + optional timeout
  • New concurrencyLimit_: 2 + concurrencyGateTimeoutMs_: 30000 reactive config slots in static config
  • syncTenantRepos per-repo loop: sequential → semaphore-guarded Promise.all
  • JSDoc taxonomy table: KB_TENANT_REPO_SYNC_CONCURRENCY_GATE_TIMEOUT row transitions from "reserved" to active emitter

• test/playwright/unit/ai/daemons/orchestrator/services/TenantRepoSyncService.spec.mjs

  • 3 new tests covering AC2's prescribed paths:
    1. concurrencyLimit=1 serializes (in-flight counter never exceeds 1 with 3 repos)
    2. concurrencyLimit=2 caps parallel at 2 (peak in-flight = 2 with 4 repos)
    3. Gate-timeout surfaces KB_TENANT_REPO_SYNC_CONCURRENCY_GATE_TIMEOUT on queued repo when slot wait exceeds concurrencyGateTimeoutMs
  • afterEach extended to restore reactive config defaults — prevents short-timeout / serial-limit leakage to sibling tests

Deltas from ticket (if any)

None substantive. The implementation matches AC2's prescription:

• Reactive concurrencyLimit config (default 2)
• concurrencyLimit: 1 serializes (current MVP shape preserved when explicitly chosen)
• Per-repo work acquires slot before clone/fetch/envelope/ingest
• Slot released after completion (success or failure) via finally
• Stable KB_TENANT_REPO_SYNC_CONCURRENCY_GATE_TIMEOUT error code (pre-declared in #11952 taxonomy; now has active emitter)
• Tests covering serialized, bounded-parallel, gate-timeout paths

The companion concurrencyGateTimeoutMs reactive config slot is an addition beyond the literal AC2 prescription — operator needs SOME way to tune the timeout, so making it reactive (vs hardcoded) is the natural pattern. The 30s default is implementation-defined; happy to tune if operator has a preferred value.

Refs #11942, not Resolves, because AC1 (per-repo jitter/backoff) remains open as the final residual. That work is a state-machine refactor (per-repo cadence stored in tenant-repo-sync-revisions.json + deterministic jitter via repoSlug + tenantId hash + exponential backoff on failure) — sized as its own PR.

Test Evidence

npm run test-unit -- test/playwright/unit/ai/daemons/orchestrator/

→ 262/262 PASS (6.7s)

The 3 new AC2 tests in particular:

npm run test-unit -- test/playwright/unit/ai/daemons/orchestrator/services/TenantRepoSyncService.spec.mjs

→ 15/15 PASS (12 pre-existing + 3 new). Concurrency tests use sleep-based timing fixtures (setTimeout(resolve, 10ms) per phase) to make the in-flight counter observable; tracking via Math.max(...inFlightLog) proves the cap holds.

Post-Merge Validation

• Operator confirms cloud trial deployment with concurrencyLimit: 2 does not exhibit thundering-herd behavior on first-bootstrap multi-tenant clone
• If specific operator deployment warrants different default, tune via the singleton's reactive config at runtime
• AC1 (jitter/backoff) remains tracked in #11942 as follow-up PR — operator should expect a separate cycle for that residual

Avoided Traps

• Did NOT use external p-limit / similar npm package — added dependency for ~45 LOC of internal-only logic isn't worth it
• Did NOT serialize via for...of + await (the simplest path that satisfies AC2 with concurrencyLimit: 1 only) — operator-deployed multi-tenant case needs actual parallelism
• Did NOT make the semaphore a singleton lifetime (cross-runTask sharing) — per-task-invocation lifetime means live config edits take effect on next cycle without daemon restart
• Did NOT bundle AC1 (jitter/backoff) into this PR — distinct state-machine work; per feedback_substrate_scope_restraint separate ticket per concern

Authority

#11942 was filed by me 2026-05-25 as a follow-up to #11790 cycle-1 review feedback. AC3+AC4 shipped via #11952 earlier this sprint. AC2 is this PR. AC1 is the final remaining residual (per-repo jitter/backoff state machine).

Self-assigned, open lane → impl in same turn per swarm-topology-anchor §AND-discipline, as the next operator-direction-aligned cloud-deployment lane after the 5-PR sprint landed.

Authored by [Claude Opus 4.7] (Claude Code) — Session continuation from cloud-deployment-trial sprint.

Cycle-2 response — close-keyword + config-boundary guard

Both required actions addressed.

Required Action 1 — close-keyword drift fixed

PR body Summary line: Closes #11942 **AC2** → Addresses #11942 **AC2**. The Refs #11942 line at the top remains the only issue reference; AC1 (per-repo jitter/backoff) stays open until its dedicated PR.

Required Action 2 — boundary guards added at d4337b74e

Real defect — the reactive configs accepted any value, producing broken semaphore states:

• concurrencyLimit = 0 → active < 0 always false → never-acquirable semaphore
• concurrencyLimit = 1.5 → active < 1.5 true at 1 → admits 2 simultaneous slots
• concurrencyLimit = NaN/Infinity/'3' → ambiguous comparison semantics
• concurrencyGateTimeoutMs = -100/NaN/Infinity → broken setTimeout behavior

Added Neo class-system beforeSet hooks:

beforeSetConcurrencyLimit(value, oldValue) {
    if (!Number.isInteger(value) || value < 1) return oldValue ?? 2;
    return value;
}

beforeSetConcurrencyGateTimeoutMs(value, oldValue) {
    if (!Number.isFinite(value) || value < 0) return oldValue ?? 30000;
    return value;
}

Note: concurrencyGateTimeoutMs = 0 is preserved as a valid sentinel (no timeout — slots wait indefinitely), as documented in the JSDoc.

New negative-path tests

Two boundary tests added:

1. beforeSetConcurrencyLimit rejects invalid values — [0, -1, 1.5, NaN, Infinity, '3', null, undefined, {}, []] all rejected → fall back to previous valid value. Integers 1 and 10 accepted.
2. beforeSetConcurrencyGateTimeoutMs rejects NaN/Infinity/negative; accepts 0 as no-timeout sentinel — [-1, -100, NaN, Infinity, -Infinity, '5000', null, undefined] all rejected. 0 (sentinel) and 60000 accepted.

Verification

• 17/17 PASS (npm run test-unit -- test/playwright/unit/ai/daemons/orchestrator/services/TenantRepoSyncService.spec.mjs)
• Pushed at d4337b74e. CI re-firing.

Re-requesting review at the new head.

[Claude Opus 4.7]