merge: bring linear-vercel current with aws-samples/main (66f78bc)

The fork's main (isadeks/main) was 64 commits stale, making GitHub report
linear-vercel as '60 behind'. Against real upstream (aws-samples/main),
linear-vercel was only 5 commits behind. Merge those in to be fully current:
- ephemeral stack cleanup script (aws-samples#109)
- dependency upgrade (aws-samples#367)
- ADR governance: in-place refinement (aws-samples#382)
- test-perf: disable Lambda bundling in unit-test synths (aws-samples#366/aws-samples#371)
- jira: reactive token refresh + retry on 401 (aws-samples#370/aws-samples#375)

Clean merge, zero conflicts (linear-vercel's foundation was already current —
merge-base 0e2806a, 2026-06-17).

Author: isadeks

.abca/commands/review_pr.md

@@ -97,6 +97,13 @@ Then apply principal-architect judgment over the diff:
   IDs, cdk-nag clean. Watch for cost and operational footguns.
 - **Tests** — Are unit tests added/updated under the matching `*/test/` tree? Do they cover the
   new behavior and failure paths, not just the happy path?
+- **Test performance (CDK synth)** — New/changed CDK tests must not re-enable Lambda bundling at
+  synth or synthesize the same stack repeatedly. `cdk/` disables bundling globally via
+  `test/setup/disable-bundling.ts` (~15× faster synth); flag any test that turns
+  `aws:cdk:bundling-stacks` back on (only valid via `postCliContext`, not constructor
+  `context` — the env var overwrites the latter) without asserting on a bundled asset, or
+  that calls `new App()` + `Template.fromStack()` per-test instead of once in `beforeAll`.
+  See #366.
 - **Routing** — Changes should land in the right package per the AGENTS.md routing table
   (agent runtime in `agent/`, API/Lambdas in `cdk/`, CLI in `cli/`).
 

AGENTS.md

@@ -45,6 +45,7 @@ Handler entry tests: `cdk/test/handlers/orchestrate-task.test.ts`, `create-task.
 - Adding or editing files in **`docs/design/`** or **`docs/guides/`** without running **`cd docs && node scripts/sync-starlight.mjs`** — CI will reject ("Fail build on mutation") because the Starlight mirror files in `docs/src/content/docs/` are stale. Always commit the regenerated mirrors alongside source changes.
 - Changing **`cdk/.../types.ts`** without updating **`cli/src/types.ts`** — CLI and API drift.
 - Running raw **`jest`/`tsc`/`cdk`** from muscle memory — prefer **`mise //cdk:test`**, **`mise //cdk:compile`**, **`mise //cdk:synth`** (see [Commands you can use](#commands-you-can-use)).
+- **Bundling Lambda assets in CDK unit tests** — `Template.fromStack()` triggers a full synth that bundles every `NodejsFunction` via esbuild (~28s for `AgentStack`). Unit tests assert on CloudFormation structure, not bundled code, so for those assertions it is overhead — plus a smoke-test of Lambda `entry` resolution and handler compilation that unit tests intentionally cede to the `agent/` build (a broken entry path or handler TS error stops surfacing at `Template.fromStack()` and instead fails at real synth/deploy or in the `agent/` build). The `cdk/` Jest config disables it globally via `test/setup/disable-bundling.ts` (sets `aws:cdk:bundling-stacks: []` in `CDK_CONTEXT_JSON`), which a bare `new App()` picks up automatically. This does not stop tests from synthesizing — `Template.fromStack()` still runs a full synth; it only skips the esbuild step. **Do not re-enable bundling** in a test unless you are specifically asserting on the bundled-asset output (hash / S3 key) — and if you must, opt out narrowly via that test's `App` `postCliContext` (e.g. `new App({ postCliContext: { 'aws:cdk:bundling-stacks': ['**'] } })`), not globally. Note that constructor `context` does **not** work for this key: CDK overwrites it with `CDK_CONTEXT_JSON`, so only `postCliContext` (applied last) overrides the global disable. Minimize full-stack synths regardless: synthesize each distinct stack config once in `beforeAll` and assert against the cached `Template`. See #366.
 - **`MISE_EXPERIMENTAL=1`** — required for namespaced tasks like **`mise //cdk:build`** (see [CONTRIBUTING.md](./CONTRIBUTING.md)).
 - **`mise run build`** builds **`//agent:quality`** alongside **`//cdk:build`** (the deployed image bundles **`agent/`**, so agent quality is part of the build) — these run as parallel `depends`, not in a fixed order; agent changes belong in the **`agent/`** tree.
 - **`prek install`** fails if Git **`core.hooksPath`** is set — another hook manager owns hooks; see [CONTRIBUTING.md](./CONTRIBUTING.md).

agent/uv.lock

@@ -108,6 +108,9 @@
     "watchPathIgnorePatterns": [
       "/node_modules/"
     ],
+    "setupFiles": [
+      "<rootDir>/test/setup/disable-bundling.ts"
+    ],
     "setupFilesAfterEnv": [
       "aws-cdk-lib/testhelpers/jest-autoclean"
     ],

cdk/package.json

@@ -66,12 +66,19 @@ function toAdfDocument(message: string): Record<string, unknown> {
   };
 }
 
+/**
+ * Outcome of a single comment POST. We distinguish auth rejection (401/403)
+ * from other failures so the caller can react to the former with a forced
+ * token refresh + retry, and treat the latter as terminal.
+ */
+type PostOutcome = 'ok' | 'auth' | 'error';
+
 async function postComment(
   accessToken: string,
   cloudId: string,
   issueIdOrKey: string,
   message: string,
-): Promise<boolean> {
+): Promise<PostOutcome> {
   // The 3LO token (audience=api.atlassian.com) is only valid against the
   // gateway base scoped by cloudId — see JIRA_API_BASE. Posting to the raw
   // site host (`*.atlassian.net`) would 401. Both path segments are
@@ -92,17 +99,20 @@ async function postComment(
       body: JSON.stringify({ body: toAdfDocument(message) }),
       signal: controller.signal,
     });
-    if (!resp.ok) {
-      logger.warn('Jira feedback REST non-2xx', { status: resp.status, url });
-      return false;
-    }
-    return true;
+    if (resp.ok) return 'ok';
+    // 401/403 are recoverable: the stored access token may be dead despite a
+    // not-yet-reached `expires_at` (server-side revocation, scope re-issue, or
+    // a value cached past its out-of-band rotation). Signal the caller to
+    // force-refresh and retry once. Any other non-2xx is terminal.
+    const outcome: PostOutcome = resp.status === 401 || resp.status === 403 ? 'auth' : 'error';
+    logger.warn('Jira feedback REST non-2xx', { status: resp.status, url, outcome });
+    return outcome;
   } catch (err) {
     logger.warn('Jira feedback request failed', {
       error: err instanceof Error ? err.message : String(err),
       url,
     });
-    return false;
+    return 'error';
   } finally {
     clearTimeout(timer);
   }
@@ -123,14 +133,20 @@ export interface JiraFeedbackContext {
 
 async function resolveTenantToken(
   ctx: JiraFeedbackContext,
+  forceRefresh = false,
 ): Promise<{ accessToken: string } | null> {
   try {
-    const resolved = await resolveJiraOauthToken(ctx.cloudId, ctx.registryTableName);
+    const resolved = await resolveJiraOauthToken(ctx.cloudId, ctx.registryTableName, { forceRefresh });
     if (!resolved) return null;
     return { accessToken: resolved.accessToken };
   } catch (err) {
+    // `force_refresh` discriminates the initial resolve from the post-401
+    // retry resolve: a failure here on the retry is an infra error (DDB/SM),
+    // distinct from "refresh-token revoked", and triage needs to tell them
+    // apart.
     logger.warn('Jira feedback could not resolve OAuth token', {
       jira_cloud_id: ctx.cloudId,
+      force_refresh: forceRefresh,
       error: err instanceof Error ? err.message : String(err),
     });
     return null;
@@ -141,6 +157,17 @@ async function resolveTenantToken(
  * Post a comment onto a Jira issue. Returns true on success, false on any
  * failure (network, auth, REST errors). Never throws — callers proceed
  * regardless.
+ *
+ * Auth resilience: the access token from the resolver can already be stale
+ * (cached within its TTL, or revoked/re-issued server-side before its
+ * advertised `expires_at`). The proactive expiry check can't catch those, so
+ * a 401/403 on the first POST triggers exactly one forced token refresh
+ * (`forceRefresh: true`) and one retry. This is the path that makes feedback
+ * comments — the only operator-visible failure signal — actually land after a
+ * token goes bad, rather than silently 401ing (issue #370). The retry is
+ * bounded at one attempt: a second 401 means the credential is genuinely
+ * unusable (refresh-token revoked, scope removed), so we stop and let the
+ * caller no-op.
  */
 export async function postIssueComment(
   ctx: JiraFeedbackContext,
@@ -149,7 +176,30 @@ export async function postIssueComment(
 ): Promise<boolean> {
   const resolved = await resolveTenantToken(ctx);
   if (!resolved) return false;
-  return postComment(resolved.accessToken, ctx.cloudId, issueIdOrKey, body);
+
+  const outcome = await postComment(resolved.accessToken, ctx.cloudId, issueIdOrKey, body);
+  if (outcome === 'ok') return true;
+  if (outcome === 'error') return false;
+
+  // outcome === 'auth': the stored access token was rejected. Force a refresh
+  // (bypassing the resolver's cache and proactive-expiry short-circuit) and
+  // retry once with the freshly-minted token.
+  logger.info('Jira feedback got auth rejection — forcing token refresh and retrying once', {
+    jira_cloud_id: ctx.cloudId,
+    issue_id_or_key: issueIdOrKey,
+  });
+  const refreshed = await resolveTenantToken(ctx, true);
+  if (!refreshed) return false;
+  // If the refresh handed back the same access token, the retry can only
+  // reproduce the 401 — skip the redundant network call.
+  if (refreshed.accessToken === resolved.accessToken) {
+    logger.warn('Jira feedback refresh returned an unchanged token — not retrying', {
+      jira_cloud_id: ctx.cloudId,
+      issue_id_or_key: issueIdOrKey,
+    });
+    return false;
+  }
+  return (await postComment(refreshed.accessToken, ctx.cloudId, issueIdOrKey, body)) === 'ok';
 }
 
 /**

cdk/src/handlers/shared/jira-feedback.ts

@@ -97,6 +97,21 @@ export interface ResolverOptions {
   readonly dynamoDbClient?: DynamoDBDocumentClient;
   /** Override fetch for token-endpoint refresh in tests. */
   readonly fetchImpl?: typeof fetch;
+  /**
+   * Force a token refresh even when the stored `expires_at` claims the token
+   * is still valid. Used by the reactive-401 retry path: Atlassian can reject
+   * an access token (401) before its advertised expiry — server-side
+   * invalidation, a re-issued token after a scope change, or a token cached
+   * within {@link SECRET_CACHE_TTL_MS} that was rotated out-of-band. The
+   * proactive expiry check can't see those, so on a 401 the caller re-resolves
+   * with `forceRefresh: true` to bypass the in-memory *token* cache and the
+   * expiry short-circuit and mint a guaranteed-fresh token before retrying.
+   *
+   * The registry-row cache is intentionally NOT bypassed: a revoked access
+   * token does not change the row (`site_url`, `oauth_secret_arn`), so forcing
+   * a DDB read on every 401 would add load without changing the outcome.
+   */
+  readonly forceRefresh?: boolean;
 }
 
 interface CacheEntry<T> {
@@ -137,6 +152,10 @@ export interface ResolvedJiraToken {
  * Refreshes silently if the cached token is expiring. Returns null on any
  * failure (registry miss, secret missing, refresh-token revoked) so callers
  * can gracefully no-op rather than blowing up.
+ *
+ * Pass `options.forceRefresh` to mint a guaranteed-fresh token even when the
+ * stored `expires_at` looks valid — see {@link ResolverOptions.forceRefresh}
+ * (the reactive-401 retry path).
  */
 export async function resolveJiraOauthToken(
   cloudId: string,
@@ -146,6 +165,7 @@ export async function resolveJiraOauthToken(
   const region = options.region ?? process.env.AWS_REGION ?? 'us-east-1';
   const ddb = options.dynamoDbClient ?? DynamoDBDocumentClient.from(new DynamoDBClient({ region }));
   const sm = options.secretsManagerClient ?? new SecretsManagerClient({ region });
+  const forceRefresh = options.forceRefresh ?? false;
 
   // ─── Step 1: Registry row ────────────────────────────────────────
   const row = await getRegistryRow(ddb, registryTableName, cloudId);
@@ -162,7 +182,11 @@ export async function resolveJiraOauthToken(
   }
 
   // ─── Step 2: Cached or fresh token JSON ──────────────────────────
-  const cached = tokenCache.get(row.oauth_secret_arn);
+  // `forceRefresh` bypasses the in-memory token cache: the cached access token
+  // is the one a caller just saw 401, so we must re-read the secret (and
+  // refresh below) rather than hand the same dead token back. (The registry
+  // row above still uses its own cache — see ResolverOptions.forceRefresh.)
+  const cached = forceRefresh ? undefined : tokenCache.get(row.oauth_secret_arn);
   let token: StoredOauthToken;
   if (cached && cached.expiresAt > Date.now() && !isTokenExpiring(cached.value.expires_at)) {
     token = cached.value;
@@ -178,8 +202,11 @@ export async function resolveJiraOauthToken(
     token = fetched;
   }
 
-  // ─── Step 3: Refresh if expiring ─────────────────────────────────
-  if (isTokenExpiring(token.expires_at)) {
+  // ─── Step 3: Refresh if expiring (or forced) ─────────────────────
+  // `forceRefresh` refreshes regardless of `expires_at`: a 401 on a
+  // not-yet-expired token means the stored access token is dead despite the
+  // timestamp, so trust the 401 over the clock and rotate.
+  if (forceRefresh || isTokenExpiring(token.expires_at)) {
     const refreshed = await refreshJiraToken(token, sm, row.oauth_secret_arn, options);
     if (!refreshed) {
       return null;