fix(docs): correct VPC endpoint cost to ~$102/mo and clarify session timeouts

VPC endpoint cost was ~$50/mo (1 AZ math), actual is ~$102/mo
(7 endpoints x 2 AZs x $0.01/hr x 730 hrs). Update baseline totals
from ~$85-95 to ~$140-150 in COST_MODEL.md and DEPLOYMENT_GUIDE.md.

Clarify the two distinct timeout limits: AgentCore 8-hour service
limit vs orchestrator 9-hour executionTimeout.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: scottschreckengaust

docs/design/COST_MODEL.md

@@ -11,16 +11,16 @@ These costs are incurred regardless of task volume:
 | Component | Estimated cost | Notes |
 |---|---|---|
 | NAT Gateway (1×) | ~$32/month | Fixed hourly cost + data processing. Single AZ (see [COMPUTE.md  - Network architecture](./COMPUTE.md)). |
-| VPC Interface Endpoints (7×) | ~$50/month | $0.01/hr per endpoint per AZ. |
+| VPC Interface Endpoints (7×, 2 AZs) | ~$102/month | $0.01/hr × 7 endpoints × 2 AZs × 730 hrs. |
 | VPC Flow Logs | ~$3/month | CloudWatch ingestion. |
 | DynamoDB (on-demand, idle) | ~$0/month | Pay-per-request; no cost when idle. |
 | CloudWatch Logs retention | ~$1–5/month | Depends on log volume. 90-day retention. |
 | API Gateway (idle) | ~$0/month | Pay-per-request. |
-| **Total baseline** | **~$85–95/month** | |
+| **Total baseline** | **~$140–150/month** | |
 
 ### Scale-to-zero characteristics
 
-Most platform components are fully serverless and incur zero cost when idle: DynamoDB (PAY_PER_REQUEST), Lambda, API Gateway, ECS Fargate (cluster is free, when enabled), AgentCore Runtime (per-session), Bedrock (per-token), and Cognito (free tier). The always-on cost floor (~$85–95/month) is dominated by VPC networking infrastructure (NAT Gateway + 7 interface endpoints) which is required for private subnet connectivity to AWS services and GitHub. See the [Deployment guide](../guides/DEPLOYMENT_GUIDE.md) for the full scale-to-zero breakdown.
+Most platform components are fully serverless and incur zero cost when idle: DynamoDB (PAY_PER_REQUEST), Lambda, API Gateway, ECS Fargate (cluster is free, when enabled), AgentCore Runtime (per-session), Bedrock (per-token), and Cognito (free tier). The always-on cost floor (~$140–150/month) is dominated by VPC networking infrastructure (NAT Gateway + 7 interface endpoints across 2 AZs) which is required for private subnet connectivity to AWS services and GitHub. See the [Deployment guide](../guides/DEPLOYMENT_GUIDE.md) for the full scale-to-zero breakdown.
 
 ## Per-task variable costs
 
@@ -47,16 +47,16 @@ Assuming a typical task: 1–2 hours, Claude Sonnet, ~100K input tokens, ~20K ou
 | Model choice | 5–10× between Haiku and Opus | Default to Claude Sonnet; allow per-repo override. |
 | Turn count | Linear with turns | `max_turns` cap (default 100, configurable 1–500). |
 | Cost budget | Hard stop at budget | `max_budget_usd` cap (configurable $0.01–$100). Agent stops when budget is reached regardless of remaining turns. |
-| Task duration | Sub-linear (compute is cheap; tokens dominate) | 8-hour max session timeout. |
+| Task duration | Sub-linear (compute is cheap; tokens dominate) | AgentCore: 8-hour service limit; orchestrator: 9-hour `executionTimeout`. |
 | Prompt caching | 50–90% token cost reduction | Enable by default; cache system prompts and repo context. |
 | Concurrency | Linear with parallel tasks | Per-user and system-wide concurrency limits. |
 
 ## Cost at scale
 
 | Scale | Tasks/month | Estimated monthly cost (infra + tasks) |
 |---|---|---|
-| Low (1 developer) | 30–60 | $150–500 |
-| Medium (small team) | 200–500 | $500–3,000 |
+| Low (1 developer) | 30–60 | $200–550 |
+| Medium (small team) | 200–500 | $550–3,000 |
 | High (org-wide) | 2,000–5,000 | $5,000–30,000 |
 
 These estimates assume Claude Sonnet with prompt caching enabled and average task complexity.

docs/guides/DEPLOYMENT_GUIDE.md

@@ -13,7 +13,7 @@ ABCA deploys as a **single CDK stack** (`backgroundagent-dev`) containing all pl
 | **Orchestration** | Durable Lambda (checkpoint/replay) | Same durable Lambda via `ComputeStrategy` |
 | **Agent mode** | FastAPI server (HTTP invocation) | Batch (run-to-completion) |
 | **Startup** | ~10s (warm MicroVM) | ~60-180s (Fargate cold start) |
-| **Max duration** | 8 hours (AgentCore session) | Limited by orchestrator timeout (9 hours) |
+| **Max duration** | 8 hours (AgentCore service limit) | 9 hours (orchestrator `executionTimeout`) |
 
 Both backends are orchestrated by the same durable Lambda function. The `ComputeStrategy` interface abstracts `startSession()`, `pollSession()`, and `stopSession()` -- the ECS strategy calls `ecs:RunTask` / `ecs:DescribeTasks` / `ecs:StopTask` directly from the Lambda. No Step Functions are used.
 
@@ -39,15 +39,15 @@ ECS Fargate is currently **opt-in** -- the `EcsAgentCluster` construct is presen
 | Component | Est. Monthly Idle Cost | Why |
 |-----------|----------------------|-----|
 | NAT Gateway (1x) | ~$32 | $0.045/hr fixed charge |
-| VPC Interface Endpoints (7x, 2 AZs) | ~$50 | $0.01/hr per endpoint per AZ |
+| VPC Interface Endpoints (7x, 2 AZs) | ~$102 | $0.01/hr × 7 endpoints × 2 AZs × 730 hrs |
 | WAF v2 Web ACL | ~$5 | Base monthly charge |
 | CloudWatch Dashboard | ~$3 | Per-dashboard charge |
 | Secrets Manager (1+ secrets) | ~$0.40/secret | Per-secret monthly |
 | CloudWatch Alarms | ~$0.10/alarm | Per standard alarm |
 | CloudWatch Logs retention | ~$1-5 | Storage for retained logs |
-| **Total always-on baseline** | **~$85-95/month** | |
+| **Total always-on baseline** | **~$140-150/month** | |
 
-The dominant idle cost is VPC networking: 7 interface endpoints (~$50/month) plus the NAT Gateway (~$32/month).
+The dominant idle cost is VPC networking: 7 interface endpoints across 2 AZs (~$102/month) plus the NAT Gateway (~$32/month).
 
 For the full cost model including per-task costs, see [COST_MODEL.md](../design/COST_MODEL.md).
 
@@ -75,7 +75,7 @@ For the full cost model including per-task costs, see [COST_MODEL.md](../design/
 |---------|---------|---------------|
 | VPC (public + private subnets, 2 AZs) | All compute | N/A (no direct cost) |
 | NAT Gateway (1x) | Private subnet internet egress | **No** (~$32/mo) |
-| VPC Interface Endpoints (7x) | AWS service connectivity from private subnets | **No** (~$50/mo) |
+| VPC Interface Endpoints (7x, 2 AZs) | AWS service connectivity from private subnets | **No** (~$102/mo) |
 | VPC Gateway Endpoints (2x: S3, DynamoDB) | S3 and DynamoDB connectivity | Yes (free) |
 | Security Groups | HTTPS-only egress | N/A |
 | Route 53 Resolver DNS Firewall | Domain allowlisting for agent egress | Minimal |

docs/src/content/docs/architecture/Cost-model.md

@@ -15,16 +15,16 @@ These costs are incurred regardless of task volume:
 | Component | Estimated cost | Notes |
 |---|---|---|
 | NAT Gateway (1×) | ~$32/month | Fixed hourly cost + data processing. Single AZ (see [COMPUTE.md  - Network architecture](/architecture/compute)). |
-| VPC Interface Endpoints (7×) | ~$50/month | $0.01/hr per endpoint per AZ. |
+| VPC Interface Endpoints (7×, 2 AZs) | ~$102/month | $0.01/hr × 7 endpoints × 2 AZs × 730 hrs. |
 | VPC Flow Logs | ~$3/month | CloudWatch ingestion. |
 | DynamoDB (on-demand, idle) | ~$0/month | Pay-per-request; no cost when idle. |
 | CloudWatch Logs retention | ~$1–5/month | Depends on log volume. 90-day retention. |
 | API Gateway (idle) | ~$0/month | Pay-per-request. |
-| **Total baseline** | **~$85–95/month** | |
+| **Total baseline** | **~$140–150/month** | |
 
 ### Scale-to-zero characteristics
 
-Most platform components are fully serverless and incur zero cost when idle: DynamoDB (PAY_PER_REQUEST), Lambda, API Gateway, ECS Fargate (cluster is free, when enabled), AgentCore Runtime (per-session), Bedrock (per-token), and Cognito (free tier). The always-on cost floor (~$85–95/month) is dominated by VPC networking infrastructure (NAT Gateway + 7 interface endpoints) which is required for private subnet connectivity to AWS services and GitHub. See the [Deployment guide](/getting-started/deployment-guide) for the full scale-to-zero breakdown.
+Most platform components are fully serverless and incur zero cost when idle: DynamoDB (PAY_PER_REQUEST), Lambda, API Gateway, ECS Fargate (cluster is free, when enabled), AgentCore Runtime (per-session), Bedrock (per-token), and Cognito (free tier). The always-on cost floor (~$140–150/month) is dominated by VPC networking infrastructure (NAT Gateway + 7 interface endpoints across 2 AZs) which is required for private subnet connectivity to AWS services and GitHub. See the [Deployment guide](/getting-started/deployment-guide) for the full scale-to-zero breakdown.
 
 ## Per-task variable costs
 
@@ -51,16 +51,16 @@ Assuming a typical task: 1–2 hours, Claude Sonnet, ~100K input tokens, ~20K ou
 | Model choice | 5–10× between Haiku and Opus | Default to Claude Sonnet; allow per-repo override. |
 | Turn count | Linear with turns | `max_turns` cap (default 100, configurable 1–500). |
 | Cost budget | Hard stop at budget | `max_budget_usd` cap (configurable $0.01–$100). Agent stops when budget is reached regardless of remaining turns. |
-| Task duration | Sub-linear (compute is cheap; tokens dominate) | 8-hour max session timeout. |
+| Task duration | Sub-linear (compute is cheap; tokens dominate) | AgentCore: 8-hour service limit; orchestrator: 9-hour `executionTimeout`. |
 | Prompt caching | 50–90% token cost reduction | Enable by default; cache system prompts and repo context. |
 | Concurrency | Linear with parallel tasks | Per-user and system-wide concurrency limits. |
 
 ## Cost at scale
 
 | Scale | Tasks/month | Estimated monthly cost (infra + tasks) |
 |---|---|---|
-| Low (1 developer) | 30–60 | $150–500 |
-| Medium (small team) | 200–500 | $500–3,000 |
+| Low (1 developer) | 30–60 | $200–550 |
+| Medium (small team) | 200–500 | $550–3,000 |
 | High (org-wide) | 2,000–5,000 | $5,000–30,000 |
 
 These estimates assume Claude Sonnet with prompt caching enabled and average task complexity.

docs/src/content/docs/getting-started/Deployment-guide.md

@@ -17,7 +17,7 @@ ABCA deploys as a **single CDK stack** (`backgroundagent-dev`) containing all pl
 | **Orchestration** | Durable Lambda (checkpoint/replay) | Same durable Lambda via `ComputeStrategy` |
 | **Agent mode** | FastAPI server (HTTP invocation) | Batch (run-to-completion) |
 | **Startup** | ~10s (warm MicroVM) | ~60-180s (Fargate cold start) |
-| **Max duration** | 8 hours (AgentCore session) | Limited by orchestrator timeout (9 hours) |
+| **Max duration** | 8 hours (AgentCore service limit) | 9 hours (orchestrator `executionTimeout`) |
 
 Both backends are orchestrated by the same durable Lambda function. The `ComputeStrategy` interface abstracts `startSession()`, `pollSession()`, and `stopSession()` -- the ECS strategy calls `ecs:RunTask` / `ecs:DescribeTasks` / `ecs:StopTask` directly from the Lambda. No Step Functions are used.
 
@@ -43,15 +43,15 @@ ECS Fargate is currently **opt-in** -- the `EcsAgentCluster` construct is presen
 | Component | Est. Monthly Idle Cost | Why |
 |-----------|----------------------|-----|
 | NAT Gateway (1x) | ~$32 | $0.045/hr fixed charge |
-| VPC Interface Endpoints (7x, 2 AZs) | ~$50 | $0.01/hr per endpoint per AZ |
+| VPC Interface Endpoints (7x, 2 AZs) | ~$102 | $0.01/hr × 7 endpoints × 2 AZs × 730 hrs |
 | WAF v2 Web ACL | ~$5 | Base monthly charge |
 | CloudWatch Dashboard | ~$3 | Per-dashboard charge |
 | Secrets Manager (1+ secrets) | ~$0.40/secret | Per-secret monthly |
 | CloudWatch Alarms | ~$0.10/alarm | Per standard alarm |
 | CloudWatch Logs retention | ~$1-5 | Storage for retained logs |
-| **Total always-on baseline** | **~$85-95/month** | |
+| **Total always-on baseline** | **~$140-150/month** | |
 
-The dominant idle cost is VPC networking: 7 interface endpoints (~$50/month) plus the NAT Gateway (~$32/month).
+The dominant idle cost is VPC networking: 7 interface endpoints across 2 AZs (~$102/month) plus the NAT Gateway (~$32/month).
 
 For the full cost model including per-task costs, see [COST_MODEL.md](/architecture/cost-model).
 
@@ -79,7 +79,7 @@ For the full cost model including per-task costs, see [COST_MODEL.md](/architect
 |---------|---------|---------------|
 | VPC (public + private subnets, 2 AZs) | All compute | N/A (no direct cost) |
 | NAT Gateway (1x) | Private subnet internet egress | **No** (~$32/mo) |
-| VPC Interface Endpoints (7x) | AWS service connectivity from private subnets | **No** (~$50/mo) |
+| VPC Interface Endpoints (7x, 2 AZs) | AWS service connectivity from private subnets | **No** (~$102/mo) |
 | VPC Gateway Endpoints (2x: S3, DynamoDB) | S3 and DynamoDB connectivity | Yes (free) |
 | Security Groups | HTTPS-only egress | N/A |
 | Route 53 Resolver DNS Firewall | Domain allowlisting for agent egress | Minimal |