Skip to content

fix: quality audit, dependency upgrade, emulator pin, registry fixes - #1052

Merged
krokoko merged 126 commits into
mainfrom
fix/1051-quality-audit
Nov 19, 2026
Merged

krokoko merged 126 commits into
mainfrom
fix/1051-quality-audit

Conversation

@krokoko

@krokoko krokoko commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Four things on one branch:

  1. Dependency upgrade of every package (cdk, cli, web, docs, the root, the Jira Forge app, the Python agent and its image). It replaces the Dependabot pull request chore(deps): uv: bump the all-python group across 1 directory with 10 updates #1050, and chore(deps): npm: bump the all-npm group across 5 directories with 59 updates #1040, which was closed on 2026-11-18; chore(deps): npm: bump the all-npm group across 2 directories with 64 updates #1058 was opened for npm in its place.
  2. AWS Emulator pin for the integration tier moved from 1.0.481 to 1.0.489, with the README statements that were observed again.
  3. Registry: the defects that could be proven, fixed with tests.
  4. Quality audit of the whole code base: 481 changes. Every change has a concrete case ("this input leads to this wrong result"), the smallest fix that works, and where it changes behaviour a test that was seen failing first.

Updated after the first reviews (2026-11-19). The branch is rebased onto main with the MicroVM approval lifecycle (#904). One commit brings main's new code and this branch's gates together, and the commits after it handle the findings of the two reviews: the blocking secret-redaction regression is fixed in both scanners, and every other finding is fixed, answered or listed with its reason. The comment "The two reviews: what was done with each finding" goes through them one by one; the last area of the list, "Changes after the first reviews of this pull request", explains each of those commits.

The branch has 125 commits. Each covers one area, and its message explains every change of that commit in plain English with its gain. The same text is in the comments of this pull request, one comment per area, so that a change can be discussed where it is explained:

  1. Every change in one line
  2. Agent runtime (Python) (part 1 of 3): what changes and what it gains
  3. Agent runtime (Python) (part 2 of 3): what changes and what it gains
  4. Agent runtime (Python) (part 3 of 3): what changes and what it gains
  5. Task orchestrator, hydration, budgets and memory: what changes and what it gains
  6. Task API: reads, creation, attachments, authorizers: what changes and what it gains
  7. Linear, Jira, Slack and GitHub integrations (part 1 of 2): what changes and what it gains
  8. Linear, Jira, Slack and GitHub integrations (part 2 of 2): what changes and what it gains
  9. Epic orchestration (sub-issues): what changes and what it gains
  10. bgagent CLI (part 1 of 2): what changes and what it gains
  11. bgagent CLI (part 2 of 2): what changes and what it gains
  12. Registry: what changes and what it gains
  13. Follow-up changes in neighbouring files, and documents brought in line (part 1 of 2): what changes and what it gains
  14. Follow-up changes in neighbouring files, and documents brought in line (part 2 of 2): what changes and what it gains
  15. Constructs, quality gates, docs and web console: what changes and what it gains
  16. Changes after the first reviews of this pull request (part 1 of 2): what changes and what it gains
  17. Changes after the first reviews of this pull request (part 2 of 2): what changes and what it gains
Kind Changes What it means
Bug 240 a wrong result, a crash or a missed case, fixed with a test that failed before
Risk 34 a missing check on input, a secret that could reach a log, a write that could be lost
Scale 6 fine for one user, wrong for many: unbounded work, memory or requests
Speed 4 a large slowdown removed
Test 46 risky logic that no test failed on, now pinned by one
Lean 58 code that should not exist or should be smaller: deleted, merged, or replaced by the standard library
Gate 24 a quality gate that checked less than it claimed, or a baseline that moved
Docs 31 a document or comment that said something the code does not do
Also 38 a change that came with one of the above (a correction from a review, a neighbouring fix)

Lines by kind of file:

Files Added Removed
tests and test corpora 215 +25,340 -2,013
product code 209 +7,181 -5,119
lockfiles 3 +3,950 -4,989
tooling and configuration 42 +441 -392
generated (docs mirrors, bootstrap template, snapshots) 26 +207 -148
documents 28 +205 -158
all 523 +37,324 -12,819

Area

  • cdk — infrastructure, handlers, constructs
  • agent — Python runtime / Docker image
  • cli — bgagent client
  • docs — guides or design sources (docs/guides/, docs/design/)
  • tooling — root mise.toml, scripts, CI workflows

Also web (the operator console) and the lockfile of integrations/jira-forge-app. No workflow under .github/workflows/ is changed.

Related

Changes

1. Dependencies

JavaScript and tools (first commit). Every direct dependency of cdk, cli, web, docs, the root and the Jira Forge app moves to its newest release that is at least seven days old: 66 packages, six of them majors (@aws/durable-execution-sdk-js 3, commander 15, js-yaml 5, jsdom 31, react-router 8, eslint-plugin-jsdoc 65). yarn.lock goes from 1441 to 1306 locked versions. 20 of 29 root resolutions and 4 of 5 Forge overrides are gone because the upgrade made them unnecessary. Tool pins: knip 6.45.0, prek 0.5.10, semgrep 1.185.0, osv-scanner 2.7.1, grype 0.121.3, trivy 0.76.2.

Code the new versions needed: js-yaml 5 throws on an empty frontmatter block (the parser keeps the old answer, 4 tests); the bootstrap template is regenerated for aws-cdk 2.1148.0 (version 33, same policies); commander 15 is ES modules only (ts-jest compiles that one package for the CLI suites, and a new test loads the real package from a plain Node process); import order moves in 30 files (eslint-plugin-import-x 4.18); Starlight 0.42 needs five module declarations.

Python agent and image (second and fourth commit). Ten packages: bedrock-agentcore 1.26.0, boto3 1.44.0, claude-agent-sdk 0.2.179, fastapi 0.162.4, mcp 2.3.0 (a major), pygments 2.21.0, pytest 9.2.0, ruff 0.17.4, ty 0.0.100, uvicorn 0.54.0. The image: Claude Code CLI 2.1.319, mise 2026.11.6 at its digest in place of latest, the python:3.13-slim digest of Python 3.13.18, and pip 26.3 (clears four of the five HIGH findings that trivy 0.76.2 reports on the pip of the base image; the fifth is accepted until 2026-12-16 with the reason in the scan configuration).

Code the new versions needed:

  • botocore 1.44 changes the default retry mode from legacy to standard (5 attempts become 3). The agent names legacy on its sessions and clients, so it retries as before; AWS_RETRY_MODE still wins.
  • mcp 2 replaces httpx with httpx2 and renames the result fields. With the old names every Gateway tool result would have read as successful and empty; four tests now use mcp's own client and types.
  • Claude Code 2.1.311 and later fetch model settings from a host the DNS allowlist does not name: the runner sets CLAUDE_CODE_MODEL_CATALOG=off.

Held back, with the reason: typescript 7 (no JavaScript compiler API yet, which ts-jest, typescript-eslint, astro check and ts-node need); cdk-nag 3 (removes NagSuppressions, 69 calls on this branch); the Cedar pair (no cedarpy release on a 4.13 or 4.14 core); claude-agent-sdk 0.2.180 (bundles CLI 2.1.321, whose changelog says mods written in a session turn on without asking in bypass mode; every task runs in bypass mode, so that release waits for a live task that shows how such a mod meets the Cedar hooks); the Python 3.15 base image of #1049 (the image stays on python:3.13-slim at a newer digest: two minor versions of the interpreter are a change of their own, to be made with the agent's lockfile and the emulator tier on that version).

2. AWS Emulator pin

The integration tier (mise run test:integration) runs on emulator build 1.0.489, the newest build the package host served on 2026-11-17. The three suites pass on it with the upgraded dependencies. Five statements of the emulator README were observed again on 1.0.489 and hold (the two agent-registry refusals, the iss claim of a Cognito token, first-login password rotation, the 1,000-object ceiling of a bucket); the rows that were not probed again keep "Recorded on emulator 1.0.481", as the README's procedure allows.

3. Registry

What could be proven is fixed, each with a test; the details are in the registry comment and, for the agent side, in the agent comments.

  • Deleting a stack or switching the registry off. AWS refuses to delete a registry that still holds a record. The custom resource sent the same delete at every poll and timed out after 15 minutes: a stack with a published asset ended in DELETE_FAILED, and a deploy with the registry switched off left the registry and its records in the account. It now deletes the records first, then the registry (two IAM actions added to its roles). Deploy this change once with the registry enabled before you remove the registry or the stack: a stack deployed earlier still runs the old handler. Tested on the emulator, not against AWS.
  • Publish. A create that took more than about 12 seconds left a draft behind that blocked every retry of that version, with a bare gateway error and nothing in the log: the wait was allowed 60 seconds inside a function that is stopped after 15. The publish function now gets 28 seconds, and a slower create returns the 502 that names the record. A conflict returns the registry's own message (for example the hint to delete a corrupt record), a record that AWS refuses as invalid is a 400 with AWS's reason, and a namespace, name or version that is not a string is a 400.
  • Resolving a pin. An exact pin matches only the version as written, in both resolvers (1.0.0-rc.1 also matched 1.0.0-rc.01; the TypeScript resolver could not tell two numeric prerelease identifiers above JavaScript's largest safe integer apart). The Python parser accepts ASCII digits only, as the TypeScript one does. Six cases for these join the two corpora that both languages run.
  • Fewer calls. Resolving a pin, the duplicate check before a publish and show fetch only the records of the asset in question, not every record of its kind and namespace: up to 119 sequential calls fewer per resolved pin in a namespace of 120 records, at every task start that pins an asset.
  • In the agent. Two pins of one MCP server that resolve to different versions fail the task with the reason (one version ran while the task record named two). A task fails when the rule that keeps Linear tools away from the agent removes an MCP server its Blueprint pins (it ran without the server while the record listed it). git stash, rebase and merge work again in a clone with registry MCP servers. A pinned MCP server whose header values are not strings or whose arguments are not a list of strings fails the task before the agent starts (the Claude Code CLI skips such a server: its own claude mcp list reports it as skipped; that the task then ran without it is read in the CLI, not run), and the publish endpoint now refuses such an asset with a 400.
  • Gate. cdk-nag checks again that every registry route uses the Cognito authorizer; a suppression had switched that check off.
  • Emulator README. The emulator's refusal of a second record with the same name is listed as a known difference from AWS (it is why two versions of one asset cannot be tested on the emulator tier).

4. The audit: what to know before merging

What changes for users and operators

What a user, an operator or a contributor can notice. A line marked (deploy) changes the configuration of a deployed resource or the agent image, not only code.

Tasks and the agent

  • A task fails at start, with Cedar's message, when a Blueprint or registry rule errors on a Read, Write, Edit or Bash call.
  • A task on a pull request from a fork fails at pre-flight with PR_FROM_FORK, before a session starts.
  • A task that is only an issue number, and a pull request task, fail in hydration when GitHub does not return the issue or the PR.
  • A task fails at start when two pins of one registry MCP server resolve differently, when the Linear scrub removes a pinned server, or when a pinned server has header values that are not strings or arguments that are not a list of strings.
  • A force push asks for approval also as git push origin x --force, with -f after the branch at the end of the command or of a line or before ;, &, |, > or 2>, and as git push -f whatever follows the flag; rm -fr /path is refused like rm -rf /path.
  • Secrets in the output of built-in tools reach the model and the task events as [REDACTED-...]; a Write or Edit that adds such a marker is refused.
  • On AgentCore and Lambda MicroVM an approval asked late in a session gets a window that fits the time left; under 150 seconds left it is refused.
  • The agent is given the newest 300 comments of an issue, where it got the 30 oldest.
  • On AgentCore and ECS the orchestrator waits about 8.5 hours for an agent at any poll interval: 1020 polls were 85 minutes at 5 s and 85 hours at 300 s.
  • The URL attachments of a task share 30 seconds and count toward its 50 MB limit; over either, the task fails with that reason.
  • The turn number in progress events, bgagent watch and bgagent status counts answers of the model, not each of their messages.
  • New events: step:<name>:start and :succeeded or :failed for the build check, :start for the pull request step, one trajectory event per tool result.
  • A Gateway that never answers the handshake is given up after 20 seconds (was 300); with mcp 2.3.0 requests to it carry baggage and traceparent in _meta.
  • The final answer of a task without a repository is refused only for two phrases about background runs (thirteen before); ScheduleWakeup is locked out.
  • A build that could not run is stored without build_passed (was true); a failed build is no longer taken for one because its log says "not found".
  • The agent asks GitHub about every pull request task whether the pull request comes from a fork (one more GitHub call at setup) and refuses a fork's, whatever its branch is called.
  • A failed repo_config call through the Tool Gateway reaches the model as a failed tool call; it arrived marked as a success.
  • A task without a repository downloads its attachments into a directory of its own, <workspace>/<task id>/.attachments.
  • A connection string is redacted also when its password holds a slash or its user is empty (redis://:password@host), in tool output and in deny reasons. A URL without a password stays readable only when its host has a port and the first @ behind the port begins a path segment (https://host:8443/@scope/pkg).
  • On AgentCore and ECS a failed session_started write no longer starts more sessions (the event is then missing). A failed status read is a missed poll however many fail in a row; only a read that is refused (access denied and the like) ends the orchestration at that poll, as every failed read did on main. The wait no longer ends after ten polls on a HYDRATING read.

API

  • issue_number has to be a positive integer: a number sent as text ("42") gets 400, and null counts as absent.
  • A next_token that cannot be decoded gets 400 "Invalid next_token." on the four list endpoints; the list used to restart at page one.
  • A malformed attachments value, a task_description or deny reason that is not a string, and a webhook or key name that is not a string get 400.
  • initial_approvals (--pre-approve) refuses this_call, tool_type_session and tool_group_session (400); in an approval the last two cover later calls.
  • The pending-approvals list allows a user 60 calls a minute, where it allowed 10.
  • The pending-approvals list (bgagent pending, the console's inbox) leaves out a request whose window has passed (it listed it until DynamoDB deleted the row) and reads past up to 2,000 such rows to find the live ones.
  • confirm-uploads fails the task when the uploads exceed 50 MB together (it stayed PENDING_UPLOADS) or one does not match its declared type.
  • A repeated confirm-uploads gets 200 in every live state (was 409 in three); a replayed Idempotency-Key in PENDING_UPLOADS gets new upload_instructions.
  • updated_at moves when the agent finishes, fails, pauses or resumes a task; it stayed at the time the task started to run.
  • New error titles: "GitHub token rejected" (not retryable), "The platform lost track of this task" and "Build or tests did not pass" (retryable).
  • Pre-flight reports GitHub timeouts, 5xx and 429 answers, and a rate-limited 403 on the repository check, as GITHUB_UNREACHABLE (retryable).
  • Registry publish answers 400 with AWS's reason for an invalid record (was 500), for coordinates that are not strings, and for an MCP server whose header values are not strings or whose arguments are not a list of strings (was accepted).

CLI

  • bgagent watch exits with code 2, not 1, when it gives up on a failing API, as --wait does.
  • bgagent submit refuses .gif and .webp files itself and uploads the files that do not fit into 3 MB of inline data.
  • After a gateway timeout (504) on the confirmation, bgagent submit reads the task for up to 165 s and prints it, or the reason it ended; it confirms again only when the task still waits for its uploads after that, three confirmations at most.
  • bgagent list, webhook list and api-key list follow next_token to further pages until they have --limit entries (20 without it); the task list sends five requests at most.
  • bgagent configure drops the cached login when it points the CLI at another user pool.
  • Prompts of the linear, jira and slack commands read piped answers; at the end of input they fail with "No input provided." and exit code 1.
  • bgagent linear setup (Secrets Manager path) refuses a slug that names another workspace, and stops when it cannot read the workspace registry.
  • bgagent linear add-workspace refuses any registered workspace, remove-workspace takes one whose grant died, app-template --aws-callback-url is gone.
  • A retried bgagent submit uploads each same-named file into its own attachment.
  • A config file that cannot be read or parsed is reported with its path and the reason ("Cannot read the config file ..."); main printed the bare parser error.
  • bgagent linear setup and add-workspace also refuse a slug that is registered to another workspace when Linear reports the slug as the URL key of the workspace just authorized.
  • bgagent linear list-projects exits 1 when a workspace could not be queried, in text and in JSON output.
  • bgagent jira map, bgagent linear onboard-project and bgagent slack onboard-channel keep the date of the first mapping. They read the mapping row first, so an operator policy that allowed only dynamodb:PutItem on that table also needs GetItem.

Linear, Jira, Slack and GitHub

  • Slack: in a channel with a default repository, CI/CD or an other-owner/repo that is not onboarded and has no issue number is text: the default is used.
  • Linear: a comment whose task is refused gets the reason in place of "On it" and a cross for the eyes; a budget refusal names no amounts.
  • Linear: an issue moves to In Review only when the run has a pull request; the agent no longer renews a Linear token it cannot store.
  • Jira: a card that is In Review or In Progress stays there when a pull request opens; a board with another review status needs --status-on-pr.
  • Linear and Atlassian token renewals give up after 10 seconds and the Linear issue search after 5; none had a time limit.
  • A failed Identity vault call fails only that one Linear event, without marking the workspace revoked; a vault token is reused for 60 seconds.
  • Jira: the agent's answer, and the question of a run that stopped to ask, are rendered from Markdown (inline code, bold, fenced code blocks); links and images in that text stay as typed.
  • Jira: a follow-up that completes with a red build names the reason ("Build or tests did not pass"); on an issue outside an orchestration, a follow-up that only answered a question keeps the completed comment with its answer.
  • Jira: with a --status-on-start override a follow-up no longer moves a card back from In Review; outside an orchestration a follow-up takes its status overrides from the project mapping as it is when the comment arrives.
  • Linear: removing a workspace that was set up again while the request ran answers 404 and leaves the new registration and its secret alone.

Epics

  • The sweep leaves the panel of a finished epic alone one hour after its final status; it edited every finished panel on each 10-minute run.
  • The sweep takes back a sub-issue's start claim only after 10 minutes: a start that crashed is picked up 10 to 20 minutes later, not within 10.
  • A re-applied trigger label and @bgagent retry read the current title and text of the sub-issues that wait, failed or were skipped.
  • The row that makes an epic exist is written after all its sub-issue rows, in a request of its own (one more DynamoDB request per seed): a seed that gives up leaves no epic, and re-applying the trigger seeds again.

Console and dashboard

  • The Build Pass Rate and Lint Pass Rate widgets leave out tasks without a verdict (no repository, crashed, build could not run). (deploy)
  • A crashed task records its real duration, cost and turns and emits the metrics event: the dashboard counts it as a failure, budgets include its cost.
  • Five approval metrics without dimensions declare the empty dimension set CloudWatch needs; TimedOutEffectiveTimeout is also written without dimensions.
  • The console shows a labeled Linear issue as "Starting..." for ten minutes at most; the issue picker keeps a repository's issue list for one minute.
  • A click on the console's title goes to the overview inside the app; it loaded the whole page again.

Operations and deployment

  • The registry publish function gets a timeout of 28 seconds (was 15) and waits 20 seconds for a new record (was 60). (deploy)
  • The registry custom resource deletes records before the registry (two new IAM actions); deploy once with the registry enabled before removing it. (deploy)
  • Both ECS task definitions get NUDGES_TABLE_NAME, so bgagent nudge reaches a task on the ECS backend. (deploy)
  • The web ACL stores REDACTED for the Authorization and X-API-Key headers in its sampled requests. (deploy)
  • The agent image changes: Claude Code CLI 2.1.319, mise 2026.11.6 (was latest), a newer python:3.13-slim digest, pip 26.3. (deploy)
  • The agent image switches the requests and urllib3 auto-instrumentation off: the agent's requests to Linear and Atlassian no longer carry baggage (user id and repository; on AgentCore also the session id), traceparent and X-Amzn-Trace-Id. (deploy)
  • Every allowed use of an API key writes the log line "API key authorized"; "Webhook created" names the key that made the webhook.
  • The alarm on skipped team-budget enforcement can fire: BudgetTeamMembershipUnresolved declares the empty dimension set CloudWatch needs.
  • The agent logs a Jira rate limit (429) as WARN JIRA_APP_ACTOR_PROXY_TRANSIENT, no longer as ERROR JIRA_APP_ACTOR_PROXY_REJECTED.
  • A GitHub token refused twice (fanout.github.api_error) and a Slack bot token scheduled for deletion no longer send records to the dead-letter queue.
  • The orchestrator function is bundled without the import.meta.url substitution, which nothing has needed since durable SDK 1.1.6, and runs in strict mode like the other handlers. (deploy)

Contributors (lint, gates, hooks, tests)

  • Coverage floors rise: cdk 93/85/95/93 (statements/branches/functions/lines; was 91/82/94/91), cli 91/85/92/91 (was 83/85/89/83), agent 89 (was 80).
  • In the agent, # pragma: no cover and # pragma: no branch no longer take code out of the coverage floor.
  • Git hooks run the node, gitleaks and semgrep that mise.toml pins, not the machine's own (MISE_ACTIVATE_AGGRESSIVE=1).
  • mise run security:sast prints semgrep's output and fails when semgrep loaded no rule.
  • The console lint fails on a dropped or misused promise (no-floating-promises, no-misused-promises), as cdk and cli do.
  • Nine cdk-nag suppressions that covered no finding are gone: the build reports, for example, a wildcard permission added to the flow-log role.
  • In the agent, bandit no longer skips five checks (B602 among them), ruff applies S106 and S108 to the emulator tests, ty reports deprecated calls.
  • engines.node is ^22.23.4 || ^24.15.0 in the root, cdk, cli and docs; semgrep 1.185.0, prek 0.5.10, knip 6.45.0 and emulator 1.0.489 are new pins.
  • A read-only workflow whose pull request step names no strategy fails validation (rule 4).
  • The lint fails on an explicit any in the CLI, on a built-in Error thrown from a catch without the caught error as its cause in cdk (preserve-caught-error), and on a control character in a regular expression in both; a test in each package fails when a function above the complexity ceiling grows past the value its directive records.
  • mise run security:sast:masking also reports an except (A, B): handler and a try statement with else:, and holds a suppression comment in a workflow, a Dockerfile, a script or a configuration file to a rule id and a reason, as it did in source files.
  • The two secret scanners run the same connection-string cases from contracts/secret-scan-vectors.json; a change of the pattern in one scanner alone fails its suite.

Decisions that are yours to confirm or reverse

Each of these was a choice between two defensible behaviours. The line says which one is in the branch, what it costs, and where to change it.

  1. Emulator pin 1.0.489, not 1.0.490. GitHub listed 1.0.490 on 2026-11-17, but its package answered 403. Moving the pin again is one line and the procedure in scripts/aws-emulator/README.md.
  2. Four upgrades held back (typescript 7, cdk-nag 3, the Cedar pair, claude-agent-sdk 0.2.180) for the reasons in section 1, and two advisories accepted until 2026-12-16 with the reason next to each entry: setuptools as vendored by pip (agent/.trivyignore; the module the advisory names is not in the image) and picomatch (osv-scanner.toml; published on 2026-11-17, no fixed release, build and test tooling only).
  3. The agent no longer renews a Linear token. It could not store the renewed pair (its role only reads the workspace secret), which left Secrets Manager with a used-up refresh token and could take the workspace offline until bgagent linear setup was run again. It now starts without a Linear token when the stored one is about to expire and leaves the renewal to the Lambdas. Cost: such a task (about one in a thousand) gets no eyes reaction and no move to In Progress at its start, and can miss its final mark.
  4. A finished answer is no longer failed over an everyday phrase. The guard that refuses to deliver a placeholder matched 13 phrases, among them "results will follow" and "check back later", and failed tasks whose deliverable was a reply or a status update that says exactly that. It now matches the two phrases of the placeholder that was seen on a live task (_DEFERRAL_MARKERS in agent/src/workflow/deliverers.py). Cost: a final message that only promises results in ordinary words is delivered and the task is COMPLETED.
  5. A task on a pull request from a fork is refused before a session starts (PR_FROM_FORK, a pre-flight failure with a reason of its own). It failed later, in the agent's setup, before. Reverse in cdk/src/handlers/shared/preflight.ts, and in the agent's own check (_refuse_pr_from_fork in agent/src/repo.py), if fork pull requests are meant to be supported.
  6. The agent cannot call ScheduleWakeup (_DISALLOWED_TOOLS in agent/src/runner.py): a one-shot headless task that schedules its own continuation ends with a promise instead of a result.
  7. A task fails at start when a Cedar rule of its policy cannot be evaluated, with Cedar's message. The check at task start now evaluates one call of each kind (a Read, a Write, an Edit, a Bash call); a rule that errors on one of them used to pass it, and then every call it applied to was denied as an engine error. Cost: a task that ran in spite of such a rule now fails at start, for example a read-only task whose Blueprint has a rule that errors on file writes.
  8. A Write or Edit that would add a redaction marker to a file is refused. Secrets in the output of built-in tools are now replaced before the model sees them, so the model can hold a marker where a value was; writing the file back from what it saw put the marker into the pull request in place of the value. The model is told that the real value is still on disk and to change the file around that line; a marker the file already holds may stay. Cost: an edit that adds such a marker as text of its own (a test of the scanner, a sentence about the marker) is refused as well. It is one self-contained check in the hook that runs before a tool call.
  9. .mcp.json of a session is kept out of commits through the clone's own exclude file (.git/info/exclude), not through an index flag as in an earlier commit of this branch: with the flag, git stash, rebase and merge failed in a clone that had registry MCP servers. Where that file does the work, git's hint to use -f is switched off in the clone.
  10. bgagent webhook list, api-key list and list follow the API's page token. A filtered bgagent list therefore sends up to five requests where it sent one, to find tasks behind the first page; five is chosen so that watch bgagent list --status RUNNING every two seconds stays under the WAF limit of 1,000 requests in five minutes (MAX_LIST_REQUESTS in cli/src/commands/list.ts).
  11. Epic sweep: two windows. The sweep stops editing the panel of a finished epic one hour after its final status was recorded (SETTLED_GRACE_MS), and retries a final panel edit that failed for one day, counted from the epic's end or its last re-open (GIVE_BACK_WINDOW_MS). Before, it edited every finished epic's panel every ten minutes for as long as the rows existed.
  12. Jira cards only move forward. An issue that is already In Review or In Progress stays there instead of moving back or sideways, and the fallback by status category is no longer used for it. A card that is In Progress on a board without one of the known review names stays there until --status-on-pr is set.
  13. A deny reason is scanned for secrets on its first 20,000 characters and stored cut to 2,000, as before. An oversized reason could hold the function until its timeout.
  14. Lint rules switched on with existing code fixed, each the owner's to refuse: no-explicit-any in the CLI, preserve-caught-error in cdk (one file keeps an override, see "Found and not changed"), no-control-regex in both with two inline directives that carry a reason, the promise rules in the console, and a test that holds every function above the complexity ceiling to the value its directive records.
  15. Coverage floors sit two points under what the suites measure: cdk 93 / 85 / 95 / 93 (statements, branches, functions, lines; 91 / 82 / 94 / 91 on main), the agent 89 (80), the CLI 91 / 85 / 92 / 91 (83 / 85 / 89 / 83). A pull request that lowers coverage by more than two points now fails the build. # pragma: no cover no longer takes agent code out of the floor.
  16. Removed options and files that nothing used: bgagent linear app-template --aws-callback-url (it printed a redirect URI the CLI never sends), the ENABLE_CLI_TELEMETRY and DEBUG_DRY_RUN_PROMPTS switches of the agent, the logs_url field the agent stored and nothing returned, three .npmignore files with their CODEOWNERS line, and the CLI's unused library entry point.
  17. The agent image keeps trace headers and the correlation baggage out of requests to Linear and Atlassian (OTEL_PYTHON_DISABLED_INSTRUMENTATIONS in agent/Dockerfile, with the list the AWS OpenTelemetry package applies in its agent observability mode). Wherever the image ran outside that mode, the auto-instrumentation of requests put the submitter's user id and the repository (on AgentCore also the session id) into a baggage header of every such request. Cost: on a runtime that does not set that mode, calls made with requests no longer get a client span of their own in the trace. Observed on a local header recorder (34 of 34 requests before, 0 of 34 after), not on a deployed stack.
  18. The pending-approvals list reads 20 pages at most (2,000 rows) for one call (PENDING_MAX_PAGES in cdk/src/handlers/get-pending.ts). The list now leaves out requests whose window has passed and reads on to find the live ones. The bound is there because such rows can be left faster than DynamoDB deletes them, and the console repeats the call every ten seconds. Cost: a live request behind 2,000 expired rows is not listed until DynamoDB has deleted them (it was not listed behind 100 before); it can still be approved or denied by its id, and a warning is logged when the bound is reached.
  19. The secret scanners leave a URL as it is when its password position holds a placeholder and nothing else ({password}, ${DB_PASSWORD}, %s, <password>). Such a line is a template in code or documentation, and with a marker in its place the agent could neither read nor edit it. Cost: a password that has exactly the form of a placeholder is taken for one. The exemption is one constant in each scanner (_NOT_ONLY_A_PLACEHOLDER in agent/src/output_scanner.py, NOT_ONLY_A_PLACEHOLDER in cdk/src/handlers/shared/deny-reason-scanner.ts); without it every such template line is replaced.

Found and not changed

Needs your decision (a patch or a small change is ready)

  • checkRepoOnboarded in repo-config.ts is called only by its own tests; a patch deletes it. That file was left untouched in this pull request, which is also why the lint keeps a preserve-caught-error override for it: one throw in a catch there needs { cause: err }.
  • Trajectory events carry a tool_results list that is always empty; a patch removes it. It changes an emitted event and was not run on the emulator.
  • ApiError.requestId of the CLI is written at 42 places and read nowhere; a patch removes it (open PR feat: event-driven governance (sync + async event rules) (#230) #568 then needs the same change).
  • The notice "ABCA hit your concurrency limit" is not among ABCA's own comment markers, so a Jira site on OAuth hands it to the next task as a human comment. One line; the list is also Linear's trigger guard.
  • A sub-issue of an epic whose agent only asked a question counts as succeeded and its dependents start. A patch treats it as not done; or sub-issues get no question tool. It changes what users see.
  • The Linear, Jira, GitHub and Slack verifiers repeat one constant-time comparison; a patch makes it one function. Signature code: wants a second reviewer.
  • .github/zizmor.yml has two ignore entries that no gate needs; a patch removes them (workflow configuration).
  • .mergify.yml states merge rules that nothing executes (Mergify is not installed). Delete it?
  • Four legs of the security suite find nothing or repeat another gate (retire.js, grype, the masking range scan, bandit at High). Removing a scanner is yours.

Agent runtime

  • A task with a repository on default/agent-v1 (the API's default) or knowledge/web-research-v1 is told it has no repository and ends FAILED deliverable=lost when the agent only answers. Decide: deliver the answer (three lines) or always a pull request.
  • A nudge is read only when the agent ends its answer, not between tool calls as the user guide says; earlier costs a table query per tool call.
  • A repository's own GitHub token (githubTokenSecretArn) serves pre-flight and hydration only; the agent and the screenshot processor use the platform token. The fix changes the agent payload and IAM.
  • A workflow's limits.max_turns is read by nothing: workflows that declare 30 and 40 run with 100. Apply it (lowers a cap) or delete it.
  • Memory never works for a repository with a dot in its name (vercel/next.js). Needs one encoding of the actor id for agent and platform.
  • A build or lint command runs with or without a shell by a list of operators (py_compile src/*.py gets no glob). One mode changes every Blueprint command.
  • Unreachable but planned in the design: the runner's checkpoint and resume, five of its eight step handlers, the policy engine's blueprint_disable (290 lines). Delete or wire.
  • A workflow whose only deliverable is a comment stores 200 characters of the answer and reports success; the fix narrows the validator.
  • On AgentCore and ECS the start step can still start more than one session: when the agent moves the task to RUNNING first, when the answer to the RUNNING write is lost, or when the invocation ends inside the step. feat(compute): add Lambda MicroVM P3 approval lifecycle #904 closed these for MicroVM. Contract.
  • Two refactors of the approval hook were held back for feat(compute): add Lambda MicroVM P3 approval lifecycle #904. It rewrote those lines, the patches no longer apply, and they are not redone here.
  • The 31 run_task tests repeat about 1,300 lines of scaffolding: too large, and open PR feat(agent): add in-pipeline pre-PR isolated sub-agent critic (adversarial review) phase #263 extends the file. Not written: an emulator test for a rejected attachment descriptor.

Orchestrator and API

  • Two overlapping requests with one Idempotency-Key create two tasks. The fix adds a claim row (schema: ask first).
  • POST /v1/webhooks/tasks cannot carry an attachment (no S3 permission; the WAF blocks bodies over 8 KB). Grant and exempt, or refuse them there.
  • The WAF blocks an address after 1,000 requests in five minutes; one bgagent watch sends 250 to 750. The limit is a documented setting.
  • prompt_version is the hash of a constant, equal for every task without prompt overrides. The real fix moves it to the agent (contract).
  • create-webhook rolls back with DeleteSecret, which its role may not call: the secret is orphaned. One IAM action, or reorder the writes.
  • Webhook management routes refuse a console token (403). The fix removes an audience check; a test pins today's rule.
  • On ECS a description or prompt override near 7,000 characters exceeds the 8,192 of RunTask overrides; open PR fix(security): payload bootstrap v2 with signed per-task payload references #1015 rewrites these lines.
  • When the orchestrator ends a task itself, only MicroVM compute is stopped; an ECS task or AgentCore session may run on. feat(compute): add Lambda MicroVM P3 approval lifecycle #904 left that as it was.
  • A replay of an invocation killed during hydration fails the task; the small fix lets a duplicate execution start several sessions.
  • The poll window counts polls: at a 5-second interval a hung ECS container may never time out. Wants a wall-clock deadline.
  • A task confirmed through confirm-uploads counts twice against the concurrency limit (open PR fix(orchestration): exactly-once concurrency seat release #1009), and a slow confirmation gets the gateway's 504.
  • A used-up GitHub quota is reported as insufficient permissions or as "pull request not found or closed".
  • The sanitizer deletes every <word...> token (Promise<void>, <Layout>). Escaping instead changes a documented control.
  • A GitHub token that stays refused shows only as fanout.github.api_error warnings; no alarm watches them.
  • GET /v1/pending has no field that says the list is incomplete; only the function log does. An optional boolean in the response is an API change (three type files, the CLI and the console).

Linear, Jira, Slack, GitHub

  • Three Lambdas renew a Linear token but may only read the secret: the renewed token is lost and the workspace needs linear setup again. Three one-word IAM edits. Also open: a task can be handed a Linear token that expires before the task ends.
  • A Linear delivery retried after its 5-second limit can start a second task (the dedup key holds the timestamp). Needs one captured retry.
  • Re-applying the trigger label during a run starts a second task (Linear, Jira). Refuse, ignore or restart?
  • Linear's reaction swap removes a person's eyes or check mark too, and a failed state change looks like "already there". Needs a live query and seven files.
  • Low confidence, each a small fix: the agent's Linear token lacks Bearer; a Linear PDF is stored without .pdf; Jira events without a timestamp share a dedup key; a stranded task can get two final comments; a Slack DM keeps a dead Cancel button.
  • A file on a Slack mention can never create a task (no bucket, no files:read). Wire it (IAM, re-install) or remove 140 lines.
  • A failed screenshot run is retried twice and can repeat its comment; retryAttempts: 0 adds a stack resource.
  • Merges left: one tenant-registry function (two open PRs mock the module), one attachment-intake module (too large), a copy of isLinearUploadsUrl.
  • A Jira description that arrives as wiki markup (a string in the webhook payload, not ADF) reaches the agent as typed, and its images become no attachments. A converter, or a read of the issue over REST v3 at admission, is more than a fix.
  • A first run on Jira that completes with a red build says "Task completed" while the card stays In Progress and nothing says why. Give it the failure frame an iteration gets (one expression), or keep the comment equal to Linear's and Slack's?
  • A question asked on a pull request whose build is red is still reported as a failed change on Linear and for an iteration on a sub-issue of an epic ("I made the change, but the build/tests didn't pass"); on a standalone Jira iteration it now gets its answer. Decide the rule for the three together.
  • Sub-issues of an epic keep the Jira status names recorded when the epic was seeded; letting them follow a changed mapping needs the reconciler to read the mapping table (an environment variable and a grant).

Epic orchestration

  • The stranded sweep lacks the Jira registry and the Linear vault wiring: it never settles a Jira epic or one of a vault workspace. Needs IAM grants.
  • Labelling an epic starts tasks for sub-issues that are Done or Canceled (Linear, Jira). A product rule for both.
  • The sweep settles an epic as complete while re-stack tasks still run. Needs a marker on the row (schema); smaller races measured in review stay.
  • When the final panel edit lands and the state change after it fails, the parent stays In Progress. A patch (190 lines) needs refitting.
  • The panel says re-applying the label retries; on Jira it does not. Retry there, or word the hint per tracker.
  • Sub-issues added to an epic that exists can still be half-written when the write gives up (a first seed no longer can), and a retried seed can resend old sub-issue text. Both need changes of the store.
  • The Slack orchestration adapter cannot be reached (340 lines, kept by the design); its design document still calls Jira orchestration unreachable.

CLI

  • linear onboard-project maps a repository that is not onboarded (jira map refuses). Five lines, but it supersedes half of open PR fix(jira): validate repo onboarding at map time (#369) #374.
  • linear add-workspace copies 190 lines of setup and has drifted; setup is one 850-line function with the loopback consent three times. Removing a command; a large refactor.
  • On the Identity vault, linear setup <slug> in the wrong workspace only warns, then overwrites that workspace's entry. Needs a forced consent.
  • A Linear workspace whose URL key has under four characters cannot use it as slug.

Registry

  • The Python registry client has no caller and differs from the TypeScript one; ADR-022 keeps it. Delete 700 lines or fix two cases.
  • A pinned MCP server that cannot connect at run time does not fail the task and is recorded as loaded. Fail, or write a warning event?
  • Two upstream reports about the emulator (SKILL parsing, a timestamp format) are not filed: your call.
  • A conflict answer of the publish endpoint passes on AWS's text, which names the registry's bare id (no ARN, account id or request id reaches a publisher). A tested patch that withholds the id is ready, if you want it.

Constructs, gates and docs

  • Hooks exclude 13 files for no reason; a patch exists, open PR feat: update QUICK_START guide with installation steps #780 rewrites the two lines.
  • Eight more cdk-nag suppressions cover no finding; each needs its own look.
  • Console: an iteration shows "Opened the pull request", a task without a repository the stage "Pull request".
  • The console lint has two of the three promise rules of cdk and cli; the third (unbound-method) has four reports there, none a defect, and needs two interface declarations changed.
  • The force-push rule matches the text of a command, one pattern per spelling. The reviewer's proposal, to read the command's words in the hook and hand Cedar a boolean, changes the policy context (a contract of the agent and of the parity corpus): yours to decide.
  • No test runs the approval hook through a live Claude CLI session (the review's test gap): it needs a model call, which this work did not make. The two secret scanners now share their test vectors.
  • Two tests build a stack inside the test (a review nit): left, each stack has a configuration of its own and is built once, for that one test.
  • On main, not changed here: four statements of the deployment and user guides that feat(compute): add Lambda MicroVM P3 approval lifecycle #904 added do not match the code (a resource count of 484 for 482, a cloudwatch_write_failed record that nothing emits, two bundle versions), and agent/scripts/verify_microvm_credentials.py stops with a KeyError before it probes anything.
  • The review asked for the dependency upgrade to go into a pull request of its own. Not done: the split is yours to decide.

Open pull requests that touch the same files

This branch changes 523 files, so it meets work in flight: 23 open pull requests change a file it changes too. Checked with git merge-tree against the head of each of them on 2026-11-19, after the rebase onto main with #904:

Result Pull requests
Merge cleanly with this branch #1011, #1007, #988, #780
Clean with main today, conflict once this is merged #1053 (3 files), #1006 (1 file), #824 (2 files), #263 (1 file)
Already conflict with main; this branch adds to what has to be resolved #1015 (15 files), #1014 (5 files), #1013 (2 files), #1012 (2 files), #1009 (3 files), #1008 (1 file), #1005 (1 file), #991 (5 files), #910 (2 files), #856 (5 files), #679 (5 files), #568 (12 files), #374 (8 files), #218 (1 file), #165 (5 files)
Dependabot #1050 (uv) is replaced by this branch. #1058 (npm, opened when #1040 was closed) changes the same package files and lockfiles and conflicts in them. #1049 (Python 3.15 base image) conflicts in agent/Dockerfile and is not taken

Whichever side is merged second resolves the conflict. Known beyond the textual conflicts:

Verification

Run on the head of this branch after the rebase onto main with #904, on macOS, with AWS credentials removed from the environment and DynamoDB Local on a loopback port for the transaction tests that #904 added (ABCA_DDB_LOCAL_ENDPOINT, as CI sets it):

Gate Result
yarn install --check-files and uv sync --locked, then the lockfiles unchanged
mise run build (agent quality, the cdk, cli, web and docs builds, the Forge tests, drift and file-hygiene checks) every task passes except, in three of four runs on this machine, one cdk test that came with #904 (see below); the tree is as committed afterwards
Unit tests none skipped: agent 3,076 pass; cdk 7,924 in 281 suites, of which the one named below fails in most local builds; cli 1,472 in 80 suites pass; web 237 in 24 files pass
Coverage agent 91.97 % (floor 89); cdk 95.86 / 87.98 / 97.98 / 95.86 for statements, branches, functions and lines (floors 93 / 85 / 95 / 93); cli 93.78 / 87.62 / 94.44 / 93.78 (floors 91 / 85 / 92 / 91); web 90.84 / 82.88 / 91.12 / 93.38 (floors 88 / 80 / 89 / 91, not changed)
mise run test:integration on emulator 1.0.489 passes: cdk 14 tests, cli 7, agent 44
Security scans, each task run on its own: security:secrets, security:deps, security:sast, security:sast:masking, security:grype, security:retire, security:gh-actions and the agent's bandit pass
Per-PR scans: security:secrets:range over the 125 commits of the branch; security:sast:range and security:sast:masking:range against main pass
Pre-commit hooks over all files (prek run --all-files --stage pre-commit) pass
Agent image builds for linux/arm64; the container starts and answers /ping; trivy 0.76.2 with the flags and the ignore file of mise //agent:security:image reports nothing. The scan read the filesystem of a container created from the image (trivy rootfs; 1,265 packages: Debian 13.7, Python, Node, the gh and Rust binaries), not the image itself: the local Docker disk had no room for the export that trivy image makes

The gates were run on the head. The one test that fails in most local builds is cdk/test/scripts/package-microvm-artifact.test.ts, which came with #904 and which this branch does not change: it gives a packaging script 20 seconds, and on this machine every python3 that the script starts goes through a mise shim that takes half a second, so under the load of the parallel build one run of the script exceeds the limit. The file passes when it is run alone (63 seconds here). In CI it takes 11 seconds on this head (9 on main), and the build there passes with all 7,924 cdk tests. Every other test passes in every local run. Only the secret scan reads every commit: a commit in the middle of the branch was not built on its own, and some would not pass (the generated documentation mirrors, for one, are not regenerated with each commit that changes a document: once in a commit of their own before the first reviews, and again after the commits that followed those reviews).

On the first push CodeQL reported one new alert (js/incomplete-multi-character-sanitization, high) in the sanitizer that this branch rewrites for linear time: the replace that removes HTML tags was handed to the stripping loop as a function, so the analysis could not see that it is repeated. The commit refactor(hydration): show static analysis that the tag pass is repeated writes that replace into the loop. What the sanitizer returns is unchanged: the module before and after gave the same text for 400,366 generated inputs, and the check passes on the head.

How the changes were made and checked. Each change comes from a finding with a concrete case. It was implemented with a test that was seen failing first wherever behaviour changes. Every commit was then reviewed by a second agent that had not seen the implementation and whose brief was to refute it: old against new on generated inputs, deliberate breakages of the changed lines against the tests, every sentence of a document against the code. 25 of those reviews found a wrong fix; each was corrected, with a test, before this pull request was opened, and the corrections are folded into the commits they belong to (two stand as commits of their own, because later commits changed the same lines). The other reviews led to stricter tests and to truer wording of the texts you read here.

After the first reviews. The branch was rebased onto main with #904, and one commit brings main's new code and this branch's gates together. Five read-only checks then compared, for the 48 source, test and document files that both sides had changed, what main changed, what the branch changed and what the rebased tree holds (the other eight such files are generated: the lockfile, the bootstrap template and six documentation mirrors, which were regenerated): no line of either side was dropped or doubled, and one real interaction (the re-read before a session start in front of the MicroVM start claim) and a few stale numbers and texts were found and corrected. Every finding of the two reviews was reproduced with a failing test before it was changed, and every commit made for them was reviewed by a second agent in the same way as before. Of the reviews of the eleven commits made for the two reviews, five led to a correction of code (the port rule of the two scanners, the rules for Markdown in a Jira comment, the limit on failed status reads, the lookup of a Linear slug and the force-push patterns), and the reviews of those corrections led to three more changes (a run of asterisks in a Jira comment, the ten-poll rule of the orchestrator's wait, and one more shared case for the port rule of the scanners). The other reviews changed wording only. The corrections are commits of their own, each named in the list with the finding it corrects.

Not verified: nothing was deployed and no AWS call was made. Worth a look on a deployed stack, before or after merging:

  • the registry custom resource's delete path (run on the emulator only) and the publish function's new timeout;
  • that AgentCore Gateway accepts the _meta keys that mcp 2.3.0 adds to the agent's requests;
  • nudges on the ECS backend, the web ACL's redaction of its sampled requests, the two pass-rate widgets and the approval metrics on the dashboard;
  • the Linear, Jira and Slack paths against the live services: they are covered by unit tests with recorded shapes, not by live calls;
  • the agent image in the runtime: the image was built, scanned and started locally only, and the effect of its new OpenTelemetry setting was observed on a local header recorder;
  • the orchestrator function on a deployed stack: its bundle is built without two esbuild options and now runs in strict mode, like the other handlers; both bundles load in Node 22 and 24, and no test of the repository runs a Lambda bundle;
  • Claude Code CLI 2.1.319 on a Lambda MicroVM: main probed the credential refresh that MicroVM workers rely on with 2.1.191 and 2.1.301; in 2.1.319 the code of that cache and of the container-credential path reads the same, but it was not run;
  • the Jira comments on a live Jira site: the rendering of the agent's Markdown was checked against the published document schema, and no comment was posted.

Acknowledgment

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of the project license.

@krokoko
krokoko requested review from a team and backgroundagents as code owners November 18, 2026 12:59
@krokoko

krokoko commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor Author

Every change in one line

Grouped by area and by commit. The comments below explain each line: what was wrong, what changes, the gain and the test.

Agent runtime (Python) (126)

fix(agent): set updated_at when the agent changes a task's status

  • Bug: updated_at shows when the agent finished, failed or paused a task, not when the task started to run
  • Bug: The user guide no longer promises a logs_url field that nothing returned, and the agent stops storing it
  • Bug: The agent log names the AWS error code and message when a status write fails, not just ClientError
  • Risk: Attached files are in the clone's local exclude file, so git add -A, clean -fd and stash -u skip them

fix(agent): fail task start on a Cedar rule that cannot be evaluated

  • Bug: A retry refused after a human denial appears in the task's event stream with the id of the denied rule
  • Bug: A task fails at start, with Cedar's message, when a rule errors on a Read, Write, Edit or Bash call
  • Test: A test fails when any of the five refusals of an unusable policy at task start is removed
  • Test: A test fails when a pre-approval is checked after, not before, the memory of a recent denial
  • Lean (stdlib): The policy decision is a frozen dataclass: 89 lines fewer, and assigning to a field raises an error

fix(agent): correct the secret scanners and the content sanitizer

  • Bug: Tool output such as a git log, a package.json or an npm error is no longer reported as a leaked secret
  • Bug: Temporary AWS key ids (ASIA) are redacted in tool output, longer GitHub tokens in a deny reason
  • Lean (delete): The repeated error handling around a user's nudge is gone: 44 product lines and two lint suppressions
  • Test: An emulator test fails when the nudge reader's DynamoDB filter or its consume-once condition is wrong
  • Risk: The sanitizer removes control characters and direction marks before it looks for injection phrases
  • Test: A test fails when the clarification tool or its question parameter is renamed or its handler breaks
  • Bug: AWS secret keys and URL passwords are redacted from deny reasons, new GitHub App tokens by both scanners

fix(agent): keep session-only .mcp.json edits out of pull requests

  • Bug: Pull requests no longer carry the agent's session-only edit of a tracked .mcp.json
  • Bug: A .mcp.json in a legacy encoding or UTF-16 no longer fails the task; its two identical readers are one
  • Risk: A .mcp.json that starts with a byte-order mark is read: its Linear server is removed, the others kept
  • Bug: A refused connection, timeout or error answer of the Gateway is one warning that names the real cause
  • Bug: A Gateway that never answers the handshake holds a tool call for 20 seconds instead of 300
  • Bug: A 200 answer to a Linear reaction whose body is not a JSON object no longer fails the task
  • Bug: The agent logs a Jira rate limit (HTTP 429) as transient, as the Lambda does, not as a rejected request

fix(agent): gate a force push written with the flag after the branch

  • Lean (delete): Five names in the policy engine that nothing reads are deleted, with two tests: 20 lines fewer
  • Risk: The built-in rule that refuses rm -rf of an absolute path refuses rm -fr as well
  • Bug: A force push asks for approval also when --force follows the branch or -f ends the command

fix(agent): pick the right branch and repository during repo setup

  • Bug: A child task whose predecessor branch was merged and deleted aims its pull request at the default branch
  • Bug: Setup checks out a pull request whose branch is the default branch, and refuses one that comes from a fork
  • Bug: When the GitHub call for the default branch fails, setup reads it from the clone instead of assuming main
  • Risk: In a fork, the agent's gh commands act on the task's repository, not on the parent project
  • Risk: A stacked child finds its base and predecessor branches in the clone, so a failed fetch cannot drop them

fix(agent): harden run_cmd output handling, timeouts and log redaction

  • Bug: Command output with a byte that is not UTF-8 no longer fails a passing build or crashes setup
  • Bug: On a timeout the whole process group of a build or lint command is told to stop, not only the command
  • Bug: The failure summary of a red build keeps the totals line when a count ends in 0, such as '10 failed'
  • Risk: The agent's log redactor replaces the values of its GitHub, Linear and Jira credentials wherever they appear
  • Scale: The agent keeps the last 200,000 output lines of a build or lint command in memory instead of all of them

fix(agent): correct what the pipeline reports when a task ends

  • Bug: A build whose command could not run is recorded without a verdict and shown as NOT RUN, not PASSED
  • Bug: A task stopped at its turn limit records the limit as completed turns (100), not one more (101)
  • Bug: A Linear issue moves to In Review only when the run has a pull request, as the Jira card does
  • Bug: A build killed for lack of memory or disk no longer fails a read-only task such as a review
  • Bug: After a failed push the task reports work that was not delivered, not a commit safe on the branch
  • Bug: Only a dry run prints 'Dry run mode detected.'; the DEBUG_DRY_RUN_PROMPTS switch that did nothing is gone
  • Bug: An agent that notices its task was cancelled replaces the eyes on the Linear issue with a cross

fix(agent): make secret redaction of built-in tool output take effect

  • Bug: An approval wait is limited to the session time that is left, also for a start time with milliseconds
  • Bug: Secrets in the output of built-in tools are redacted before the model and the task events receive them
  • Bug: A failing tool call reaches the blocked-host detector and the stuck guard through its own hook event
  • Bug: The stuck guard gives its advisory with the third identical failure, not only when the agent stops
  • Bug: Session scopes of an approval cover later calls of the tool or its group and are refused as pre-approvals
  • Bug: A clone of a repository whose name only contains the task repository's name is no longer refused
  • Also: A Write or Edit that would put a redaction marker into a file in place of the hidden value is refused
  • Also: The stuck guard's entry in the stop hook is deleted: 55 lines that could no longer inject anything

fix(agent): record cost, duration and metrics for a crashed task

  • Lean (delete): The pipeline's uvloop warning, which could never appear and used a deprecated asyncio call, is deleted
  • Bug: A crashed task shows its real duration instead of 0s and counts as a failure on the dashboard
  • Lean (merge): A task that fails after its agent ran keeps its cost and turn counts, so the monthly budgets include it
  • Lean (merge): The rule for which tasks must deliver a pull request or a commit exists once, in the delivery gate
  • Lean (stdlib): The check for the agent's needs-input marker is one expression, 7 lines shorter, with the same result
  • Test: A test fails when the pipeline stops removing Linear MCP servers from .mcp.json before the agent starts
  • Test: A test fails when the agent does not run on the context the platform sent, or accepts a newer format

fix(agent): repair local runs and diagnostics, close a coverage bypass

  • Bug: agent/run.sh builds the image from the repository root, where the Dockerfile's COPY paths start
  • Bug: Local agent runs, local table set-up and local progress events work with AWS CLI v1 as well as v2
  • Bug: agent/run.sh passes the auxiliary model setting into the container and drops a dead Linear variable
  • Bug: The SDK smoke diagnostic prints FAIL and exits 1 when Bedrock refuses the model call
  • Bug: The subprocess threading diagnostic exits 1 when a threaded read loses messages
  • Bug: Agent commits keep Co-Authored-By, Task-Id and Prompt-Version in one trailer block that git can parse
  • Gate: In the agent package a '# pragma: no cover' comment no longer hides code from the coverage floor

fix(agent): give repo-less tasks their attachments and a cancel check

  • Bug: A task without a repository downloads its attached files and names them in the agent's prompt
  • Bug: A cancelled task without a repository delivers no result, no event and no 'completed' memory episode
  • Bug: A start-up failure reaches the task record with its real reason, not as a lost session minutes later
  • Bug: The memory episode of a repository task carries the task's verdict, not the result of its build
  • Bug: A coding workflow that delivers a document no longer fails when it leaves out the requires_repo line
  • Bug: The console and bgagent watch show the build check after the agent, its result and the pull-request step

fix(agent): stop the post-hooks losing commits or failing the task

  • Bug: Commits made after the agent opened its pull request are pushed to it
  • Bug: A build that ran and failed is no longer taken for a command that could not run
  • Bug: Commits on the task branch are kept when the session ends on a branch with none of its own
  • Bug: The pull request the platform opens links the licence of the repository it is in
  • Bug: A commit or push hook that outlasts its timeout no longer fails the whole task
  • Bug: A build command whose program is not installed counts as could not run, not as a crash
  • Lean (merge): One function reads a pull request field; a gh lookup that times out no longer fails the task
  • Test: The safety-net commit is run by tests against a real repository
  • Also: A task without a repository whose workflow stops quietly on a failed agent step starts no delivery step

fix(agent): record tool results and error reasons, count real turns

  • Bug: The trace and the trajectory stream record what each tool returned, screened for credentials
  • Bug: A task stopped by a CLI error or the budget carries the CLI's reason in its error
  • Bug: The research workflow is no longer offered the clarification tool, whose question its lane drops
  • Bug: A clarification call with an empty question holds the task instead of failing it as not saved
  • Bug: The turn number in progress events, bgagent watch and bgagent status counts model answers, not messages
  • Lean (delete): The unused ENABLE_CLI_TELEMETRY opt-in and the nine variables it set are removed from the runner
  • Lean (reuse): The runner strips the agent's instrumentation variables with the rule run_cmd uses, now under test
  • Also: The call that streams build and lint output no longer trips the security scan; its decoding is unchanged

fix(agent): stop failing finished answers over an everyday phrase

  • Bug: A finished answer that contains an everyday promise is delivered instead of failing the task
  • Bug: A workflow file with the reserved empty post_hooks key loads, and the CI gate loads every shipped workflow
  • Bug: A read-only workflow whose pull request step names no strategy fails validation

fix(agent): stop renewing Linear tokens the agent cannot store

  • Bug: The agent no longer renews a Linear token it cannot store; an expiring one is left to the Lambdas
  • Bug: The final Linear reaction and the move to In Review use a token looked up when the task ends
  • Bug: A failed pipeline phase records its exception once on its tracing span instead of twice

fix(agent): correct the commands and rules the coding prompts give

  • Lean (merge): Both prompt builders share one memory renderer and one tail for overrides, channel guidance and skills
  • Lean (delete): The sanitizer has one name; the test that compared it with itself and a duplicate test are gone
  • Test: A test fails when a built system prompt still contains an unfilled {placeholder}
  • Bug: The system prompt names the Blueprint's build and lint commands instead of always the mise ones
  • Bug: The closing rules of the coding prompt agree with the numbered steps they follow
  • Bug: The review prompt shows the GitHub review request as valid JSON, with each comment as an object
  • Lean (reuse): The prompts take the two default workflow ids from the one definition in the configuration module

test(agent): cover the decisions run_task makes around the agent

  • Test: A test fails when a pull-request iteration or review is given the post-hooks of another workflow
  • Test: Tests fail when the typed marker stops holding a new task, or an iteration on a pull request is held
  • Test: A test fails when a build killed at its time limit is reported as a failed build
  • Test: A test fails when a task with a repository is not handed its attachment, or its prompt names a wrong path
  • Test: Tests fail when a task is remembered under the wrong name or the agent's notes are not stored
  • Test: Tests fail when a finished task is recorded with the wrong status, or Linear gets the wrong final mark
  • Test: Tests fail when a blueprint command, a branch or a limit of a task is dropped on its way to the agent

test(agent): pin what the runner hands the SDK and records from it

  • Lean (delete): The agent's session result no longer carries two duration fields that nothing read
  • Test: Tests fail when the tool lock, the policy hooks or a task limit is left out of the SDK session call
  • Test: A test pins what the runner records from a clean session end: status, final text, cost, session id, usage
  • Also: The pipeline's four fallbacks to a default workflow id use the two definitions of the configuration module

fix(agent): catch a re-clone of the task repository on its own line

  • Bug: The guard against a second clone of the task repository judges each command of a multi-line command alone
  • Test: Five tests call the callbacks that the SDK is handed, so a break in what they pass on fails a test
  • Test: Tests pin that a denied rule refuses its next call without a new request, and that a timeout does not
  • Test: Tests cover the approval flow's refusals for errors other than the two it knows by name
  • Test: Tests pin the numbers of the session-lifetime limit on an approval window, not only its label
  • Lean (reuse): One helper writes every best-effort progress event of the hooks, where two did the same
  • Also: The log line of a stuck-guard advisory is screened like the advisory itself

fix(agent): fail a task whose pinned MCP server the Linear scrub removes

  • Bug: A task fails when the Linear scrub removes a registry MCP server that its Blueprint pins
  • Lean (merge): Task verdict and error chaining are tested in one file, each case once (8 duplicate tests removed)
  • Also: The agent README's manual image build works again; the dry run and the credentials are described as they are
  • Also: A session's .mcp.json stays unstaged where the clone's exclude file lacks a final newline or cannot be written

refactor(agent): use one hash for approval rows and the deny cache

  • Lean (reuse): The approval hook stores a decision under the policy engine's own hash of the tool input
  • Lean (delete): Five pieces of the tool hooks that could never run are deleted, with two silent-failure suppressions
  • Also: Redundant checks for a progress writer in the approval step, the tool hooks and repository setup are removed

Task orchestrator, hydration, budgets and memory (26)

fix(hydration): fail a task that cannot run without its issue or PR

  • Bug: A review task on a pull request too large for the prompt keeps its 'Review this pull request' instruction
  • Bug: When its issue or pull request cannot be fetched, a task that cannot run without it fails and says why
  • Bug: The agent gets up to the newest 300 comments of an issue instead of only its 30 oldest
  • Speed: Trimming an oversized pull request applies the budget by arithmetic first and sanitizes no text twice
  • Scale: Each text the prompt budget admits is sanitized once: the work no longer grows with the dropped comments

fix(orchestration): stop false timeouts and stray agent sessions

  • Bug: No agent session is started for a task that is already failed or cancelled when the start step runs
  • Bug: On AgentCore and ECS the orchestrator waits about 8.5 hours at any poll interval, not 85 minutes at 5 seconds
  • Bug: A failed DynamoDB status read counts as a missed poll; only a refused read still ends the orchestration
  • Bug: The 'queued' comment on a Linear or Jira issue is posted only when the task really was queued
  • Bug: A queued Linear issue gets the queued notice as a plain comment, without the cross mark of a failed task

fix(api): make failure titles and retry advice match what failed

  • Bug: A task whose GitHub token is expired or revoked reads 'GitHub token rejected' and is not retryable
  • Bug: A task the platform dropped reads 'The platform lost track of this task', retryable, not 'Unexpected error'
  • Bug: The reply under a timed-out task says a retry may not resolve it instead of 'reply here to try again'
  • Bug: A task whose agent finished but whose build failed reads 'Build or tests did not pass', retryable
  • Bug: A task for a repository whose compute backend is not deployed says so and is not retryable
  • Bug: A hung clone, install or push is titled 'A setup or git command timed out', not as a slow build

fix(orchestration): treat temporary GitHub and ECS failures as temporary

  • Bug: A GitHub timeout, 5xx or 429 on the push-permission check fails the task as temporary, not as a bad token
  • Bug: A GitHub server error on the pull-request check is reported as temporary, not as a missing pull request
  • Bug: A rate-limited GitHub token fails new tasks as temporary ('rate limited'), not as a missing repository
  • Bug: An ECS task that a status read does not see yet is asked for again and fails only after three misses

fix(hydration): record guardrail blocks and use the repo token for URLs

  • Bug: An issue task that the content guardrail blocks gets its guardrail_blocked event, as a pull request task did
  • Bug: URL attachments are fetched with the repository's own GitHub token when it has one, not the platform token
  • Bug: The task detail reports a fetched URL attachment as passed, with its real type and size, not as pending

fix(memory): load past task episodes and let the team-budget alarm fire

  • Bug: The memory read before a task asks for the whole episodes subtree, so per-task episodes are in scope again
  • Bug: The alarm on skipped team-budget enforcement can fire: its metric is published with an empty dimension set
  • Also: The refusal of a task whose billed user is in more than 98 teams no longer names that user's platform id

Task API: reads, creation, attachments, authorizers (33)

fix(api): stop five read endpoints from failing or hiding data

  • Bug: bgagent policies list works for a repository whose Blueprint holds Cedar rules without annotations
  • Bug: The policy listing reads the repository row once: a failed read fails that request and caches nothing
  • Bug: The console's issue picker shows up to 50 open issues of a repository that has many open pull requests
  • Risk: A repository's issue list is kept for one minute, so repeated requests no longer cost a GitHub call each
  • Bug: bgagent trace download on a task whose trace file is gone prints 'No trace artifact', not an internal error
  • Bug: The replay of a long --trace task is returned clipped and marked as truncated instead of ending in 502
  • Scale: The pending-approvals list allows a user 60 calls a minute instead of 10, which two console windows reached

fix(api): make confirm-uploads fail closed and safe to repeat

  • Bug: Submitting a local file over 500 KB together with a URL attachment works instead of failing every time
  • Bug: A rejected upload is removed from storage at once instead of staying readable by version id for 7 days
  • Bug: The first blocked upload fails the task; a retried confirmation can no longer step over a blocked file
  • Bug: After a gateway timeout bgagent submit waits for the running confirmation and prints the task or its error
  • Bug: A repeated upload confirmation is answered with the task in all six live states instead of three
  • Bug: Uploads beyond the 50 MB limit fail the task at once with that reason, not later as an expired upload window
  • Risk: A file uploaded straight to storage as text fails the task when its bytes are not valid UTF-8 text

fix(api): limit what the server behind a URL attachment can do to a task

  • Bug: A URL attachment answered with status 204 or 999 fails the task instead of crashing the orchestrator
  • Risk: The URL attachments of a task share 30 seconds; a slow server then fails its own task with the reason
  • Risk: Linked files count against the 50 MB attachment limit of a task like every other attachment

fix(api): bound the secret scan of an oversized deny reason

  • Risk: An oversized deny reason can no longer hold the function until its timeout: 20,000 characters are scanned

fix(api): read auth headers in any casing and log each API key use

  • Bug: The API-key and webhook authorizers find their headers whatever the casing of the header name
  • Risk: Each allowed use of an API key is logged, and the log line of a new webhook names the key that made it
  • Bug: A revoked webhook stops authenticating as soon as its revocation has returned
  • Bug: A webhook or API key name that is not a string is refused with 400 instead of being stored
  • Also: A test fails when the webhook-management authorizer accepts an access token or another app client's token
  • Also: The webhook handler reads the signature and Idempotency-Key headers in any casing, like its authorizer

fix(api): refuse malformed task input and let a retried upload finish

  • Bug: An issue_number has to be a positive integer, as a pr_number already had to; null counts as absent
  • Bug: A replayed Idempotency-Key for a task that still waits for uploads returns new upload instructions
  • Bug: A malformed attachments value gets a 400 with the reason, not a lost attachment, a dead task or a 500
  • Bug: A next_token that cannot be decoded is refused with 400 instead of restarting the list at its first page
  • Bug: A task_description or deny reason that is not a string gets a 400 naming the field, not a 500
  • Also: The Slack processor takes the two inline attachment limits from the validation module; its copies are gone

fix(api): log an invalid policy set under its own message

  • Bug: The log line of an invalid policy set keeps its message and carries the parser text in the field error

fix(api): hide expired approval requests and wire the per-user cap

  • Bug: The pending list leaves out approval requests whose window has passed and reads past up to 2,000 of them
  • Bug: The stack passes its per-user task limit to the task API and the queue pickup, not only to the orchestrator

Linear, Jira, Slack and GitHub integrations (65)

fix(jira): ignore ABCA's own comments and another site's stored graph

  • Bug: On a Jira site without the Forge app, ABCA no longer answers its own orchestration panel as an instruction
  • Bug: A Jira issue adopts a stored orchestration only from its own site, so a site change cannot start old tasks
  • Bug: The run that loses the race to create a Jira orchestration deletes its attachment copies from S3
  • Bug: ABCA's refusal of a Jira retry from an unlinked account no longer starts an agent run on the pull request
  • Bug: When ABCA cannot get a Jira access token, a site with the Forge app gets a failure comment with the remedy
  • Bug: A Jira webhook body of JSON null and a numeric account-link code are answered with 400 instead of 500

fix(slack): keep retried deliveries from losing or repeating messages

  • Bug: The final Slack message of a task is posted on a retry after a Slack outage instead of being lost for good
  • Bug: A replayed 'task created' or 'agent started' record no longer posts and deletes a duplicate Slack message
  • Bug: A Slack mention whose first delivery failed outright is processed on Slack's first retry, not dropped

fix(linear): tell commenters why nothing started and end a reply loop

  • Bug: The Linear bot recognises two more of its own replies, which ends a reply loop one comment could start
  • Bug: A Linear comment whose task is refused gets the reason in place of 'On it' and a cross instead of eyes
  • Bug: A Linear label event processed twice no longer posts a false failure comment on a running task
  • Bug: A comment to the bot on a Linear sub-issue without a pull request gets a reply that says its state
  • Bug: A retry or follow-up on a plain Linear issue runs with the earlier task's description plus the comment

fix(slack): stop taking the first slash word of a mention as repo

  • Bug: A Slack file over the inline limits (500 KB, 3 MB per message) is refused by name before it is downloaded
  • Bug: A Slack request that fails with an unexpected error gets ❌ in place of 👀, like the other refusals
  • Bug: Slack messages round a task's duration before splitting it: '2m' instead of '1m 60s'
  • Bug: A Slack bot token scheduled for deletion counts as absent, so removing the app no longer raises the alarm
  • Bug: The Slack install page reads the app credentials on every call, so a corrected secret works at once
  • Bug: The Slack account-link endpoint answers 400 instead of 500 when the code in the body is not a string
  • Bug: In a channel with a default repository, a mention with CI/CD, and/or or a file path is no longer rejected
  • Bug: A Slack message of several lines reaches the agent as written, with its line breaks and indentation
  • Bug: A mention inside a Slack thread gets the progress reactions itself, not the first message of the thread

fix(fanout): retry failed notifications and stop false Jira successes

  • Bug: A notification that fails for a passing reason is retried from the failed record on, not as a whole batch
  • Bug: A final reply that Linear refused is delivered again instead of staying on 'On it' for good
  • Bug: The 'Opened a pull request' comment on Linear no longer depends on the stream being slower than the agent
  • Bug: A GitHub token refused twice is logged and dropped instead of replaying the batch to the dead-letter queue
  • Bug: When the agent stops to ask a question, the Jira issue shows the question instead of 'Task completed'
  • Bug: A Jira iteration posts its result even when the status comment was deleted or can no longer be edited
  • Bug: A Jira iteration that changed code and ends with a failing build is a failure, not 'Task completed'

fix(linear): keep vault workspaces online, previews on the right issue

  • Bug: One throttled vault call can no longer take a working Linear workspace offline until it is re-authorized
  • Speed: A Linear token from the Identity vault is reused for 60 seconds instead of two AgentCore calls per request
  • Bug: A preview screenshot goes to the Linear issue of the task that opened the pull request, in its workspace
  • Bug: The Linear issue search gives up after 5 seconds and the token renewal after 10; neither had a time limit
  • Also: The Linear reply about an attachment that could not be downloaded or screened no longer shows the error text

fix(linear): answer a named sub-issue with its state, not a question

  • Bug: A Linear issue whose own text fits the 10,000 character limit is not rejected for a paragraph ABCA adds
  • Bug: The bgagent:help label on an issue outside an onboarded project gets an answer that says what is missing
  • Bug: A comment on an epic that names a sub-issue without a pull request is answered with that sub-issue's state

fix(screenshots): let a branch name only a task of its own repository

  • Bug: A Linear task's preview reaches its issue or reply even when the pull request never names the issue
  • Bug: A word and a number in a branch name no longer hide the Linear identifier in the title or body
  • Test: The re-deploy path of the screenshot processor has tests that fail when it breaks
  • Bug: A Jira comment that ends its sentence with the mention ('... onto main, @bgagent.') starts the iteration
  • Bug: A browser command that times out reports the time it was given, where it always said 0ms
  • Also: The branch name of a pull request can no longer put a preview picture onto a task of another repository

fix(jira): stop moving cards backward and show the agent's answers

  • Bug: A Jira issue that is already In Review or In Progress stays there instead of moving back or sideways
  • Bug: Italic lines of ABCA's Jira comments render as italics instead of showing their underscores
  • Lean (merge): Creating and updating a Jira comment share one code path for identity, token refresh and retry
  • Bug: A question asked with @bgagent on a Jira issue gets the agent's answer in the result comment
  • Bug: Recent Jira comments given to a task are the ten newest human ones, without ABCA's own comments
  • Bug: Jira descriptions and comments keep nested list items, code blocks in lists and pasted links
  • Bug: The renewal of a Jira OAuth token gives up after 10 seconds instead of holding the function
  • Also: The Jira comment about an attachment that could not be downloaded or screened no longer shows the error text

fix(metrics): publish the approval metrics that have no dimensions

  • Bug: Approval metrics without dimensions declare one empty dimension set, so CloudWatch can create them
  • Bug: The timeout of a timed-out approval is also published without dimensions, as the dashboard reads it
  • Bug: An answer to a clarifying question starts the resumed run even when the description is full
  • Bug: A reply rounds its duration once, so 119.6 seconds reads 2m instead of 1m 60s

fix(linear): let an admin remove a workspace whose Linear grant died

  • Bug: The console shows a labeled Linear issue as starting for ten minutes at most, not for as long as it is open
  • Bug: For a project mapped before its workspace was recorded the console prints the onboard-project command
  • Bug: The Linear webhook answers 400 or 401, not 500, to a null body or an organizationId that is not a string
  • Bug: remove-workspace also removes a workspace whose Linear grant died, and deletes its secret
  • Bug: POST /linear/link answers 400, not 500, when the code in the body is not a string

fix(linear): stop telling the agent an attached file is missing

  • Bug: A Linear task's context hint names only the paperclips the task does not carry, not the files it attached
  • Lean (reuse): The unused wrapper around the Linear issue-to-task lookup is gone; its tests call the lookup production uses
  • Lean (merge): One function swaps the status marker of a Linear issue or of a comment, in place of two copies

fix(linear): write "Task timed out" in the final comment, not timed_out

  • Bug: The final Linear comment of a timed-out task reads "Task timed out" instead of "Task timed_out"

Epic orchestration (sub-issues) (22)

fix(orchestration): stop the sweep editing every finished epic's panel

  • Scale: The sweep stops editing the panel of a finished epic one hour after its final status was recorded
  • Bug: The sweep takes back a sub-issue's claim only after 10 minutes, so a live start gets no second agent run
  • Bug: After a recovery by the sweep the parent issue shows its final status in the same run, not 10 minutes later
  • Bug: A multi-line Linear comment (a list, a code block) reaches the agent as written, not joined into one line
  • Bug: A Linear comment that ends its sentence with the mention ('..., @bgagent.') starts the work

fix(orchestration): stop late task events from undoing an epic's repair

  • Bug: A late write to an old task record no longer marks a repaired or retried sub-issue failed again
  • Bug: A question answered on a sub-issue no longer re-stacks its dependents or counts as a repair
  • Bug: A final epic status whose panel edit failed is tried again by the next event or sweep run
  • Bug: The epic panel shows a sub-issue it has just started as running, not as blocked

fix(orchestration): let a reworded or long sub-issue of an epic start

  • Bug: A long sub-issue under a long epic starts: the shared epic text is cut to fit the description limit
  • Bug: Re-applying the trigger label reads the title and text of sub-issues that have not started again
  • Bug: A step added to a chain epic no longer brings a second agent run that opens the same pull request
  • Risk: Rows that DynamoDB hands back unprocessed are written again, and a seed that cannot store them fails
  • Bug: The epic panel lists sub-issues by their number (ENG-9 before ENG-10) and the integration row last
  • Lean (delete): Five functions of the old status block and rollup comment that nothing calls are deleted
  • Bug: After a retry that could not start, the panel says why it did not start, not how the earlier run failed
  • Also: A final panel edit that can never land is retried by the sweep for one day, not for as long as the rows exist

fix(orchestration): run a sub-issue added to an epic after a failure

  • Bug: A sub-issue added to an epic after a failure builds on the work that succeeded and runs
  • Bug: Replies on an epic name the project's own trigger label and say to re-apply it on the epic
  • Also: A retry after a clarifying question keeps the reviewer's answer when the earlier description is cut to fit
  • Also: A retry comment on an epic reads its sub-issues again, so a refused and reworded sub-issue can start
  • Also: The sub-issue release loses a retry option that nothing read; two log event names without an emitter are gone

bgagent CLI (50)

fix(cli): make the Linear commands work on a multi-workspace stack

  • Bug: A workspace added with bgagent linear add-workspace has its events accepted instead of answered with 401
  • Bug: bgagent linear add-workspace refuses any workspace already registered; five messages point to setup instead
  • Bug: bgagent linear invite-user works for every workspace of a multi-workspace stack, not just one of them
  • Risk: On the Secrets Manager path, bgagent linear setup refuses a slug registered to another workspace
  • Bug: bgagent linear list-projects and onboard-project report a token Linear refuses, not an empty result
  • Risk: bgagent linear setup reads the stack-wide signing secret once and stops when that read fails
  • Risk: bgagent linear setup stops, before it writes anything, when it cannot read the workspace registry

fix(cli): report a corrupt config as not configured, add missing tests

  • Test: A test fails when the preview call of bgagent linear link or jira link loses its dry-run flag
  • Test: A test fails when --verbose prints a freshly created API key instead of masking it
  • Lean (delete): The client call behind bgagent status loses an option that no command passed, and the test of it
  • Test: A test fails when saving credentials does not make an existing credentials file owner-only
  • Bug: A config file that cannot be parsed is reported with its path and the reason, not as a bare JSON error
  • Test: A test fails when the retried statuses are not 500 to 599, or --wait keeps its count after a good poll

fix(cli): make --verbose work on subcommands of command groups

  • Test: A test fails when the cached login expiry is not one hour ahead for a lifetime of 3600 seconds
  • Lean (merge): Login and token refresh save Cognito's answer through one function; the auth module is 10 lines shorter
  • Bug: --verbose takes effect on the subcommands of command groups, for example bgagent --verbose webhook list
  • Test: A test fails when bgagent status --wait exits with another code than 2 after it gives up waiting
  • Lean (reuse): The CLI's list of final task statuses is typed, so a misspelt status in it is a compile error
  • Lean (delete): The CLI's unused library entry point is removed (24 lines), so the dead-code check sees its API types

fix(cli): correct two Linear command reports and delete dead paths

  • Bug: bgagent linear setup offers to keep the signing secret only when one is stored, not on a first install
  • Bug: bgagent linear backfill-secret-provenance reports a skipped workspace as skipped only and does not count it
  • Lean (delete): Three unreachable signing-secret paths of bgagent linear setup are deleted: 187 product lines fewer
  • Lean (delete): autoLinkTokenOwner, without a caller since the move to OAuth, is deleted with its three tests (191 lines)
  • Lean (reuse): bgagent linear list-projects calls the two shared lookups instead of its own copies: 49 lines fewer
  • Lean (delete): bgagent linear app-template loses --aws-callback-url, which printed a redirect URI the CLI never sends
  • Lean (merge): The Linear commands read stack outputs through the shared findStackOutput instead of a private copy

fix(cli): let Linear prompts read a piped answer, test consent guards

  • Lean (merge): bgagent linear setup, add-workspace and invite-user share one login-token decoder and one error wording
  • Lean (merge): Five Linear commands check the workspace slug through one function instead of five copies (15 lines fewer)
  • Test: A test fails when one of the four Linear consent paths accepts a state the command did not send
  • Test: A test fails when bgagent linear update-webhook-secret drops its registry write or the stored tokens
  • Test: A test fails when linear backfill-secret-provenance marks a copied secret owned or a dry run writes
  • Test: A test fails when bgagent linear setup stops refusing to move a vault workspace to Secrets Manager
  • Also: The prompts of the Linear, Jira and Slack commands read piped answers, each line answering one prompt

fix(cli): share one visible prompt that fails at the end of input

  • Lean (merge): Linear, Jira and Slack commands ask through one visible prompt, which fails at the end of the input
  • Test: Tests run onboard-project and pin the owning workspace it records, or that nothing is written
  • Test: Tests reach the self-link picker of setup and add-workspace and pin the user mapping it writes
  • Lean (delete): The Linear OAuth module no longer carries an expiry helper that only its own tests called
  • Lean (yagni): Linear OAuth and vault helpers lose three parameters and a result field that nothing used
  • Lean (merge): The Jira OAuth error for an unexpected token response names the fields it got, not their values
  • Also: The Jira commands drop their copies of three helpers the Linear commands have (about 60 lines fewer)
  • Also: The Jira and Slack commands use the shared stack-output lookup instead of private copies (about 40 lines)

refactor(cli): drop a hand-written JSON walk and two wrapper functions

  • Lean (yagni): Inviting a user and resetting a password each make their Cognito call in one function, not two
  • Lean (stdlib): Verbose output masks secret fields while JSON.stringify writes the body, with no copy made first

fix(cli): follow the API's attachment limits and list pagination

  • Bug: bgagent submit refuses .gif and .webp itself and uploads small files beyond 3 MB of inline data
  • Scale: bgagent webhook list and api-key list follow next_token until the rows asked for are there
  • Risk: bgagent configure drops the cached login when it points the CLI at another user pool
  • Bug: bgagent watch exits with code 2 and the real failure count when it gives up on a failing API
  • Also: bgagent submit uploads each of two attachments that share a file name instead of the first one twice
  • Also: A replay bundle that bgagent replay --force writes over an existing file is owner-only like a new one
  • Also: Two copies of the final-status check and six casts are deleted; watch takes its exit code where --wait does

Registry (13)

fix(registry): stop publish stranding records and hiding the reason

  • Bug: A slow registry publish completes or returns the error that names the stranded record, not a gateway error
  • Speed: Resolving a pinned asset and the publish duplicate check fetch only the records of that asset
  • Bug: A publish conflict returns the registry's own message, such as the hint to delete a corrupt record
  • Bug: Registry publish answers 400 with AWS's reason when AWS refuses the record as invalid, not 500
  • Risk: Registry publish answers 400 when namespace, name or asset_version is not a string
  • Bug: An exact registry pin matches only the version as written, in both the TypeScript and Python resolvers
  • Bug: The Python registry reference parser accepts ASCII digits only and rejects an over-long version part

fix(registry): delete a registry's records before deleting the registry

  • Bug: The registry custom resource deletes a registry's records first, as AWS requires, then the registry
  • Bug: The emulator README lists the registry's one-record-per-name refusal as a known difference from AWS

fix(registry): keep git working in clones with registry MCP servers

  • Bug: Two pins of one registry MCP server that resolve to different versions fail the task with the reason
  • Lean (delete): The registry documents that tool_prefix is not applied and how a registry server's tools are named
  • Gate: cdk-nag checks again that every registry API route uses the Cognito authorizer
  • Also: git stash, rebase and merge work again in a clone with registry MCP servers; git add -A skips .mcp.json

Follow-up changes in neighbouring files, and documents brought in line (63)

chore(cdk): drop dead cdk-nag suppressions, fetch less in registry show

  • Gate: The coverage drift check's suite covers the removal of the two lists that make pragma comments inert
  • Docs: Comments name the admission step and tie the CLI's wait to the upload confirmation timeout
  • Docs: The dashboard comment names the timeout metric its percentile lines read, the one without dimensions
  • Lean (delete): The orchestrator handler test no longer mocks a repository check that nothing calls
  • Lean (delete): The session start test no longer mocks a repository check that nothing calls
  • Speed: Showing a registry asset fetches the versions of that asset, not every record of its kind and namespace
  • Gate: cdk-nag checks five places again where a suppression covered no finding

docs: bring the design docs and guides in line with the changed code

  • Docs: The approval design gives the pending-list limit as 60 a minute and what a session scope adds to the allowlist
  • Docs: The interaction design lists the failure hook and says that text attached to a tool result reaches the model
  • Docs: The developer guide says that a dry run prints the length and a hash of the prompts, not the prompts
  • Docs: The workflow design names the step events as emitted and says that a missing strategy counts as create
  • Docs: The agent's contributor guide says that pragma comments no longer take code out of the coverage floor
  • Docs: The Linear guide matches the code on workspace removal, a re-applied epic label and the agent token warning
  • Docs: The attachment design states the 30-second URL limit, the Slack limits and what a replayed create returns
  • Docs: The API contract documents the replay of an upload task, a refused next_token and the confirm-uploads errors
  • Docs: The screenshot guide explains how a pull request's Linear issue is found and why a preview can stay on GitHub
  • Docs: The Jira guide lists the question comment, the answer to a no-change request and the rule for cards in review
  • Docs: The Slack guide says when a mention is answered 'not onboarded' and when it runs on the channel's default repo

fix(orchestration): refuse a fork's pull request before a session starts

  • Bug: A task on a pull request from a fork is refused before a session starts, with a reason of its own
  • Docs: Two code comments state the ECS poll rule and the registry list filters as they are now
  • Bug: A Jira preview is delivered when the blueprint spells the repository in another letter case than GitHub
  • Lean (reuse): One private-address check guards both attachment downloads and refuses all of fe80::/10
  • Test: A test pins that a failed S3 store of a Linear or Jira attachment fails with the answered error
  • Also: The one-day window for retrying a failed final panel edit counts from the epic's end or its last re-open

fix(cli): make bgagent list follow the page token of the API

  • Lean (delete): The event catch-up of the CLI client no longer takes a page size that its only caller never varied
  • Bug: bgagent platform doctor names --label in the onboard-project command it tells the operator to re-run
  • Also: bgagent list reads on for up to five requests, so a filter finds older tasks and --limit works up to 500
  • Also: bgagent list, webhook list and api-key list follow the page token with one function instead of three loops

fix(agent): use the shared redactor in the server, drop deprecated calls

  • Docs: Comments on the session tags, the Linear token fixture and a nudge test match the code again
  • Lean (delete): The server no longer calls a function Python removes in 3.16, and the type check reports deprecated calls
  • Test: A test fails when the agent stops storing an iteration's outcome: code changed or not, answer, commit
  • Docs: The comment on the attachment download says what the workspace is for a task without a repository
  • Risk: The server's own log lines pass through the agent's one redactor instead of a second, narrower copy
  • Gate: Three coverage-ignore comments that have no effect in the agent are removed
  • Test: Two emulator tests check that updated_at moves with the status the agent writes
  • Also: A task's attachments stay out of the pull request when the clone's exclude file ends without a line break

test(registry): add six cases to the two-language parity corpora

  • Test: The shared resolver corpus holds an exact pin beside its leading-zero twin and two identifiers from 2^53 on
  • Test: The shared resolver corpus holds a candidate version written with a digit from another script
  • Test: The shared grammar corpus holds a digit from another script and two more line terminators at the end of a ref

fix(console): word the last step of a task by what that step does

  • Bug: The console's activity feed says 'Opening a pull request' only for a task that opens one
  • Bug: The console's raw event list labels an agent turn 'Turn N', the number of the model's answer
  • Test: The test of the console's raw event list expects 'Turn 7' for an agent turn without text
  • Bug: The console's API types say that a Linear issue reported as with the agent can come without a task

refactor(cdk): one pull request number rule, drop unused channel ops

  • Lean (reuse): One function reads a task's pull request number; the three other copies are gone
  • Lean (delete): The Linear adapter no longer carries two channel operations that nothing calls
  • Lean (delete): The function that swept interim notes off a Linear thread is deleted with its query
  • Lean (delete): The five tests of the deleted note sweep are removed with it
  • Docs: Comments of the Jira and Slack adapters no longer list two operations that do not exist
  • Lean (delete): The channel interface and its design document describe only the operations that are used
  • Bug: A stored number that is no pull request number reads as no pull request in all four readers

chore(cdk): drop two dead cdk-nag suppressions, correct stale comments

  • Docs: Two comments and a test title say what the code does (issue list time limit, queued task, timed-out command)
  • Lean (delete): cdk-nag now checks the origin access control of the consent page and console distributions
  • Also: The console's issue picker says to try again (503), not 500, when GitHub stalls while a page is being read

fix(agent): fail a task whose pinned MCP server the CLI would skip

  • Bug: A pinned MCP server with a field of a type the Claude Code CLI refuses fails the task before it starts
  • Docs: Two registry test docstrings name the cases that the two-language parity corpora hold by now
  • Lean (delete): The runner's comment no longer promises a missing-SDK fallback that the clarification tool does not have
  • Bug: The timed-out approval event's docstring says the publisher also emits its timeout without dimensions
  • Also: Registry publish answers 400 for an MCP server with non-string header values or args that are no string list

docs: say what a request without a workflow runs, list the fork reason

  • Docs: The registry design says that an MCP server with 'linear' in its key or settings cannot be loaded
  • Docs: The Jira guide says what a subtask added after a failure builds on
  • Docs: The user guide says what a request without a workflow runs and corrects five commands and limits
  • Docs: The API contract lists PR_FROM_FORK; the attachment design gives the upload rules of the CLI and Slack
  • Docs: The contributor guides name the type check's rule for deprecated calls and the coverage pragmas without effect

Constructs, quality gates, docs and web console (36)

chore(tooling): close a lint bypass in cdk, drop 15 duplicate rules

  • Gate: A stray ESLint configuration file below cdk can no longer take files out of the cdk lint tasks
  • Lean (delete): Fifteen deprecated ESLint core formatting rules that cdk and cli ran twice are deleted (39 lines fewer)

fix(cdk): deliver nudges on ECS, correct pass rates, redact keys in WAF

  • Bug: The Build and Lint Pass Rate widgets leave out a task that reports no build or lint result
  • Bug: A nudge sent with bgagent nudge reaches a task that runs on the ECS backend instead of expiring unread
  • Risk: The web firewall stores REDACTED in place of the Authorization and X-API-Key values in its request samples
  • Also: Two comments in the stack say that the concurrency cap queues a task and that Linear gets a plain comment

fix(hydration): sanitize a text in time proportional to its length

  • Scale: Sanitizing a text takes time proportional to its length, so one long comment cannot hold up a task's start

chore(tooling): tighten the SAST scan, git hooks and coverage gates

  • Gate: The whole-repository SAST scan fails when semgrep loaded no rules and shows what semgrep reports
  • Bug: mise run without a task name installs first and builds afterwards
  • Gate: Git hooks run the node, gitleaks and semgrep that mise.toml pins instead of the machine's own
  • Gate: The cdk, agent and CLI coverage floors sit two points under what the suites measure
  • Gate: The coverage contract pins which tests pytest collects and the file its coverage settings come from
  • Lean (delete): The allow lists of bandit and ruff lose the entries that accepted nothing

docs(guides): correct the task requests of the guides and test them

  • Bug: Task requests in the user guide and the quick start name the coding workflow; a test sends each to the API
  • Lean (delete): The docs package no longer carries jest, jest-junit and a jest configuration that nothing runs
  • Gate: The docs test task fails when one of its two test files is missing, instead of running fewer tests
  • Also: The user guide lists the scopes bgagent submit --pre-approve accepts and the three that are refused

fix(agent): replace app and bearer tokens whole past an inner marker

  • Risk: Both secret scanners replace a GitHub App token whole when part of its signature looks like an older token
  • Also: Both secret scanners replace a JWT behind Authorization: Bearer whole, past a marker another pattern wrote

chore(tooling): delete unread .npmignore files and dead scan exemptions

  • Lean (delete): Two secret-scan exemptions the scanned history does not need and seven ignore comments ty skips are removed
  • Lean (delete): Three .npmignore files of packages that are never packed are deleted, with the three lines that named them
  • Also: The CLI README no longer tells users to install an npm package that the project does not publish

chore(tooling): fail the console lint on dropped and misused promises

  • Gate: The console's lint fails on a promise that is dropped or handed to code that ignores it, as in cdk and cli
  • Also: A click on the console's title goes to the overview inside the app instead of reloading the whole page

chore(tooling): turn on three lint rules, test the complexity records

  • Gate: The CLI lint tasks name their configuration file, so one in a subfolder cannot replace the rules
  • Gate: The lint tasks of the web console name their configuration file as well
  • Gate: A test fails when a function above the complexity ceiling grows past the value recorded beside it
  • Docs: The cdk and CLI guides say what the number in a complexity comment means and which test holds it
  • Gate: An explicit any fails the CLI lint; the upload error of submit is read as before this pull request
  • Gate: In cdk a catch block that throws a built-in Error without the caught error as its cause fails the lint
  • Gate: A control character in a regular expression fails the lint of cdk and the CLI, two patterns excepted
  • Gate: Two spaces inside an import attribute are a lint finding again in cdk and the CLI
  • Gate: Five functions that got smaller have their complexity record lowered, so the branches cannot return

fix(tooling): masking gate sees tuple handlers and non-source files

  • Gate: The masking gate also matches a handler written except (A, B): and a try statement with an else clause
  • Gate: A semgrep suppression in a workflow, Dockerfile, script or config file needs a rule id and a reason

fix(agent): keep trace headers and baggage out of third-party requests

  • Risk: Agent requests to Linear and Atlassian carry no trace headers and no baggage with user id and repository

Changes after the first reviews of this pull request (47)

fix(cli): upload the right file on a retry, report the real failure

  • Bug: A retried submit uploads each same-named file into its own attachment, not the first one twice
  • Bug: After a gateway timeout the CLI prints the task it read or why it ended, and confirms again only if pending
  • Bug: A config file that cannot be read or parsed is reported with its path, the reason and what to do

fix(linear): revoke only the installation a workspace removal read

  • Risk: A Linear workspace set up again between a removal's read and its revoke keeps its new registration

fix(agent): refuse every fork pull request, flag failed gateway calls

  • Bug: A failed repo_config call through the Tool Gateway reaches the model marked as an error
  • Bug: A task without a repository downloads its attachments into a directory of its own
  • Risk: The agent asks GitHub about every pull request whether it comes from a fork, whatever its branch is called

fix(jira): stop iterations pulling cards back, use current overrides

  • Bug: With a --status-on-start override, an @bgagent iteration leaves an In Review Jira card where it is
  • Bug: Outside an orchestration, an @bgagent iteration takes its Jira status overrides from the project mapping
  • Bug: Running bgagent jira map again keeps the date the project was first mapped

fix(agent): gate git push <ref> -f before ; & | > 2> or a line break

  • Risk: A force push with -f after the branch needs approval also before a line break, ;, &, |, > or 2>

chore: correct two documents and drop a dead bundling workaround

  • Docs: ADR-016 says who renews a Linear token: the Lambda resolver does, the agent only reads the stored one
  • Docs: The API contract states the limits of GET /v1/pending: expired requests hidden, 100 listed, 60 calls a minute
  • Lean (delete): The orchestrator bundle is built without the import.meta.url substitution that durable SDK 1.1.3 needed

fix(cli): refuse a Linear slug registered to another workspace

  • Risk: Linear setup and add-workspace refuse a slug registered to another workspace, also when the URL key matches
  • Bug: linear list-projects exits 1 when a workspace could not be queried, in JSON and in text output

fix(jira): render the agent's Markdown and name a red build's reason

  • Bug: A Jira comment renders the agent's answer or question from its Markdown, fenced code as a code block
  • Bug: A Jira iteration that completes with a red build names the reason: Build or tests did not pass

fix(orchestration): bound failed status reads, contain two failed writes

  • Bug: A failed session_started write on AgentCore or ECS no longer makes the start step start more sessions
  • Bug: Three failed status reads in a row end the orchestrator's wait (replaced later in this pull request: failed reads are waited out)
  • Bug: A seed writes an epic's meta row after all sub-issue rows, alone, so a failed seed leaves no half epic

fix(cli): keep the first-mapped date of Linear and Slack mappings

  • Bug: Running bgagent linear onboard-project again keeps the date the project was first mapped
  • Bug: Running bgagent slack onboard-channel again keeps the date the channel was first mapped

fix(agent): redact a connection string whose password holds a slash

  • Risk: A URL password that holds a slash is redacted (a later commit narrows which URL with a port is kept as plain)
  • Test: Both secret scanners run the same connection-string cases from one shared vector file

fix(agent): gate git push -f whatever follows the flag

  • Risk: A force push written git push -f needs approval whatever follows the flag (;, |, -fu)

fix(agent): stamp updated_at when a task resumes after an approval

  • Gate: The approval hook's complexity record states 24, what the function measures with main's lifecycle code
  • Bug: A task that returns to RUNNING after an approval gets updated_at set to the moment it resumes
  • Test: The test of the capped approval wait holds the clock still and asserts exactly 80 seconds again

fix(cli): read the active row where two rows carry a Linear slug

  • Bug: Where a dead-grant row and an active row share a Linear slug, the CLI reads the active one

fix(jira): keep operators and links as typed, and a red-build answer

  • Bug: A Jira comment keeps operators written with asterisk pairs as typed (x ** 2, **kwargs, f(**a))
  • Risk: A link or an image in the agent's answer or question stays as typed on Jira, with its URL visible
  • Bug: A standalone Jira iteration that only answers a question on a red build posts the completed comment and its answer

docs(agent): name the probed CLI versions, correct two complexity notes

  • Docs: The credential helper's docstring names the Claude CLI versions that were probed and says 2.1.319 was not
  • Gate: run_agent's complexity record states 40, the value main's MicroVM change left, and must not grow
  • Docs: The agent guide counts nine functions with a complexity record, some with a newer value in front

fix(orchestration): wait out failed status reads, stop a leaked MicroVM

  • Risk: A replayed MicroVM start for a task that is already over stops the MicroVM the first run launched
  • Risk: Failed status reads are missed polls however many fail in a row; only a refused read ends the orchestration
  • Test: The poll-timeout guidance test also covers the message an approval wait gets when the window closes
  • Docs: ORCHESTRATOR.md states what a failed status read does during the wait on each backend

fix(jira): keep a run of asterisks in the agent's text as typed

  • Bug: A run of asterisks in the agent's text, such as a masked value, stays as typed on Jira

fix(agent): redact a URL whose password begins with digits and a slash

  • Risk: A URL is redacted when its password begins with digits and a slash; host:port/path/@name is left as it is
  • Risk: A URL with an empty user, the Redis form redis://:password@host, is redacted by both scanners
  • Test: Timing tests pin the bounds of the connection-string pattern, and shared cases pin its port rule
  • Docs: The comment at the connection-string pattern says which URL is kept and why, the same in both scanners

fix(orchestration): drop the ten-poll rule that only a stale read met

  • Bug: The orchestrator's wait no longer ends after ten polls on a stale HYDRATING read

test(agent): hold the port rule of the scanners to the first at sign

  • Test: A shared case holds the scanners' port rule to the first at sign behind the port

@krokoko

krokoko commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor Author

Agent runtime (Python) (part 1 of 3): what changes and what it gains

fix(agent): set updated_at when the agent changes a task's status

Bug: updated_at shows when the agent finished, failed or paused a task, not when the task started to run

When the agent itself changed a task's status (finished it, failed it, or paused it to ask for an approval), it left the task's updated_at time untouched, so the API kept returning the moment the task had started to run. A task that failed after three hours was listed under 'Needs you' on the console's Overview as updated '3h ago', a repository whose last task had just finished showed its last activity as '3h ago', and tasks left the 'Done (24h)' and 'Failed (24h)' counters hours too early. The agent now sets updated_at together with the status, as every status change made by the rest of the platform already does. The return to RUNNING after an approval was left out at first, because pull request #904 was rewriting that statement; #904 is merged and did not set the time, so a later commit of this pull request sets it there too. Every status change the agent makes sets updated_at.

Gain: Bug fixed for every reader of updated_at: the console's 'Updated' column, a repository's last activity, the 'Done (24h)' and 'Failed (24h)' counters, the recent-failure flag and the API field now show when a task finished or paused, not when it started. Until now the value was wrong by the task's whole running time, up to 8 hours; a task waiting for an approval now shows how long it has waited. About 15 lines of agent code, and the guide's example of a completed task shows the corrected value.

Test: agent/tests/test_task_state.py > TestStatusWritesStampUpdatedAt: test_terminal_write_stamps_it_with_completed_at, test_running_write_stamps_it_with_started_at, test_approval_request_stamps_it

Bug: The user guide no longer promises a logs_url field that nothing returned, and the agent stops storing it

The user guide said that every task record has a logs_url field with a direct link to its CloudWatch logs, and that it can be read from the task status output or from the API. Nothing ever returned that field: not the API, the CLI or the web console. The agent stored the link in the database only in the rare case where its own RUNNING write came before the orchestrator's, and no code read it. The guide now gives only the instruction that works (open the log group and filter by task id), and the agent no longer builds or stores the link.

Gain: The guide stops promising a field that never arrives. 62 lines removed and 18 added: 20 lines of agent code and the five tests of the deleted link builder are gone, one small test stays to show that the attribute is no longer stored. No reader changes behaviour, because there was none.

Test: agent/tests/test_task_state.py > TestWriteRunningMaintainsStatusCreatedAt::test_stores_no_logs_url

Bug: The agent log names the AWS error code and message when a status write fails, not just ClientError

When the agent could not store a task's final status, or its RUNNING status, the log line ended with the single word ClientError, which is the name of every AWS error. A refused permission, throttling and an invalid request all looked the same, and a lost final status is what later makes the platform fail the task as 'Agent session lost'. The two log lines now carry the error code and message, like the other status-write log lines in the same module.

Gain: Whoever reads the agent log after a lost status write sees the cause (for example AccessDeniedException or ValidationException and its message) instead of one opaque word. 2 lines changed.

Test: agent/tests/test_task_state.py > TestFailedStatusWriteNamesTheError::test_write_terminal and ::test_write_running

Risk: Attached files are in the clone's local exclude file, so git add -A, clean -fd and stash -u skip them

Files that a user attaches to a task (screenshots, logs) are downloaded into a .attachments folder inside the repository clone the agent works in. Git treated them as new, untracked work: a 'git add -A' or 'git add .' by the agent would put the uploads into the pull request, a 'git clean -fd' would delete them and a 'git stash -u' would put them away in the middle of the task. The folder is now listed in the clone's local exclude file, which is never committed, so these commands skip the uploads. The design document already said the folder was ignored; now it is.

Gain: A user's uploads can no longer reach a pull request through a broad git add, and a 'git clean -fd' or a 'git stash -u' no longer takes them away. A clean or stash that also asks for ignored files still removes them ('git clean -fdx', 'git stash -a'), and 'git clean -fdX', which kept them before, now deletes them. The end-of-task safety net also stops logging 'Uncommitted changes detected' for every task whose only untracked files are its attachments. 7 lines added to the agent.

Test: agent/tests/test_attachments.py > TestDownloadAttachments::test_downloads_are_not_picked_up_by_git

fix(agent): fail task start on a Cedar rule that cannot be evaluated

Bug: A retry refused after a human denial appears in the task's event stream with the id of the denied rule

When a user denies an approval request, further attempts by the agent that match the same rule are refused at once for a minute, without asking again. Each such refusal is supposed to leave an event in the task's event stream. For this kind of refusal the event carried the id of the denied rule, a field the event writer did not accept: the error was swallowed and no event was written. The writer now accepts the rule id, so the event is written and names the rule.

Gain: Retries refused after a human denial (for example a force push retried on another branch) now appear in the task's event stream, which is what bgagent watch shows and what is kept as the audit record, with the id of the denied rule. Before, they left no trace there, only a warning in the agent log on every such retry and an error line after five. Six lines of product code.

Test: agent/tests/test_progress_writer.py > TestApprovalMilestoneHelpers::test_rule_level_cache_hit_reaches_the_event_stream

Bug: A task fails at start, with Cedar's message, when a rule errors on a Read, Write, Edit or Bash call

A Cedar rule from a blueprint or the registry can read the shell command or the file path in a request that has none. Two examples: a rule with no action that tests context.command, and the usual rule that blocks the Bash tool, extended with a test of the command. Such a rule passed the check at task start, and then every tool call it applied to was denied as an engine error: every call of the task with the first example, every shell command with the second. The check at task start now evaluates one call of each kind of tool the engine tells apart (a Read, a Write, an Edit and a Bash call), through the routine the engine uses at run time, and treats an evaluation error from Cedar as a failure. The task then fails at start with Cedar's message, which names the missing attribute.

Gain: A rule of this kind now fails the task at once with a clear error, which is what the engine's own documentation says of an invalid blueprint policy, instead of a task that spends its turns and budget on denied calls. This holds for a rule that applies to every tool call, to file writes, to shell commands, or to the Read, Write, Edit or Bash tool by name; a rule that names another tool (Glob, an MCP tool) is still found only when that tool is called. A task that used to run in spite of such a rule now fails at start as well: for example a read-only task whose blueprint has a rule that errors on file writes, which that task never evaluated. Policy text that cannot be parsed is now caught by this check as well. The check no longer repeats the engine's request names by hand and is 3 lines shorter than the code it replaces.

Test: agent/tests/test_policy_three_outcome.py > TestLoadTimeValidation::test_rule_reading_an_absent_context_attribute_fails_at_start (7 rows: 4 in the first commit, 3 in the follow-up) and ::test_hard_rule_reading_an_absent_context_attribute_fails_at_start

Test: A test fails when any of the five refusals of an unusable policy at task start is removed

The engine refuses to start a task whose policy it cannot use: text that is not Cedar, an approval timeout that is not a number, an unknown severity, a rule id that repeats a built-in rule of the same tier, and a hard rule placed among the soft rules. None of these five refusals had a test: each could be deleted and every test still passed. One parametrized test now has a row for each.

Gain: Each of the five refusals at task start is now pinned: deleting any one of them fails exactly one row and no other test (shown by deleting each in a copy of the code). No product change; 51 lines of test.

Test: agent/tests/test_policy_three_outcome.py > TestLoadTimeValidation::test_policy_the_engine_cannot_use_fails_at_start (5 rows)

Test: A test fails when a pre-approval is checked after, not before, the memory of a recent denial

A pre-approval is checked before the one-minute memory of a recent denial, so that a user who denies one call and then approves the whole tool is not refused on the retry. This order is documented but had no test: the two steps could be swapped and every test still passed. A test now denies a call, pre-approves the tool and expects the retry to be allowed.

Gain: The last unpinned pair in the order of the decision steps has a test: with the two steps swapped it fails (the retry is still denied) and no other test does. No product change; 14 lines of test.

Test: agent/tests/test_policy_three_outcome.py > TestRecentDecisionCacheIntegration::test_pre_approval_beats_a_recent_denial_of_the_same_call

Lean (stdlib): The policy decision is a frozen dataclass: 89 lines fewer, and assigning to a field raises an error

The object that carries the result of a policy evaluation was a hand-written class with its own constructor, equality, hash and text form. Its comment gave the reason: tests could still build it with an old allowed= keyword, which no product code uses. It is now a frozen dataclass with the same fields, defaults, keyword-only construction, equality and hash, and assigning to a field of a decision after it is built now raises an error. The tests of the old keyword are removed.

Gain: 89 lines removed net (72 of product code, 17 of tests). Assigning to a field of a decision (outcome, reason, rule ids and the rest) between the engine that makes it and the hook that enforces it now raises an error; the dictionary that a cache hit carries for its event is still an ordinary dict. The class now has the form the design document gives for it.

Test: agent/tests/test_policy_three_outcome.py > TestPolicyDecisionConstruction (existing tests unchanged; ::test_outcome_is_required adapted; ::test_decision_cannot_be_modified new)

fix(agent): correct the secret scanners and the content sanitizer

Bug: Tool output such as a git log, a package.json or an npm error is no longer reported as a leaked secret

The agent's scanner for secrets in tool output took any web address for a connection string with a password as soon as a colon and an at sign appeared anywhere after it, even several lines later. A git log with a link and an author address, a package manifest or an npm error was reported as a leaked secret, and where the scanner's redaction is applied everything from the link to the word after the at sign was replaced by a marker. A connection string is now a URL whose user and password stand directly in front of the host; the user may be an e-mail address, or empty. (The first version of this change did not take a password that holds a slash; the first review found that, and since the commits after it the password may hold one, in both scanners. A URL without a password is left as it is only when its host has a port and the first at sign behind the port begins a path segment.) An AWS access key pair (key id, colon, the 40 characters of the secret) is replaced wherever it stands, and a URL whose user is an access key id is replaced as a whole, also when its password holds a slash, as nearly half of all secret keys and of the SMTP passwords of Amazon SES do. A URL whose password position holds a placeholder and nothing else ({password}, ${DB_PASSWORD}, %s, ) is left as it is: it is a template in source code or documentation, not a credential, and since the agent reads files through this scanner, a marker in place of such a line kept the agent from editing the line and could reach a pull request.

Gain: Ordinary tool output (a git log, a package.json, a README, an npm error) is no longer reported as a leaked secret, and no part of it is replaced by a marker in what the agent reads. The pattern also stops being quadratic in the number of URLs (3,000 URL lines, 190 KB: about 1 s before, 5 ms now, measured here); tool output is usually far shorter, so that is a safety margin, not a visible speed-up. A key id followed by a colon and its secret is now replaced as a pair outside URLs as well, where only the key id used to be. The agent can read and edit a line that builds or documents a URL with a placeholder in the password position ({password}, ${DB_PASSWORD}, %s, ), and writes no marker into the repository through it: in 2,422 fragments of public code sampled for this change, 785 of the 1,353 URLs with a user and a password that the scanner replaced were such templates.

Test: agent/tests/test_output_scanner.py > TestScanToolOutput::test_clean_url_followed_by_an_email_address, ::test_clean_url_with_port_and_scoped_package, ::test_detects_connection_string_with_an_email_address_as_user, ::test_detects_aws_key_pair_in_a_url, ::test_url_with_an_aws_key_id_as_user_is_replaced_as_a_whole (5 cases), ::test_longer_run_after_an_aws_key_id_is_not_its_secret, ::test_url_template_with_a_placeholder_password_is_left_as_it_is (15 lines), ::test_same_url_with_a_password_in_the_place_of_the_placeholder_is_replaced (7 lines), ::test_password_that_is_not_one_placeholder_and_nothing_else_is_replaced (20 passwords), ::test_placeholder_password_after_an_aws_key_id_is_no_template; cdk/test/handlers/shared/deny-reason-scanner.test.ts > 'redacts a connection string whose user is an e-mail address', 'redacts an AWS key pair in a URL, with slashes in the secret', 'replaces a URL whose user is an AWS key id as a whole, with ...' (5 cases), 'does not take a longer run after an AWS key id for its secret', 'counts a character outside the BMP once in both length limits, as the agent's scanner does', 'leaves a URL template with a placeholder password as it is: ...' (15 lines), 'replaces the same URL with a password in the place of the placeholder: ...' (7 lines), 'replaces a password that is not one placeholder and nothing else: ...' (20 passwords), 'takes a placeholder password after an AWS key id for no template'

Bug: Temporary AWS key ids (ASIA) are redacted in tool output, longer GitHub tokens in a deny reason

Two secret scanners that say they mirror each other did not detect the same things. The agent's scanner of tool output knew long-term AWS access key ids (AKIA) but not temporary ones (ASIA), the kind every role session has, the agent's own included. The scanner for the reason of a denied approval matched GitHub tokens of exactly 36 characters only, so a token of a longer format stayed in the text. Each side now matches what the other already did.

Gain: A temporary AWS access key id in tool output is flagged and redacted like a long-term one. A longer GitHub token typed into a deny reason is redacted before the reason is stored on the approval record and in the audit event (kept 90 days by default) and before it is shown to the agent.

Test: agent/tests/test_output_scanner.py > TestScanToolOutput::test_detects_temporary_aws_access_key; cdk/test/handlers/shared/deny-reason-scanner.test.ts > 'redacts a GitHub token longer than 36 characters'

Lean (delete): The repeated error handling around a user's nudge is gone: 44 product lines and two lint suppressions

The code that hands a user's nudge to the running agent handled the same errors three times. Marking a nudge as consumed carried two branches that only served hand-made exception classes of its own tests, and a guard against the AWS SDK not being installed, which is a pinned dependency. The hook around it wrapped three calls in more try/except blocks, two of them with a suppression of the silent-failure lint rule, although two of the calls catch every error themselves and the third only formats strings. The extra layers are removed; what the functions return is the same for every input.

Gain: 44 lines of product code and 17 lines of test code removed (net), two suppressions of the silent-success-masking rule and two coverage-exclusion comments gone. The 8 statements of the nudge hook that no test could reach no longer exist.

Test: agent/tests/test_nudge_reader.py > TestMarkConsumed, agent/tests/test_nudge_hook.py and agent/tests/test_cancel_hook.py: 56 tests that pass on the committed code and on the new code

Test: An emulator test fails when the nudge reader's DynamoDB filter or its consume-once condition is wrong

The agent's reader for user nudges sends DynamoDB two expressions: a filter that selects the nudges not yet consumed, and a conditional update that marks a nudge consumed only once. Both had only ever run against a mock that returns what the test scripted, so a wrong filter value or condition passed every test while nudges stopped arriving, or came again after a restart. A test in the emulator tier now runs the reader against DynamoDB semantics: of a pending nudge, a consumed one and the rate-limit row that share the table, it reads the pending one alone, consumes it once and reads nothing afterwards.

Gain: The read and the write of the nudge feature are checked by the service's own evaluation of their expressions, including the alias that the reserved word 'consumed' needs. Both mutations the finding names fail the new test (a wrong filter value returns no nudge, a wrong condition marks none), and all 44 agent tests of the emulator tier pass with the extended fixtures.

Test: agent/tests_emulator/test_nudges.py > TestNudgeDelivery::test_a_pending_nudge_is_read_and_then_consumed_exactly_once

Risk: The sanitizer removes control characters and direction marks before it looks for injection phrases

The sanitizer for outside text (issue and pull-request bodies, comments, memory records) removed control characters, text-direction marks and stray byte order marks only after it had looked for instruction prefixes, injection phrases and HTML tags. One such invisible character inside 'SYSTEM:', inside 'ignore previous instructions' or inside a script tag hid it from the check and was then removed, so the text reached the prompt intact. Both copies of the sanitizer, Python and TypeScript, now remove these characters first.

Gain: An instruction prefix, an injection phrase or a dangerous tag can no longer be slipped past the sanitizer with a character the sanitizer itself deletes, and sanitizing text that is already sanitized changes nothing for these inputs, which the agent's models rely on. Output changes only for text that contains such characters.

Test: agent/tests/test_sanitization.py > TestInvisibleCharactersHideNothing::test_pattern_is_neutralized_in_one_pass (4 cases); cdk/test/handlers/shared/sanitization.test.ts > 'neutralizes a pattern hidden by ..., in one pass' (the same 4 cases)

Test: A test fails when the clarification tool or its question parameter is renamed or its handler breaks

The test that claimed to check the registered clarification tool built a second tool of its own and checked that one, so the real tool's name, its question parameter and its handler were never tested. Renaming the tool or its parameter passed every test while breaking the feature that lets the agent hold a task and ask the requester a question. The test now captures the tool that is really registered and checks the name the runner matches on, the parameter the runner reads and the reply of the handler.

Gain: The contract between the tool and the runner is pinned: renaming the tool, renaming its parameter or breaking its handler now fails a test (each was tried and reverted). A test that could not fail is replaced by one that can.

Test: agent/tests/test_clarification_tool.py > TestClarificationTool::test_registered_tool_is_the_one_the_runner_reads

Bug: AWS secret keys and URL passwords are redacted from deny reasons, new GitHub App tokens by both scanners

The scanner that redacts secrets from the reason a user gives when denying an approval is described as a port of the agent's output scanner, but its patterns were narrower. A quoted AWS secret key, one in the JSON form that 'aws sts' prints, one ending in a slash, the secret of an AWS key pair in a URL, a database URL with a password, a git URL carrying a token, a short fine-grained GitHub token and a bearer token after 'BEARER' in capitals all passed through unredacted. The port now redacts all of these, as the agent's scanner does, and the agent's scanner gains the Slack token pattern that only the port had. Both scanners also learn the format of the GitHub App installation tokens that GitHub issues since 2026 (ghs_, the app id, an underscore and a JWT, about 520 characters): neither recognised such a token in an assignment, as a JSON value or after 'Authorization: token'. The pattern for a token in a git URL, quadratic in both scanners on text that repeats 'x-access-token:', is now linear and takes a token of any length. In both scanners a URL whose user is an AWS access key id is replaced as a whole, and one whose password position holds only a placeholder is left as it is.

Gain: A secret pasted into a deny reason in any of these shapes is no longer written to the approval record, kept in the audit event (90 days by default) or injected into the agent's context. Tool output that holds a Slack token is now recognised by the agent's scanner. A text that repeats 'x-access-token:' no longer costs quadratic time: 100,000 such characters took 391 ms in the deny-reason scanner and 1.8 s in the agent's scanner, and take 10 ms and 35 ms now (measured here). A GitHub App installation token of the format that GitHub issues by default since October 2026, which is also the format of the GITHUB_TOKEN of a GitHub Actions run, is replaced when it shows up in tool output or in a deny reason; until now only the 40-character format was. The platform's own GitHub access is a personal access token today and is planned to become a GitHub App, whose tokens have this format. A deny reason that quotes a line of code with such a URL template reaches the agent as it was written.

Test: cdk/test/handlers/shared/deny-reason-scanner.test.ts > 'redacts ...' (10 shapes, test.each), 'replaces a URL whose user is an AWS key id as a whole, with ...' (5 cases), 'leaves a URL followed by an e-mail address alone', 'redacts a long GitHub App token in a git remote URL', 'takes text with a colon for a git remote URL token up to 512 characters', 'counts a character outside the BMP once in both length limits, as the agent's scanner does', 'redacts a stateless GitHub App installation token in ...' (4 forms), 'leaves the other patterns their match of a stateless token ...' (2 cases), 'does not take "ghs_" and digits alone for a token: ...' (2 cases); agent/tests/test_output_scanner.py > TestScanToolOutput::test_detects_stateless_app_installation_token (4 forms), ::test_stateless_app_token_leaves_the_other_patterns_their_match (2 cases), ::test_ghs_prefix_and_digits_alone_are_not_a_token (2 cases), ::test_detects_slack_token, ::test_detects_long_app_token_in_remote_url, ::test_text_with_a_colon_is_a_remote_url_token_up_to_512_characters

fix(agent): keep session-only .mcp.json edits out of pull requests

Bug: Pull requests no longer carry the agent's session-only edit of a tracked .mcp.json

Before a session starts, the agent removes any Linear MCP server from the repository's .mcp.json and, on Jira tasks, adds a placeholder entry to it. Both edits are meant for that session only, but when the repository tracks the file, the commit the platform makes at the end of a task to save uncommitted work picked the edit up, and the push put it into the pull request. The agent now tells git to ignore its own edit of a tracked .mcp.json, so the edit stays out of every commit.

Gain: Pull requests no longer carry the platform's own change to a tracked .mcp.json: the team's Linear server removed (or the whole file deleted), or a dead Jira placeholder added on Jira tasks. Before, the commit that saves uncommitted work at the end of a task included that change when the tracked file named a Linear server or the task came from Jira, unless the agent had already committed the file itself. A task that only answers a question is no longer reported as a code update, and git rebase starts again in those clones (it refused because of the modified file) as long as the commits it moves onto leave .mcp.json alone. Limits, the first two shared with tasks that load registry MCP servers: when the platform rewrote the file and the branch to merge or rebase onto changed it too, git still stops and git stash no longer clears the way; a task that is itself asked to change .mcp.json on such a repository cannot commit that change with git add or git commit -a; a .mcp.json that is a symlink to another tracked file is not covered.

Test: agent/tests/test_channel_mcp.py > TestSessionEditStaysOutOfCommits > 'test_scrubbed_file_is_not_staged', 'test_removal_of_a_linear_only_file_is_not_staged', 'test_jira_entry_is_not_staged' (red today), 'test_file_the_repository_does_not_track_stays_untracked' (pins the design)

Bug: A .mcp.json in a legacy encoding or UTF-16 no longer fails the task; its two identical readers are one

A .mcp.json saved in a legacy encoding such as Windows-1252, or as UTF-16, made the agent's reader raise an error it does not catch, and every task on that repository failed, after the clone and the baseline build had already run. The reader now decodes the file the way the Claude CLI does (a byte that is not UTF-8 becomes a replacement character), and a file that still cannot be parsed is skipped with a warning, as the reader always promised. The registry loader had an identical copy of the reader; it now uses the same function.

Gain: Tasks on such repositories run instead of failing once the clone, the install and the baseline build are done. The Linear scrub also sees the servers of a legacy-encoded file, which the CLI does load. One reader instead of two identical copies: the registry loader is 18 lines shorter.

Test: agent/tests/test_channel_mcp.py > TestStripLinearMcpServers > 'test_scrubs_a_file_saved_in_a_legacy_encoding', 'test_utf16_file_is_ignored_not_fatal'

Risk: A .mcp.json that starts with a byte-order mark is read: its Linear server is removed, the others kept

A .mcp.json that starts with a UTF-8 byte-order mark (written by Windows PowerShell 5 or Visual Studio) is read by the Claude CLI, but the agent treated it as broken JSON. The Linear scrub then removed nothing from it, and a Jira task or a registry asset replaced the whole file instead of adding to it. The agent now drops the mark when it reads the file, as the CLI does.

Gain: The rule that the agent has no Linear MCP tools now holds for files saved by Windows tools: before, such a file kept its Linear server while the Linear token was exported, with only a warning that read as if the file were ignored. Jira tasks and registry assets keep the repository's other MCP servers instead of dropping them for the session.

Test: agent/tests/test_channel_mcp.py > TestStripLinearMcpServers > 'test_scrubs_a_file_that_starts_with_a_byte_order_mark'; TestJiraMerge > 'test_keeps_the_servers_of_a_file_with_a_byte_order_mark'; agent/tests/test_registry_loader.py > TestApplyMcpAssets > 'test_preserves_servers_of_a_file_with_a_byte_order_mark'

Bug: A refused connection, timeout or error answer of the Gateway is one warning that names the real cause

The Gateway bridge sorts a failed call into an expected hiccup (a warning) or an unexpected fault (an agent error) by the type of the exception. The MCP client hands every failure over wrapped in an exception group, so every failure was logged as an unexpected agent error, and both the log and the model saw only 'unhandled errors in a TaskGroup'. The bridge now unwraps a group that holds one error and classifies and reports that error.

Gain: A refused connection, a timeout or an error answer of the Gateway shows up as one warning with its real cause instead of an agent error without one, and the model reads the cause as well. A missing or ambiguous federated tool, the one message that names a deployment fault, is reported with the tool names the Gateway does expose. One routine failure is still logged as an agent error without its cause: a request that times out and is answered late, while the session is being closed, is reported as 'BrokenResourceError'. Apart from that the agent error stream stops collecting routine hiccups. Two identical return blocks became one; the function is no longer than before.

Test: agent/tests/test_gateway_tools.py > TestRepoConfigImpl > 'test_expected_error_inside_exception_groups_logs_warn_with_its_cause', 'test_unexpected_error_inside_an_exception_group_is_logged_with_its_cause'; TestRealMcpTypes > 'test_refused_connection_is_an_expected_error_reported_with_its_cause' (mcp's real client)

Bug: A Gateway that never answers the handshake holds a tool call for 20 seconds instead of 300

The bridge allows 20 seconds for one round-trip to the Gateway, but only the tool call had that limit. The handshake and the tool listing had none, so a Gateway that accepted the connection and then never answered held the model's tool call until the HTTP read timeout of 300 seconds. The limit is now set on the session, which applies it to every request.

Gain: A Gateway that does not answer the handshake costs the agent 20 seconds instead of 300 inside one tool call. The same holds for a stalled tool listing as long as the Gateway still answers the request that closes the session; if it has gone silent altogether after the handshake, closing the session still waits for the HTTP read timeout, as before. One argument moved, no new setting, 2 lines fewer.

Test: agent/tests/test_gateway_tools.py > TestRealMcpTypes > 'test_gateway_that_never_answers_the_handshake_is_given_up_on' (mcp's real client); TestCallGateway > 'test_opens_session_lists_and_calls_matched_tool' (assertion moved)

Bug: A 200 answer to a Linear reaction whose body is not a JSON object no longer fails the task

The helper that posts reactions on a Linear issue promises to swallow every failure, but an HTTP 200 whose body is not a JSON object (an HTML page from a proxy, or 'null') raised out of it. At the end of a task that turned a delivered task into FAILED; at the start it failed the task before the clone. Such an answer is now logged as a warning and treated like any other failed reaction, as the Jira helper already does.

Gain: An answer with status 200 whose body is not a JSON object can no longer fail a task whose work is delivered, or one that has not started. Linear and Jira treat that input the same way.

Test: agent/tests/test_linear_reactions.py > TestFailureIsSwallowed > 'test_200_without_a_json_object_does_not_raise' (5 cases: html, null, list, number, string)

Bug: The agent logs a Jira rate limit (HTTP 429) as transient, as the Lambda does, not as a rejected request

When Jira rate-limits the app, the Forge proxy passes the HTTP 429 through. The agent logged that as a request the proxy refuses for good (ERROR, JIRA_APP_ACTOR_PROXY_REJECTED), while the Lambda copy of the same rule logs it as transient (WARN, JIRA_APP_ACTOR_PROXY_TRANSIENT). The agent now classifies a 429 as transient as well.

Gain: The two copies of the rule agree. An operator who searches the agent log for REJECTED to find configuration faults (bad signature, invalid payload) no longer finds rate limits. Only the log level and the id change; nothing is retried differently.

Test: agent/tests/test_jira_reactions.py > TestStartComment > 'test_rate_limit_from_the_proxy_is_logged_as_transient'

fix(agent): gate a force push written with the flag after the branch

Lean (delete): Five names in the policy engine that nothing reads are deleted, with two tests: 20 lines fewer

The policy engine carried five names that nothing reads: a constant listing the two rule tiers, a length method on the memory of recent denials, the category annotation copied into each parsed rule (the category that bgagent policies shows comes from the API handler, which parses the rule text itself), a task_type property that only its own two tests read, and an empty default for a parameter that every caller passes. All five are deleted, together with the two tests of the property. Nothing behaves differently.

Gain: 20 lines removed net (10 of product code, 10 of tests). The engine exposes one property and one method fewer, and two internal functions lose a fallback that could never be reached.

Test: No new test (a deletion). agent/tests, whole unit suite: every test passes except the two deleted tests of the property (test_policy.py::TestTaskTypeProperty).

Risk: The built-in rule that refuses rm -rf of an absolute path refuses rm -fr as well

A built-in rule refuses rm -rf / and rm -rf of any other absolute path, and no approval can lift it. It recognised that one spelling: with the two flags the other way round, rm -fr / and sudo rm -fr /var/lib/app were allowed. The rule now matches -rf and -fr. It remains a match on these two spellings of the command text, not a parser of the command.

Gain: The absolute rule against deleting from the root no longer depends on which of -rf and -fr is typed. Nothing else changes: the new pattern matches the text rm -fr / wherever it stands in a command, exactly as the old one matches rm -rf /. So rm -fr /tmp/build is refused like rm -rf /tmp/build, and so is a commit message or a grep that contains those characters, as it already was with -rf. One pattern added to the rule and to its TypeScript copy.

Test: agent/tests/test_policy_builtin_rules.py > test_rule_catches_the_call_it_exists_for, rows 'rm_slash: Bash rm -fr /' and 'rm_slash: Bash sudo rm -fr /var/lib/app' (12 parameter sets: three task types, read-only or not)

Bug: A force push asks for approval also when --force follows the branch or -f ends the command

A force push has to be approved by a human, but the built-in rule recognised the force flag only directly after git push. With the flag after the branch (git push origin feature --force, --force-with-lease, git push origin feature -f) the push ran without a question, even right after a human had denied the same push written the other way round. The rule now also matches --force anywhere after git push, and -f as the last word of the command. Later commits of this pull request add -f after the branch at the end of a line and before ;, &, |, > and 2>, and git push -f whatever follows the flag. Side effects. The rule reads the command as text, so a command in which git push is followed later by --force asks for approval too, whether that is the flag of another program (git push origin x && npm install --force) or words in a message (a push chained with gh pr comment --body "... --force ..."), and so does one that pushes and ends in -f (git push origin x && git clean -f). In a task where rule:force_push_any is approved (--pre-approve, or bgagent approve --scope), a force push to main, master, prod or release/* typed with the flag last no longer asks: until now it asked as a push to a protected branch, while the same push typed git push --force origin main was already allowed by that approval. That holds for every command the widened rule now matches, a plain push to main followed by a program with --force included.

Gain: A denied force push can no longer be repeated by moving --force or --force-with-lease behind the branch, or by putting -f last in the command: for a minute after the denial the retry is refused at once, afterwards it asks again (before: allowed without a question). A force push typed that way now asks for approval at all. The rule remains a match on the command text, not a parser of git's command line. Two patterns added to the rule and to its TypeScript copy.

Test: agent/tests/test_policy_builtin_rules.py > test_rule_catches_the_call_it_exists_for, the four new force_push_any rows (24 parameter sets), and ::test_force_push_rule_leaves_the_flag_of_a_later_command_alone

fix(agent): pick the right branch and repository during repo setup

Bug: A child task whose predecessor branch was merged and deleted aims its pull request at the default branch

A stacked child task whose predecessor had already been merged, with its branch deleted, was started from the default branch, but its pull request was still aimed at the deleted branch. The agent could not open that pull request, the platform then had nothing to compare the work against, and the task failed as a lost deliverable although the commits existed. The pull request now targets the repository's default branch, the branch the child was actually cut from.

Gain: Bug fixed: a child task that starts after its predecessor was merged delivers its work as a pull request against the default branch, instead of failing after a complete agent run with a reason that says nothing was committed. Affects every orchestrated chain in which a predecessor is merged, and its branch deleted, before the next child starts.

Test: agent/tests/test_repo.py > TestStackedChildWithRealGit::test_child_whose_base_is_gone_targets_the_default_branch

Bug: Setup checks out a pull request whose branch is the default branch, and refuses one that comes from a fork

A review or iteration task on a pull request whose branch is the repository's default branch (a release pull request from develop into main) failed during setup with a git error, because the clone had already created that branch. Setup now checks the branch out. It first asks GitHub whether the pull request comes from a fork, because a fork's branch with the same name (a fork's main) is a different branch: without the question, setup would work on the repository's own branch and an iteration would push to it. Such a pull request is refused with a clear reason.

Gain: Reviews and iterations no longer fail in setup on pull requests opened from the default branch (release, promotion and sync pull requests) with a git error nobody can act on. The fix opens no way to work on the wrong branch: a fork's pull request with that branch name is refused. Every pull request task pays one GitHub call for it: GitHub is asked about every pull request, whatever its branch is called (at first only when the branch was named like the default branch; changed after the first reviews), and the call is retried like the clone and the fetch.

Test: agent/tests/test_repo.py > TestPullRequestBranch::test_pr_branch_is_checked_out_with_real_git[default-branch] and [other], ::test_pr_from_a_fork_is_refused_before_its_branch_name_is_fetched, ::test_fork_check_without_an_answer_stops_setup_like_a_failed_fetch, ::test_pr_from_the_repository_itself_passes_the_fork_check

Bug: When the GitHub call for the default branch fails, setup reads it from the clone instead of assuming main

When the GitHub API call that asks for a repository's default branch failed (a timeout, a server error, a rate limit), setup assumed 'main'. On a repository whose default branch is master or develop the task then ran to the end and could not deliver, or opened its pull request against a stale main. Setup now reads the default branch that the clone has already recorded locally, and falls back to 'main' only when that is missing too.

Gain: A passing GitHub API failure during setup no longer costs a full agent run on repositories whose default branch is not main, and no longer sends a pull request to the wrong branch. No extra network call: the answer is read from the clone.

Test: agent/tests/test_repo.py > TestDetectDefaultBranch::test_gh_failure_falls_back_to_the_default_branch_of_the_clone[timeout], [gh-missing], [non-zero-exit]

Risk: In a fork, the agent's gh commands act on the task's repository, not on the parent project

When the task's repository is a fork, the GitHub CLI clone added the parent repository as a second remote and made it the default target of every later gh command that does not name a repository. An agent working in a fork (the Quick Start has every new user onboard one) could therefore read, review or comment on the parent project's pull requests instead of its own. The clone now passes --no-upstream, so the task's repository is the only remote and the default target.

Gain: In a fork, the agent's gh commands act on the task's repository whether or not the model writes --repo: no review of another project's pull request, no comment or pull request on the parent, no permission errors from the parent on the Quick Start path. The clone also stops fetching the parent repository, a second download that could fail the clone step. One argument changed.

Test: agent/tests/test_repo.py > TestSetupRepoHappyPath::test_clone_adds_no_upstream_remote_for_a_fork

Risk: A stacked child finds its base and predecessor branches in the clone, so a failed fetch cannot drop them

A stacked child task fetched its base branch, and each predecessor branch it merges, a second time right after cloning, and took any failure of that fetch to mean the branch was gone. One network error was enough to start the child from the default branch, or without one of its predecessors, with only a setup note to show for it. The clone already holds every branch, so setup now looks the branch up there and falls back only when the branch really does not exist.

Gain: A network error at setup can no longer make a stacked child start from the wrong base or without a predecessor's code. One network call fewer for the base of every stacked child, and one fewer for each predecessor branch that is merged.

Test: agent/tests/test_repo.py > TestStackedChildWithRealGit::test_child_branches_from_its_predecessor_when_the_connection_drops, ::test_predecessor_is_merged_when_the_connection_drops

fix(agent): harden run_cmd output handling, timeouts and log redaction

Bug: Command output with a byte that is not UTF-8 no longer fails a passing build or crashes setup

A command whose output contained one byte that is not valid UTF-8 (a compiler quoting a source line in Latin-1, a test printing raw bytes) broke the agent's reading of that output. For build and lint commands the rest of that stream was lost, and a command that does not survive a closed pipe ended the next time it wrote to it, so a passing build was reported as failed (a shell: exit 141); for setup commands such as mise install the task crashed with a decoding error. Such a byte is now logged as a replacement character and the command runs on to its own exit status.

Gain: Repositories whose build prints legacy-encoded text or binary test output are judged by the real result of their build, and all of that output reaches the log. Before, a repository whose build went on writing after such a byte and did not survive the closed pipe was hit on every task, because a build prints the same bytes on every run: either the build after the agent's change was reported as failed, or the build before it was recorded as already failing, which excuses a failure the agent introduces. Two arguments in the product code, two tests.

Test: agent/tests/test_shell.py > TestRunCmdUndecodableOutput > test_streamed_command_keeps_its_output_and_its_exit_status, test_buffered_command_returns_instead_of_raising

Bug: On a timeout the whole process group of a build or lint command is told to stop, not only the command

When a build or lint command reached its time limit, the agent killed only the process it had started. What that process had started in turn (compilers, test runners) kept running in the checkout while the agent carried on, using memory and CPU and possibly still changing files, and where those processes held the output pipes open the timeout was reported 20 seconds late. The command now runs in a process group of its own; on timeout the whole group is asked to stop and, if the command is still there 10 seconds later, killed.

Gain: After a timeout the processes the build had started are stopped together with it instead of competing with the agent and with the later verification build. Measured in an agent image with mise 2026.9.1 (the Dockerfile pins 2026.11.6, whose source was read, not run) with a mise build of two tasks: 5 of its processes were still running after the timeout before, none now, while a build that ends because one task fails behaves as before (2 seconds, nothing left). Measured with a shell command that starts a background process: the timeout is reported after 1.0 s instead of 21.0 s. Still not reached, as before: a process that ignores the request to stop while the command itself ends on it, and a process in another process group that its build tool does not stop (a daemon, for example).

Test: agent/tests/test_shell.py > TestRunCmdStreaming > test_stream_timeout_stops_the_command_and_what_it_started, test_stream_timeout_kills_a_command_that_does_not_stop, test_stream_command_gets_a_process_group_but_not_a_session_of_its_own

Bug: The failure summary of a red build keeps the totals line when a count ends in 0, such as '10 failed'

For a failed command the agent logs a short block of the lines most likely to explain the failure. The filter that keeps harmless lines such as '0 failed' out of that block compared text fragments, so the line with the totals was dropped exactly when the count ended in 0 ('10 failed', '20 errors', '100 problems'). The block also said 'more failure lines truncated' when exactly 40 lines matched and nothing had been left out. Counts are now compared as whole numbers, and the truncation note appears only when a line was really left out.

Gain: The summary an operator reads first on a red build shows the totals line of jest, pytest or eslint also when 10, 20 or 100 tests fail, and no longer sends the reader looking for lines that do not exist. Log output only: what the build gate decides does not change.

Test: agent/tests/test_shell.py > TestRunCmdFailureLogging > test_totals_line_with_a_count_ending_in_zero_is_surfaced (jest, pytest, eslint), test_no_truncation_breadcrumb_when_every_failure_line_is_shown; guard for the rewrite: test_a_count_of_zero_is_still_noise

Risk: The agent's log redactor replaces the values of its GitHub, Linear and Jira credentials wherever they appear

Every agent log line passes through a redactor that knew the shapes of GitHub tokens only. The Linear token, the Jira token and the signing secret of the Jira app are in the environment of every repository command, so a build step that prints its environment, or the agent running printenv, wrote them into the log in cleartext. The redactor now also replaces the values of the credentials the agent holds (GitHub, Linear, Jira, the Jira app secret) wherever they appear, and log previews are redacted before they are cut to length, so that the first part of a cut value does not get through. A GitHub App installation token of the format GitHub issues since October 2026 (about 520 characters, with dots in it) that is not one of those values, for example the token of another installation that a build step prints, was replaced only up to its first dot, unless it stood behind 'Authorization: Bearer', behind 'x-access-token:' or in a token parameter of a URL, so that most of it stayed in the line; the rule for such a token now runs on through its dots and dashes.

Gain: The Linear and Jira credentials and the signing secret of the Jira app no longer reach CloudWatch through build output, previews of tool results or error messages, and the agent's own GitHub token is covered whatever its shape. About 35 lines added in shell.py: the redactor, its constants and truncate().

Test: agent/tests/test_shell.py > TestRedactSecrets > test_value_of_a_credential_the_process_holds (5 variables), test_short_value_of_a_credential_variable_is_left_alone; TestTruncate > test_credential_is_redacted_before_the_cut_can_split_it; TestRunCmdStreaming > test_stream_redacts_a_credential_printed_from_the_environment (through the real log()); follow-up for GitHub App tokens of the stateless format: TestRedactSecrets > test_github_app_token_of_the_stateless_format (4 forms), test_rest_of_a_token_goes_whatever_prefix_of_the_first_rule_it_has (4 prefixes), test_token_in_three_parts_with_a_prefix_only_the_catch_all_rule_knows; guards: test_keyword_behind_a_token_is_still_seen_by_its_own_rule, test_prefix_without_a_token_behind_it_is_left_alone

Scale: The agent keeps the last 200,000 output lines of a build or lint command in memory instead of all of them

For build and lint commands the agent writes every output line to the log and also kept a complete copy of the output in memory: 235 MB at the end of a command that printed 80 MB. A build that floods its output, for example a test that retries in a loop and logs every attempt, could therefore use up the memory of the session before the build time limit ended it. The copy now keeps the last 200,000 lines of each stream; the log still gets every line. Of a longer output the failure summary and the checks on the error output see only that end.

Gain: The copy the agent keeps of a streamed command's output is bounded in lines: for one million 80-character lines (80 MB of output) the peak memory of the process fell from 235 MB to 70 MB, and more lines no longer add to it. A runaway build that prints lines of ordinary length ends at the build timeout, which the pipeline handles, instead of exhausting the session. Lines are kept whole, so very long lines still count in full: 250,000 lines of 2,000 characters cost about 800 MB at the peak.

Test: agent/tests/test_shell.py > TestRunCmdStreaming > test_keeps_only_the_end_of_a_long_output

fix(agent): correct what the pipeline reports when a task ends

Bug: A build whose command could not run is recorded without a verdict and shown as NOT RUN, not PASSED

When a repository's build command could not run at all after the agent had finished (yarn missing from the image, or no such build task), the task rightly did not fail for it, but the task record stored build_passed = true, and a pull request that the pipeline opened itself (it does that only when the agent has not opened one) said the build PASSED. The task record now stores no build verdict, which is how a build that did not run is already recorded, and such a pull request says NOT RUN (command could not run). Whether the task succeeds does not change. Two places that read the same value no longer count such a build as passed: the build.passed attribute of the task's root span, and the Build Pass Rate widget of the dashboard, which leaves a build without a verdict out of the rate (the widget's query is corrected by another change of this pull request).

Gain: The task record, and a pull request opened by the pipeline, no longer show a green build for code that was never built, so a missing tool or a mistyped Blueprint build command no longer looks verified there. A pull request that the agent opens itself carries no build status from the pipeline, before or after. The image notes of this project record that this happened while it ran on its own repository.

Test: agent/tests/test_pipeline.py > TestInertBuildIsNotReportedAsPassed::test_task_succeeds_and_the_build_is_reported_as_not_run; agent/tests/test_post_hooks.py > TestEnsurePrCreate::test_build_that_could_not_run_is_not_reported_as_a_pass

Bug: A task stopped at its turn limit records the limit as completed turns (100), not one more (101)

The number of completed turns of a task is meant to be capped at its turn limit, because the agent SDK also counts the attempt it aborts when the limit is reached. The cap depended on a status value that the agent never reports for a task stopped at its limit (it reports a plain error), so it was never applied. It now applies whatever the status: a task that hits a limit of 100 turns records 100 completed turns, not 101.

Gain: Bug fixed for every task that hits its turn limit: turns_completed in the task record, the figure the web console shows, is now the limit and no longer one more (101 of 100). turns and turns_attempted keep the raw count on purpose, so the Linear and Jira completion comments still show 101. One parameter and one branch removed.

Test: agent/tests/test_pipeline.py > TestTurnsCompletedAtTheCap::test_max_turns_stop_is_clamped_to_the_cap

Bug: A Linear issue moves to In Review only when the run has a pull request, as the Jira card does

When a task that came from Linear ended with the agent asking the requester a question instead of doing the work, the Linear issue was moved to In Review although there was no pull request, next to the platform's comment saying the agent has a question before it starts. The issue now moves to In Review only when the run has a pull request, the rule the Jira card already follows.

Gain: A Linear board no longer shows an issue as ready for review while the agent is waiting for the requester's answer. Hit every clarify-and-hold run that came from Linear.

Test: agent/tests/test_pipeline.py > TestLinearIssueAtTerminal::test_hold_for_input_does_not_move_the_issue_to_in_review

Bug: A build killed for lack of memory or disk no longer fails a read-only task such as a review

A read-only task, such as a pull request review, still runs the repository's build after the agent has finished, for information only. When that build was killed because the machine ran out of memory or disk, the task was reported as failed although the review had already been posted. A build killed by the machine no longer fails a read-only task; for a task that changes code it still does, because that code could not be verified.

Gain: Reviews of large repositories stop being reported as failed after the review was delivered. Most exposed is the ECS backend, where read-only tasks run on the smaller 8 GB task while the full build still runs there.

Test: agent/tests/test_pipeline_post_hook_gates.py > TestRunTaskHonorsGate::test_read_only_workflow_survives_a_build_killed_by_the_host

Bug: After a failed push the task reports work that was not delivered, not a commit safe on the branch

When a task ended without a pull request, the agent decided between 'the commit is on the branch, only the pull request is missing' and 'nothing was delivered' by looking at its local checkout. After a failed push it therefore reported the first, and the platform told the user that the push had succeeded, that the work was safe on the branch and that an admin could open the pull request from it, although the branch did not exist on GitHub. The agent now looks at what was pushed, so a failed push is reported as work that was not delivered.

Gain: Users are no longer told that their work is safe on a branch that was never pushed, or sent to open a pull request from it. Affects tasks whose push is refused or fails: a token that may not push, branch protection, a change to workflow files without the workflow permission.

Test: agent/tests/test_pipeline.py > TestDeliveryGateReadsThePushedBranch::test_commit_that_was_never_pushed_is_reported_as_lost

Bug: Only a dry run prints 'Dry run mode detected.'; the DEBUG_DRY_RUN_PROMPTS switch that did nothing is gone

Every local batch run of the agent printed 'Dry run mode detected.', also when it was a real run. A dry run printed the length and hash of each prompt with a hint to set DEBUG_DRY_RUN_PROMPTS=1 'to print full text', and setting it only printed that printing is disabled. The message now appears for dry runs only, and the hint and the switch that did nothing are gone.

Gain: A real run no longer announces itself as a dry run, and nobody is sent to a switch that does nothing. 14 lines removed from the batch entry point, which also gets its first two tests.

Test: agent/tests/test_pipeline.py > TestBatchEntryPoint::test_real_run_does_not_announce_a_dry_run; TestBatchEntryPoint::test_dry_run_prints_the_length_and_hash_of_each_prompt

Bug: An agent that notices its task was cancelled replaces the eyes on the Linear issue with a cross

When a user cancelled a task that came from Linear, the eyes reaction the agent had put on the issue at the start stayed there, so the issue looked as if the agent were still working on it, next to the platform's 'Task cancelled' comment. When the agent is still running at the point where it notices the cancellation, it now replaces the eyes with a cross, as it already does when it crashes. When the platform stops the container first, which it does for a task cancelled while it runs, nothing changes.

Gain: A cancelled Linear issue no longer looks in progress in the cases where the agent outlives the cancellation: a task cancelled in a state in which the platform does not stop the container, or a container it failed to stop. For a task cancelled while it runs, the platform stops the container right after it marks the task cancelled, and the eyes stay until another task starts on the same issue, as before.

Test: agent/tests/test_pipeline.py > TestLinearIssueAtTerminal::test_cancelled_task_swaps_the_eyes_reaction

@krokoko

krokoko commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor Author

Agent runtime (Python) (part 2 of 3): what changes and what it gains

fix(agent): make secret redaction of built-in tool output take effect

Bug: An approval wait is limited to the session time that is left, also for a start time with milliseconds

The agent shortens the time it waits for a human approval to the time its session has left, so that an approval cannot arrive after the session is gone. That limit never applied: the platform sends the start time of the task with milliseconds, the agent's parser accepted whole seconds only, took the start time for unknown and skipped the limit. The start time is now read with Python's ISO 8601 parser, which takes both forms.

Gain: Affects every task on AgentCore and Lambda MicroVM that reaches an approval gate late in its session. Such a gate now gets a window that fits the time left and the user is told that it was shortened; a gate that can no longer be answered in time is refused at once instead of leaving the task waiting on a session that has ended. The dashboard widget for shortened windows starts to receive data. 8 lines of product code.

Test: agent/tests/test_hooks.py > TestRemainingMaxlifetime::test_timestamp_with_milliseconds_is_parsed (and ::test_timestamp_without_a_zone_is_read_as_utc)

Bug: Secrets in the output of built-in tools are redacted before the model and the task events receive them

A hook of the agent screens tool output for secrets (AWS keys, GitHub tokens, private keys, connection strings) and hands the model a redacted copy. For the built-in tools (Bash, Read, Grep and the others) that copy never arrived: it was returned in a field that the Claude Code CLI applies to MCP tools only, and as one flat string, where the CLI accepts a rewrite of a built-in tool only in that tool's own output shape. The model and the task's events received the secret while the log said it had been redacted. The hook now redacts the strings inside the response and returns the response in its own shape, in the field the CLI honours for every tool. If the screening itself fails, the whole output of that call is replaced by a marker; that the CLI then hands the model the marker was checked for Bash, Read, Grep, Glob, Write, Edit, WebFetch and an MCP tool. Checked against the pinned Claude Code CLI 2.1.319 (claude-agent-sdk 0.2.179). The agent now sees the marker in place of anything the scanner takes for a credential in a file or a command output, the DSN with a default password in a compose file included; the file on disk is not changed.

Gain: The redacted copy that the hook returns is applied by the CLI, for the first time on built-in tools. Measured with the pinned CLI for a Bash command, a Read and a Grep whose output held a key: the model received [REDACTED-AWS_KEY], and so did the runner, which writes the agent_tool_result events and the trajectory; before, both received the key. In these cases the 'OUTPUT REDACTED' log line and the output screening event now report a redaction that really happened. The result of an MCP tool keeps its structure instead of being replaced by the text form of a Python list. When the screening itself fails, Bash, Read, Grep, Glob, Write, Edit and WebFetch hand the model a marker; before, they handed it the unscreened output.

Test: agent/tests/test_hooks.py > TestPostToolUseHook::test_redacts_a_built_in_tool_response_in_its_own_shape (and ::test_redacts_nested_and_listed_strings_and_leaves_the_rest, ::test_a_string_with_nothing_to_redact_is_passed_on_whole, ::test_a_response_that_cannot_be_scanned_in_full_is_blanked_in_full, ::test_fail_closed_keeps_what_the_schema_of_the_tool_fixes, ::test_fail_closed_does_not_claim_a_redaction_for_a_tool_it_was_not_checked_for, ::test_wrapper_fails_closed_in_a_form_the_cli_takes)

Bug: A failing tool call reaches the blocked-host detector and the stuck guard through its own hook event

When a tool call fails while it runs (for Bash: a command that exits with a non-zero status, unless the CLI knows that status as an answer, such as 1 from grep when nothing matches) the Claude Code CLI reports it through its own hook event, PostToolUseFailure, and not through PostToolUse. The agent registered PostToolUse only, so two observers of tool results never saw a failing command: the detector that reports a blocked network host together with the DNS firewall remedy, and the guard that notices an agent repeating the same failing command. The agent now registers the failure event and shows the error text of the failed call to both. A connection that fails on the machine itself (localhost, a 127.x.x.x address, 0.0.0.0) is reported as an event but is not kept as the reason of a later failure of the task.

Gain: A command that fails because its host is not on the allowlist (npm install, pip install, curl, git clone) now produces the egress_denied event that names the host, and that reason is available for the final error of the task; before, this only happened for a command that printed such an error and still exited with status 0. A check of a local dev server that is not up yet ('curl http://localhost:3000/health') writes the event and does not turn a later red build into 'egress denied for localhost'. The stuck guard receives the failures it was written to count. Checked with the pinned CLI: a Bash command that exits 1 fires PostToolUseFailure and no PostToolUse.

Test: agent/tests/test_hooks.py > TestPostToolUseFailure::test_failed_command_emits_egress_denied_with_the_host (and ::test_a_failed_connection_to_loopback_does_not_latch_the_terminal_reason and the other tests of that class)

Bug: The stuck guard gives its advisory with the third identical failure, not only when the agent stops

The stuck guard tells the agent to stop when it keeps re-running a command that fails in the same way, and it adds 'last tool calls repeated: ...' to the reason of a task that ran out of turns. Both were computed only in the hook that runs when the agent stops to answer. An agent caught in such a loop does not stop, and the CLI runs no stop hook when it cuts a run off at the turn limit: the advisory reached only agents that had already finished, and the reason was not extended. The guard is now asked after every tool result. The advisory comes back with the third identical failure, attached to that tool result, and the summary is kept current for the turn-limit reason. A call of any tool but Bash that completed is not counted as a failure, whatever its output says. What the guard quotes of a command and of its output is screened for secrets before it is cut to a preview; the strings of a tool's answer are screened one by one, so that a marker ends where its line ends. Behaviour to know: two commands, or two outputs, that differ only in what the screening replaces now count as the same failure for the guard: a credential, and with it the rest of a URL that carries a password. A success of one such command ends the streak of the other.

Gain: The loop breaker works in the case it was built for (a task that spent 100 turns and 22 minutes re-running one failing command). With the pinned CLI the model received the advisory with the third identical failure, and a run cut off at the turn limit ended with the summary naming the repeated command. An agent that has finished is no longer called back by a late advisory, which cost one turn. Reading a file that contains 'exit 1' three times with the Read tool draws no advisory: of the calls that complete, only a Bash command is still judged by its output. The summary ends up in the error message of the task, of which the failure reply on Linear quotes the first 200 characters and the failure message on Slack the first 300; the command and the output that it quotes are screened, by the scanner of tool output and by the redaction of the log lines, before they are cut to a preview, so that a credential which these two know is replaced while it is whole, wherever the cut falls (checked at every position of both cuts). Also fixed: for tools without a command or a file path (WebFetch, Grep, Glob, MCP tools) the guard took every call for the same operation; it now tells different inputs apart.

Test: agent/tests/test_hooks.py > TestPostToolUseFailure::test_third_identical_failure_returns_the_steer_to_the_model (and ::test_max_turns_summary_is_latched_without_a_stop_hook, ::test_max_turns_summary_is_screened_like_tool_output, ::test_max_turns_summary_drops_the_start_of_a_token_that_the_cut_splits, TestStuckGuardHookIntegration::test_post_tool_use_returns_the_steer_with_the_third_identical_failure, TestStuckGuardHookIntegration::test_a_completed_call_of_another_tool_than_bash_is_no_failure); agent/tests/test_stuck_guard.py > TestSignature::test_a_tool_without_command_or_path_keys_on_its_whole_input (and the class TestOutcomeGivenByTheCaller); third task: agent/tests/test_hooks.py > TestPostToolUseFailure::test_max_turns_summary_holds_no_piece_of_a_credential_wherever_the_cut_falls (and ::test_the_advisory_its_milestone_and_its_log_line_quote_the_screened_command, ::test_max_turns_summary_is_screened_again_when_it_is_read, TestSelfRecloneGuard::test_the_log_line_of_a_denied_reclone_quotes_the_screened_command)

Bug: Session scopes of an approval cover later calls of the tool or its group and are refused as pre-approvals

An approval can be given with a scope that stands for the tool whose call is waiting: tool_type_session (this tool, for the rest of the task) and tool_group_session (the group this tool belongs to). The API and the CLI accept both, but the agent did not know them: the approval covered one call, the next call asked again, and the agent log carried a warning. The same two scopes and this_call were also accepted as pre-approvals at submit, where no call is waiting, and such a task failed when the agent started. The agent now translates the two scopes into the tool or the group of the approved call, and the API and the CLI refuse the three scopes as pre-approvals.

Gain: 'bgagent approve --scope tool_type_session', the documented way to stop repeated prompts for one tool, now does what the user guide says. 'bgagent submit --pre-approve' with one of the three scopes is refused at once, by the CLI and by the API with a 400 that names the alternative (tool_type:Bash), instead of creating a task that fails when its agent starts. 5 lines less in the CLI command, 13 lines added in the API, about 20 in the agent.

Test: agent/tests/test_hooks.py > TestApprovedPath::test_tool_type_session_covers_later_calls_of_the_approved_tool (and ::test_tool_group_session_covers_the_group_of_the_approved_tool); cdk/test/handlers/shared/create-task-core.test.ts > 'rejects the pre-approval %s, which stands for a call that is waiting for approval'; cli/test/commands/submit.test.ts > '--pre-approve rejects %s, which stands for a call that is waiting for approval'

Bug: A clone of a repository whose name only contains the task repository's name is no longer refused

The agent must not clone its own task repository a second time, because work done in a second copy never reaches the pull request. The check looked for the repository name anywhere in the clone command, so cloning another repository whose name merely contains it was refused too: with the task repository acme/api, a clone of acme/api-client, of acme/api.github.io or of megaacme/api was denied with the message that the repository is already checked out. The name now has to match as a whole.

Gain: Agents that work in an organisation with repositories named 'name' and 'name-suffix' can clone the sibling repository: the five such commands of the new test were refused before and are allowed now, and the existing cases of the guard keep their result. One line of product code.

Test: agent/tests/test_hooks.py > TestSelfRecloneGuard::test_ignores_a_repo_whose_name_only_contains_the_task_repo

Since the screening of tool output takes effect for the built-in tools, the model is shown a marker where a file holds a value that the screening hides. A Write of that file from what the model saw, or an Edit whose new text restates the line, put the marker into the repository and the pull request in place of the value, without any error (measured with the pinned CLI). The hook that runs before a tool call now refuses a Write or an Edit that would add a redaction marker of the scanner to a file, before the policy is asked, and tells the model that the real value is still on disk and to change the file around that line. A marker the file holds already may stay. Gain: a value the agent was not allowed to see can no longer be overwritten by its marker. Behaviour to know: an edit that adds such a marker as text of its own (a new test of the scanner, a sentence about the marker in documentation) is refused as well, and the refusal text does not fit that case; a Bash command is not looked at. It is one self-contained check and can be taken out without touching the rest.

The entry of the stuck guard in the hook that runs when the agent stops is deleted. The two tool hooks ask the guard after every result and the guard gives each advisory once, so that entry could no longer inject anything: 3,000 random sequences with 25,366 tool results never made it speak, while the tool hooks handed out 403 advisories. Gain: 55 lines of product code and one suppression of the silent-failure lint rule fewer.

fix(agent): record cost, duration and metrics for a crashed task

Lean (delete): The pipeline's uvloop warning, which could never appear and used a deprecated asyncio call, is deleted

Before starting the agent, the pipeline asked asyncio for its event loop policy in order to warn when uvloop is active. uvloop is not installed in the agent image and the server is started with the standard asyncio loop, so the warning could never appear. The call it used is deprecated since Python 3.14 and is announced to be removed in 3.16, and the test suite treats warnings as errors. The check is deleted.

Gain: 10 lines of diagnostics that could not run are gone. On Python 3.14 or later, 41 of the 145 pipeline tests would fail on this one call (measured by simulating the 3.14 warning for it), and on 3.16 every task with a repository would crash at this point. The same deprecated call was in the server module, where it ran at import time; a later commit of this pull request removes it.

Test: No new test (a deletion). The check is the 41 existing tests of agent/tests/test_pipeline.py and agent/tests/test_pipeline_post_hook_gates.py that drive run_task up to the agent step: see red.

Bug: A crashed task shows its real duration instead of 0s and counts as a failure on the dashboard

A task whose pipeline raised an error (a failed clone, a post-hook such as the push timing out) was recorded with a duration of 0 seconds, however long it had run, and it never emitted the metrics event from which the operator dashboard counts tasks. The record of such a task now says how long it ran, and the event is emitted as for every other finished task. For a task that fails before the agent starts, the duration is the time since the pipeline started; once the agent has started it is the time since then, the same clock a completed task reports.

Gain: Tasks that crash show their real duration in bgagent status and in the web console instead of 0s, and the dashboard's success rate and task counts include them as failures instead of leaving them out. Measured with the real record writer and the real metrics emitter: nine completed tasks and three crashed ones gave 9 events and a success rate of 100 percent before, 12 events and 75 percent now (the dashboard's query text applied to the emitted lines, not run against CloudWatch). The event of a crashed task has no build or lint verdict (null); the Build Pass Rate and Lint Pass Rate widgets leave such a task out, since another change of this pull request corrects their queries.

Test: agent/tests/test_pipeline.py > TestCrashedTaskIsReported::test_setup_failure_records_how_long_the_task_ran; ::test_crash_after_the_agent_is_timed_like_a_finished_run; ::test_crashed_task_emits_the_event_the_dashboard_counts

Lean (merge): A task that fails after its agent ran keeps its cost and turn counts, so the monthly budgets include it

The values a task record takes from the agent's result (status, cost, turn counts, session, token counts) were written out twice, once for tasks without a repository and once for tasks with one, and a third place, the record of a task whose pipeline raised an error, copied only the status. So a task that crashed after its agent had finished lost what it had cost and how many turns it took. One function now produces these values for all three records.

Gain: A task that fails after its agent ran keeps its cost, turn counts and token counts: the cost reaches the monthly budgets, which are rolled up from the cost on the task record, and shows on the task. Example: the agent works 60 turns for 6.20 USD, then opening the pull request raises; before, the record had no cost and no turns, now 6.20 and 60. 36 lines removed and 31 added in the pipeline; a field added later reaches every record.

Test: agent/tests/test_pipeline.py > TestCrashedTaskIsReported::test_crash_after_the_agent_keeps_what_the_agent_reported; TestRepoLessPipeline::test_repoless_task_skips_repo_and_runs_agent (two assertions added)

Lean (merge): The rule for which tasks must deliver a pull request or a commit exists once, in the delivery gate

The rule that decides which tasks must deliver a pull request or a commit existed twice: in the delivery gate and, term for term, in its caller, which used the copy only to decide whether to look at the pushed branch. The copy is gone: the caller now looks at the pushed branch whenever a run ends without a pull request, and the gate alone decides whether that matters. Because that look now happens for more runs, it no longer decodes what git prints (it only needs to know whether there is any output), so a commit subject that is not valid UTF-8 cannot make it fail.

Gain: The delivery rule exists once, so an exemption added later cannot be forgotten in a second place and fail a task as lost when a commit did land. 17 lines removed and 9 added in the pipeline. No task verdict changes; a run that ends without a pull request costs one more local git log.

Test: agent/tests/test_pipeline.py > TestDeliveryGateReadsThePushedBranch::test_pushed_commit_whose_subject_is_not_utf8_is_counted (new); the two existing tests of that class and tests/test_pipeline_outcomes.py::TestDeliveryGate (unchanged) cover the merge

Lean (stdlib): The check for the agent's needs-input marker is one expression, 7 lines shorter, with the same result

The check for the marker with which the agent says that it needs input walked through the lines of its final message by hand to find the first one that is not blank. It now strips the leading whitespace and looks at what follows, which is the same test in one expression.

Gain: 7 lines fewer; the marker is detected and removed by the same rule. Compared on 347,990 inputs built from every whitespace and line-break character, the marker, a truncated marker and ordinary text: no difference.

Test: No new test: agent/tests/test_pipeline_outcomes.py > TestNeedsInputMarker (5 tests, unchanged) is the check.

Test: A test fails when the pipeline stops removing Linear MCP servers from .mcp.json before the agent starts

Nothing tested that the pipeline removes Linear MCP servers from the repository's MCP configuration (.mcp.json) before the agent starts, the rule that keeps a repository or a registry asset from handing the agent Linear tools. Both removals, the one for what the repository committed and the one after registry assets are merged in, could be deleted without a test failing. Two tests now run a task up to the agent step and check what the file names at that moment.

Gain: The rule that the agent has no Linear tools is pinned at both places where the pipeline applies it: deleting either removal now fails a test.

Test: agent/tests/test_pipeline.py > TestWhatTheAgentStepIsGiven::test_linear_server_committed_to_the_repository_is_removed; ::test_registry_server_that_the_linear_scrub_removes_fails_the_task

Test: A test fails when the agent does not run on the context the platform sent, or accepts a newer format

Every deployed task reaches the agent with a context prepared by the platform: the prompt, the issue, the branch names and what is remembered about the repository. No test ran the pipeline with such a context, so the lines that take these values over, and the one that fails the task when the context cannot be parsed, could be changed freely. Two tests now cover them: one checks that the agent runs on exactly what the platform sent, the other that a context of a newer format fails the task with the error that names the mismatch.

Gain: The hand-over from the platform to the agent is tested where the agent consumes it: six mutations of those lines, the three the audit named and three more, now each fail a test.

Test: agent/tests/test_pipeline.py > TestWhatTheAgentStepIsGiven::test_orchestrator_context_is_what_the_agent_runs_on; ::test_context_of_a_newer_schema_fails_the_task_with_the_contract_error

fix(agent): repair local runs and diagnostics, close a coverage bypass

Bug: agent/run.sh builds the image from the repository root, where the Dockerfile's COPY paths start

The script that runs the agent locally built the container image with the agent folder as the Docker build context, but the Dockerfile copies paths that start at the repository root. Every local run therefore stopped at the image build with a file-not-found error. The script now builds from the repository root and names the Dockerfile, the same way the CDK stack and the image-scan task already build it.

Gain: The documented local test path works again (developer guide, README quick start, the dry-run recipe of the troubleshooting skill). It has failed for every contributor since the Dockerfile moved to the repository-root context on 2026-05-18. One line changed, and the script is now run by a test for the first time.

Test: agent/tests/test_run_sh.py > test_build_context_holds_every_path_the_dockerfile_copies

Bug: Local agent runs, local table set-up and local progress events work with AWS CLI v1 as well as v2

On a machine whose AWS command line tool is version 1, three local helpers failed. The local run script stopped with advice about SSO logins that did not apply, because it called a command that only version 2 has. Setting up the local DynamoDB tables failed, and the two tasks that show local progress events always reported that there were none, because version 1 rejects the pager flag they passed. The run script now uses the tool only when it is not version 1 and otherwise mounts the AWS folder, which is the order the developer guide describes. The table script drops the flag, and the two event tasks switch the pager off with an environment variable that both versions accept.

Gain: Local agent runs, local table set-up and local progress events work with AWS CLI v1 as well as v2 (the owner's machine has v1). One flag deleted. Checked against the real v1 and v2 executables of this machine without contacting AWS.

Test: agent/tests/test_run_sh.py > test_aws_cli_v1_falls_through_to_the_mount_of_the_aws_directory; agent/tests/test_local_dynamodb.py > test_tables_are_created_by_an_aws_cli_without_the_pager_flag and test_events_are_printed_by_an_aws_cli_without_the_pager_flag (both tasks)

Bug: agent/run.sh passes the auxiliary model setting into the container and drops a dead Linear variable

The local run script did not pass the setting for the small auxiliary model into the container, although the README lists it among the variables for local runs. A local run on an account that may only use one geography therefore called a default model profile it could not invoke. The script also passed a Linear secret variable that no code has read since the Linear OAuth migration. It now passes the auxiliary model setting and no longer passes the dead variable.

Gain: A local run can use the auxiliary model the README says it can, so the pre-flight check and web summaries stop failing on accounts limited to one geography. One dead pass-through removed (one line added, one removed).

Test: agent/tests/test_run_sh.py > test_auxiliary_model_the_caller_set_reaches_the_container

Bug: The SDK smoke diagnostic prints FAIL and exits 1 when Bedrock refuses the model call

The SDK smoke diagnostic printed PASS and exited 0 when Bedrock refused the model call. It only counted messages, and the command line tool reports a refused call as an ordinary assistant message followed by a result that is flagged as an error. The diagnostic now reads that flag, prints FAIL with the error text and the HTTP status, and exits 1.

Gain: The smoke diagnostic (the next step the threading diagnostic recommends, and a step of the developer guide's checklist for a new model) no longer clears the SDK, CLI and Bedrock path in the one case where Bedrock is the problem: a model the account cannot invoke. Its main function also drops below the complexity ceiling, so one lint exemption is deleted.

Test: agent/tests/test_diagnostics.py > test_sdk_smoke_fails_when_the_model_call_is_rejected (control: test_sdk_smoke_passes_when_the_model_answers)

Bug: The subprocess threading diagnostic exits 1 when a threaded read loses messages

The diagnostic that checks reading a child process from a background thread exited 0 even when one of its threaded reads lost messages and it printed FAIL. A shell chain or a script that checks the status went on as if it had passed. It now exits 1 whenever a threaded test fails, the rule its sibling diagnostic already follows.

Gain: Both diagnostics now end with a status that matches the verdict they print, so a failing thread test can no longer be chained past. Three lines changed.

Test: agent/tests/test_diagnostics.py > test_subprocess_threading_exit_status_follows_the_threaded_read

Bug: Agent commits keep Co-Authored-By, Task-Id and Prompt-Version in one trailer block that git can parse

The commit hook that stamps the task id and the prompt version on agent commits always started a new paragraph for them. Git reads trailers only from the last paragraph of a message, so on a commit that already ended with a Co-Authored-By line, that line stopped being a trailer. The hook now uses git's own trailer command, which adds to the block the message ends with and starts a new block only when there is none.

Gain: Agent commits on task branches keep one trailer block that git can parse: Co-Authored-By, Task-Id and Prompt-Version together. Same number of lines, and the hook has tests for the first time. The limit stays as before: a squash merge appends its own paragraph, so on main only that last block is read.

Test: agent/tests/test_prepare_commit_msg.py > test_trailers_the_message_ends_with_stay_trailers

Gate: In the agent package a '# pragma: no cover' comment no longer hides code from the coverage floor

In the agent package a # pragma: no cover comment took code out of what the coverage floor measures, and no check refused it; the other packages already reject such comments. The coverage settings now replace the two default lists that honour those comments, so a pragma comment has no effect any more. The settings are part of the coverage contract, so removing them fails the existing drift check.

Gain: The agent's 80 percent floor can no longer be met by a comment. 24 statements that seven comments were hiding now count, 19 of them run by no test, among them the escalation branch of the progress hook. Measured on the parent commit with its 2283 tests: 86.39 percent, and 86.19 percent for the same run under the new settings; with the 16 tests this commit adds, the suite (2299 tests) reports 86.35 percent. One comment on one function used to lift the total to 88.42.

Test: agent/tests/test_coverage_settings.py > test_only_code_that_cannot_run_is_left_out_of_the_measurement

fix(agent): give repo-less tasks their attachments and a cancel check

Bug: A task without a repository downloads its attached files and names them in the agent's prompt

A task without a repository (web research, or the default agent when no repository is given) can be submitted with attached files. The files were screened and stored and their descriptions were sent to the agent, but the agent downloaded attachments only on the path that clones a repository. Such a task ran with a prompt like 'Summarise the attached report', no file on disk and no mention of one, and still ended as completed. The agent now downloads the files into a directory of the task's own, below the directory it works in, and names them in its prompt, as for a task with a repository; a file that cannot be fetched or fails its integrity check fails the task before the agent starts. One workflow step used to put the platform's original prompt back in place of the one that names the files: it now keeps a prompt that is already built.

Gain: Bug fixed for every task without a repository that carries an attachment: the answer can be about the attached file. Before, the upload, the content screening and the storage were paid for and the file was ignored without any error. The download is one function used by both kinds of task (24 lines moved out of the main pipeline function, not copied).

Test: agent/tests/test_pipeline.py > TestRepoLessPipeline::test_repoless_task_gets_its_attachments; ::test_repoless_task_whose_attachment_was_replaced_fails_before_the_agent_runs; agent/tests/test_workflow_runner.py > TestCloneAndHydrateHandlers::test_hydrate_context_keeps_a_prompt_the_caller_built; ::test_hydrate_context_takes_the_hydrated_prompt

Bug: A cancelled task without a repository delivers no result, no event and no 'completed' memory episode

When a user cancelled a task without a repository while its agent was running, the agent stopped after its current turn but the pipeline carried on: it uploaded the unfinished answer as the task's result, emitted the event that carries the answer, and wrote an episode saying the task had completed into the user's memory, which that user's later tasks are given as history. A task with a repository already checks for a cancellation at that point and skips everything after it. The same check now runs for a task without a repository, between the agent and the delivery: a cancelled task delivers nothing and the agent writes no episode for it (the platform's own fallback episode records it as cancelled, as for a task with a repository), and its trace is still kept when it was submitted with tracing.

Gain: Bug fixed: a cancelled research or default-agent task no longer leaves a result file, a delivery event and a false 'completed' episode behind. The cancel check and the steps that close a cancelled task exist once for both kinds of task, and the main pipeline function is 44 lines shorter; with the attachment change its complexity as the lint counts it falls from 52 to 45.

Test: agent/tests/test_pipeline.py > TestRepoLessPipeline::test_cancelled_repoless_task_delivers_and_remembers_nothing; ::test_cancelled_repoless_task_keeps_its_trace; ::test_repoless_task_that_was_not_cancelled_is_delivered_and_remembered; ::test_task_record_that_cannot_be_read_does_not_hold_back_the_delivery; ::test_repoless_task_agent_no_result_is_error (one assertion added)

Bug: A start-up failure reaches the task record with its real reason, not as a lost session minutes later

When a task could not build its configuration at start (an attachment description the agent does not accept, or a required value that is missing or malformed), the agent raised the error before it had told its AWS session which task it was working for. The server then tried to record the failure on the task with credentials that carry no task tag, and the platform's policy lets the agent write only the record of the task named in that tag, so that write is refused. The task stayed 'running' without a heartbeat and about six minutes later the platform failed it as a lost agent session. The agent now sets the task's tags before it builds the configuration, so the real reason is recorded at once.

Gain: The real reason of a start-up failure reaches the task record within a second instead of being replaced, about six minutes later, by 'Agent session lost: no recent heartbeat'. Affects deployed tasks on AgentCore and Lambda MicroVM, the two backends whose server records such a failure. One call added.

Test: agent/tests/test_pipeline.py > TestSessionTagsAroundTheConfiguration::test_task_whose_configuration_is_rejected_is_already_tagged; ::test_started_task_is_tagged_from_its_resolved_configuration

Bug: The memory episode of a repository task carries the task's verdict, not the result of its build

After a task with a repository, the agent writes a short episode into the repository's memory, and later tasks on that repository are given it as what happened before. The episode said COMPLETED or FAILED according to whether the build after the agent had passed, not according to how the task ended. A task that stopped at its turn limit over a green build was remembered as completed although it was recorded as failed, and a task that completed over a build that was already red before it started was remembered as failed. The episode is now written once the task's verdict is known and carries that verdict, as the episodes of tasks without a repository and the platform's fallback episode already do.

Gain: Later tasks on a repository are given the true outcomes of earlier ones. Wrong before for: a task whose agent failed or hit its turn limit while the build was green or could not run, a task that delivered nothing, a task completed over an already-red build, and a completed review whose informational build failed. No new logic: 16 lines moved below the verdict and one parameter renamed.

Test: agent/tests/test_pipeline.py > TestEpisodeRecordsHowTheTaskEnded (4 tests)

Bug: A coding workflow that delivers a document no longer fails when it leaves out the requires_repo line

A workflow can declare that its result is a document rather than a pull request while it still needs the repository for context. The pipeline recognised such a workflow only when its file spelled out that it requires a repository. A coding workflow may leave that line out, because coding workflows require a repository by default, and was then sent through the build and pull-request steps: with no commits there was no pull request, the task failed as 'deliverable lost', and the document the agent wrote was never uploaded. The pipeline now uses the rule the rest of the agent uses: the declared value, or the default of the workflow's domain.

Gain: A valid document-producing coding workflow no longer fails with a misleading error after a full clone, agent run and build. No shipped workflow is affected today; the hit is on forks and on the next first-party planning workflow. One expression changed.

Test: agent/tests/test_pipeline.py > TestRepoLessPipeline::test_repoful_artifact_workflow_delivers_artifact_and_skips_pr[left-to-the-coding-domain] (the existing test, now run for both spellings)

Bug: The console and bgagent watch show the build check after the agent, its result and the pull-request step

While a coding task runs, the agent reports the start and the end of each workflow step, and the operator console shows its stages from these reports. Only the agent step was reported: the build that runs after the agent and the opening of the pull request are done by the pipeline itself, which reported nothing until the pull request existed. So while that build ran, often for minutes, the console still showed 'Working', and its lines 'Checking that it builds and the tests pass', 'Build and tests passed' and 'The build or tests failed' never appeared outside its demo data. The pipeline now reports the start and the result of the build and the start of the pull-request step, under the names the workflow gives these steps. A build whose command could not run gets a start but no result, as on the task record.

Gain: Operators see in the live console and in bgagent watch when a task is verifying its build, whether that passed, and when the pull request is being opened. Checked with the console's own functions: during the post-agent build the current stage is now 'Checking' where it was 'Working'. Three more events per coding task; no change in web or CLI code.

Test: agent/tests/test_pipeline.py > TestStepMilestonesOfThePostHooks (5 tests)

fix(agent): stop the post-hooks losing commits or failing the task

Bug: Commits made after the agent opened its pull request are pushed to it

When the agent had already opened its pull request, the platform returned the link and pushed nothing. Work the agent did afterwards, and the commit the platform makes of changes left uncommitted at the turn limit, stayed in the container and was lost, while the task reported success and a green build for code the pull request did not contain. The platform now pushes those commits to the pull request, and when the push is refused it says so in a comment on the pull request.

Gain: Bug fixed for new tasks whose agent opens its pull request before it stops working: commits made after that, and the platform's commit of changes left in tracked files, are pushed to the pull request instead of being discarded with the container; when the push is refused or times out, a comment on the pull request says so. Not delivered and not announced, as before: commits made on a detached HEAD, and files that were never added to git. Checked with real git against a bare repository: before, the branch on the remote stayed at the earlier commit; now it is at the safety-net commit.

Test: agent/tests/test_post_hooks.py > TestExistingPrGetsLaterCommits > test_safety_net_commit_reaches_the_pull_request, test_reviewer_is_told_when_the_later_commits_cannot_be_pushed

Bug: A build that ran and failed is no longer taken for a command that could not run

After the agent finishes, the platform runs the repository's build. To tell a failed build from a build command that could not run at all, which is not held against the agent, it searched the whole build log for the words 'mise' and 'not found', or for 'command not found'. A build log names mise, and failed tests are often titled '... not found', so a real test failure was taken for a command that could not run and the task completed over a broken build. The check now accepts 'not found' only on mise's own error line and relies on exit status 127 for a missing command.

Gain: Bug fixed: a red build can no longer pass the regression gate because of a stray 'not found' in its output, and a red lint baseline is no longer recorded as 'did not run'. The repository's own tests record that this misfire happened on its build log. Measured with mise 2026.10.7 (the image pins 2026.11.6): a tool missing inside a task, a dependency or a parallel task exits 127; a dependency that names a missing task prints 'mise ERROR task not found: '. The other side of relying on the exit status: a build tool that replaces the shell's 127 by a status of its own (measured: pnpm exits 1, make exits 2; npm and yarn pass 127 on) now counts as a failed build even when its only error is a program that bash could not find; before, bash's 'command not found' in the log made that 'could not run'. Two lines of logic changed.

Test: agent/tests/test_post_hooks.py > TestIsVerifyCommandInert (4 tests)

Bug: Commits on the task branch are kept when the session ends on a branch with none of its own

Before it commits and pushes, the platform looks at which branch the agent ended on. If that was not the task's branch, it moved the task's branch to wherever the agent was. An agent that had committed on the task's branch and then switched to the default branch, for example to see whether a test fails there too, lost those commits: the build ran on the wrong tree and the task ended without a pull request. The task's branch is now left where it is when moving it would drop commits and the place the agent ended on has no commit of its own; it is checked out again and its commits are built, pushed and opened as the pull request, with any edits left uncommitted on the other branch committed on top. When git refuses to carry such edits over, because they are in a file those commits changed, the branch is moved as before and the edits are delivered without the commits.

Gain: Bug fixed: commits on the task branch are no longer discarded when a session ends on another branch that holds nothing new, for new tasks and for iterations on a pull request whose base branch has moved on. That includes a branch the agent itself cut at an earlier point to start again: the commits it stepped back from are delivered too, where before they were dropped. One case stays as it was: uncommitted edits on the other branch that git cannot carry over to the task branch are delivered and the commits are not. The cases that changed and the ones that must not change (a branch of the agent's own with commits, rewritten commits, a pushed branch of its own, a HEAD that contains the task branch, the task branch itself, a detached HEAD) each have a test that runs real git.

Test: agent/tests/test_post_hooks.py > TestReconcileAgentBranch > test_keeps_the_commits_when_the_agent_ended_on_a_branch_behind_them (2 branch names), test_keeps_the_commits_when_the_default_branch_has_moved_on, test_edits_made_on_the_branch_behind_are_committed_on_top_of_the_commits, test_checkout_that_git_refuses_adopts_the_head_as_before, test_adopts_commits_the_agent_rewrote_on_its_own_branch, test_follows_a_head_that_contains_the_platform_branch, test_adopts_commits_the_agent_pushed_from_its_own_branch

Bug: The pull request the platform opens links the licence of the repository it is in

When the agent does not open the pull request itself, the platform opens it and ends the description with the sentence that the contribution may be used under the terms of the project licence. That link pointed at the licence file of this project, whatever repository the pull request was in. It now points at the licence file of the repository and branch the pull request targets, the link the agent is told to write when it opens the pull request itself.

Gain: Bug fixed: pull requests the platform opens in other repositories no longer state their licence terms with a link to an unrelated project's licence. One line of product code.

Test: agent/tests/test_post_hooks.py > TestEnsurePrCreate > test_creates_pr_with_body_basics

Bug: A commit or push hook that outlasts its timeout no longer fails the whole task

The platform's own commit of leftover changes and its push run the repository's git hooks. When such a hook ran longer than the time allowed, one minute for the commit and ten for the push, the timeout was not caught: the task was recorded as failed with a Python error, without a build check, a push or a pull request, although the agent's earlier commits were fine. A timeout, or a git that cannot be started, is now treated like a commit or a push that failed: it is logged and the platform carries on with the commits that exist. The same holds for reading the final commit after an iteration on a pull request, which only words the reply.

Gain: A commit hook that outlasts its minute costs the uncommitted remainder, not the task: the commits the agent made are still built, pushed and opened as a pull request. A push hook that outlasts its ten minutes is treated like a push that was refused instead of ending the task with a Python error: an iteration, or a new task whose agent had opened its pull request, gets the notice on the pull request; a new task without one still ends as failed, because nothing reached the remote. Hits repositories whose hooks run lint or tests, this one included. Measured with real git: after a commit is killed during its hook the repository has no lock file left, HEAD is unchanged and the branch still pushes.

Test: agent/tests/test_post_hooks.py > TestEnsureCommitted > test_git_command_that_times_out_is_reported_as_not_committed (diff, commit), test_checkout_that_is_gone_is_reported_as_not_committed; TestEnsurePushed > test_push_that_times_out_returns_false; agent/tests/test_pipeline.py > TestIterationHeadCheck > test_task_keeps_its_verdict_when_git_cannot_say

Bug: A build command whose program is not installed counts as could not run, not as a crash

A build or lint command configured without shell operators is started directly. When its program was not installed, starting it raised an error that nothing caught: a review task failed with a Python error after its review was posted, and a coding task failed during setup before the agent ran. The same command written with a shell operator exits with status 127 and is treated as a command that could not run. Both forms are now treated alike.

Gain: Bug fixed: a build or lint command whose program is not installed or cannot be executed is reported as a gate that could not run, the outcome the code documents, instead of a Python exception as the task's failure reason. A start that fails because the machine is out of memory is still reported as an infrastructure fault, not as a gate that passes.

Test: agent/tests/test_post_hooks.py > TestVerifyCommandThatCannotStart (2 tests); agent/tests/test_repo.py > TestBaselineCommandThatCannotStart > test_missing_program_is_a_failed_baseline_not_a_task_crash

Lean (merge): One function reads a pull request field; a gh lookup that times out no longer fails the task

The same lookup of a pull request with the GitHub command line tool was written out four times, with different error handling: two of the copies caught nothing, so a lookup that timed out failed a task whose work was already on the pull request. One function now does the lookup for all four places, and a lookup that fails or times out is treated like a pull request that cannot be read, which every caller already handled.

Gain: 56 lines fewer in the post-hooks for this change (106 removed, 50 added). A gh lookup that times out no longer fails an iteration or a review whose work is on the pull request, and on a new task the platform goes on to push and to open the pull request. A new task whose agent had already opened it still ends as failed in that case, now with the reason that no pull request could be opened. One suppression of the silent-failure lint rule is gone with the copy that needed it (post_hooks.py: 1 before, 0 now).

Test: agent/tests/test_post_hooks.py > TestPushResolveFailureSurface > test_pr_lookup_that_times_out_is_no_url_not_a_crash; TestEnsurePrCreate > test_pr_lookup_that_times_out_goes_on_to_create_the_pr

Test: The safety-net commit is run by tests against a real repository

The commit the platform makes of changes the agent left uncommitted was never run by a test: every test replaced it by a stub. Tests now run it against a real git repository and check that it commits changed tracked files, leaves untracked files such as downloaded attachments out of the commit, makes no second commit, and reports a commit only when one was made.

Gain: The one post-hook that writes commits on the agent's behalf is covered. Both mutations the audit named now fail a test: staging untracked files as well, and reporting a commit that was never made.

Test: agent/tests/test_post_hooks.py > TestEnsureCommitted > test_commits_tracked_changes_and_leaves_untracked_files_alone, test_clean_tree_gets_no_commit

A task without a repository whose workflow tells the runner to stop quietly when its agent step fails no longer has its delivery step started on top of the failed agent step: the run ends at that step, as it did before the cancel check was added between the agent and the delivery.

fix(agent): record tool results and error reasons, count real turns

Bug: The trace and the trajectory stream record what each tool returned, screened for credentials

The trace a developer downloads to debug a task, and the trajectory stream in CloudWatch, showed which tools the agent ran and nothing of what they returned: the runner looked for tool results in the model's own messages, where the Claude Code CLI never delivers them. Each result is now recorded as an event of its own when it arrives, with the turn, the tool name, whether the call failed and the first 2000 characters of the output. The output is screened for credentials first, and the progress event of the same result, which until now kept the first characters exactly as the CLI delivered them, gets the same screened text.

Gain: Every --trace artifact and every trajectory stream lacked tool output, for every task, although the design document promises tool input and output there. A failed command that prints a token or an access key no longer leaves it in the stored progress event (a test shows it with values assembled from fragments). 11 lines that no message could reach are removed from the runner; the cost is one more log event per tool call, with at most the first 2000 characters of the output (about 2 KB for ASCII text, up to about 24 KB when every character has to be escaped).

Test: agent/tests/test_runner.py > TestToolResultsAreRecorded: test_trace_holds_what_the_tool_returned, test_failed_call_is_recorded_as_an_error, test_long_output_is_cut_in_the_trace, test_credentials_in_a_result_are_replaced_before_it_is_recorded

Bug: A task stopped by a CLI error or the budget carries the CLI's reason in its error

When the Claude Code CLI ended a session at the budget or with an error during execution, the task's error message was a fixed sentence that named the kind of stop and nothing else; the reason the CLI reported was dropped, and the logs did not hold it either. The reason is now appended to that sentence, after the screening for credentials that other text added to an error message already gets. A stop at the turn limit keeps its sentence: the reason the CLI gives for it says nothing more, and the text that follows it is what the agent was repeating when it ran out.

Gain: A task that fails this way shows why, on the task record, in bgagent status and in the failure reply (for example the text of the exception, or 'Reached maximum budget ($5)'), instead of pointing the operator to container logs that did not contain it. The sentence the error classifier matches is unchanged, so these failures are classified as before.

Test: agent/tests/test_runner.py > TestErrorResult: test_error_subtype_carries_the_reason_the_cli_gave, test_turn_limit_keeps_the_wrapper_the_classifier_reads, test_several_reasons_are_all_kept, test_reason_is_screened_before_it_is_recorded (red before), and two that pin what stays: test_error_subtype_without_a_reason_is_the_wrapper_alone, test_failed_model_call_is_reported_with_its_result_text

Bug: The research workflow is no longer offered the clarification tool, whose question its lane drops

The list of workflows that must not be given the tool for asking the requester a question named a workflow id that does not exist, so the research workflow it was meant to name was offered the tool. A question asked through it was never posted: the tool told the model the question would reach the requester, and the task then ended as completed with the model's last sentence as its research result. The list now names the real id.

Gain: A research task can no longer end as completed with 'I asked a question' as its result. One identifier changes; a test now loads every id on the list, so a misspelt or renamed workflow fails the build instead of silently excluding nothing.

Test: agent/tests/test_runner.py > TestClarificationToolIsOfferedPerWorkflow: test_research_workflow_is_not_offered_the_tool and test_excluded_workflow_is_one_that_ships_and_is_not_offered_the_tool (one case per listed id)

Bug: A clarification call with an empty question holds the task instead of failing it as not saved

When the agent asked for clarification but left the question text empty, the task was not held: the pipeline ran the build, looked for a pull request, found nothing committed and failed the task as 'the change was not saved'. Such a call now holds the task like any other clarification call. The comment shows the agent's last message, or the platform's standard wording when there is none.

Gain: The requester gets a question instead of a failed task with a misleading reason, and no build is run for a task that changed nothing. The runner and the comment renderer were already written for this case; only the step between them dropped it. Two lines of product code change.

Test: agent/tests/test_pipeline.py > TestHoldForInput::test_task_is_held_whatever_the_question_says[empty question] (red before; the [question] case pins the ordinary hold), and agent/tests/test_runner.py > TestClarificationCallIsRecorded, which pins what the runner records for such a call

Bug: The turn number in progress events, bgagent watch and bgagent status counts model answers, not messages

The runner numbered every message of the model as a turn, but one answer of the model arrives as several messages (its thinking, its text and each tool call), so the turn number in the progress events, in bgagent watch and in bgagent status ran well ahead of the real count and could pass the turn limit, for example 70 of 30. A turn is now one answer of the model, which is what the turn limit counts. The numbers the Claude Code CLI itself reports at the end of a run are not touched.

Gain: The live counter means what the limit means, on every task: a sample run of three answers showed 'turn 6' before and shows 'turn 3' now. For a task whose session breaks off before the CLI reports its own count, the turn counts on the task record come from this number and are no longer inflated two to three times.

Test: agent/tests/test_runner.py > TestTurnCount: test_messages_of_one_answer_are_one_turn, test_result_between_two_calls_of_one_answer_starts_no_turn, test_run_without_a_result_reports_the_turns_it_saw (red before), test_message_without_an_answer_id_is_a_turn_of_its_own (pins the fallback)

Lean (delete): The unused ENABLE_CLI_TELEMETRY opt-in and the nine variables it set are removed from the runner

The runner carried an opt-in for the Claude Code CLI's own telemetry export: an environment variable that nothing in the repository sets, no test runs and no document mentions, with a comment saying it was never confirmed to work. It is removed together with the nine variables it derived, the return value no caller read and a log line every task printed to say the option was off.

Gain: 83 lines removed (81 in the runner, one entry in the test setup, one commented-out line in the stack), one undocumented environment variable gone, one log line less per task. Nothing that runs today changes: the removed branch only ran when the variable was set by hand.

Lean (reuse): The runner strips the agent's instrumentation variables with the rule run_cmd uses, now under test

The rule that keeps the agent's own instrumentation settings away from the programs it starts was written twice, once for build and git commands and once for the Claude Code CLI, and neither copy had a test, so a correction made in one could leave the other behind. The CLI's environment is now prepared with the same function as the commands' environment.

Gain: One definition instead of two (7 lines fewer in the runner) and the first tests of the rule: five tests, and each of four deliberate breakages of the rule now fails one of them, where before any of them passed the whole suite.

Test: agent/tests/test_shell.py > TestCommandEnvironment (through run_cmd, buffered and streamed) and agent/tests/test_runner.py > TestSetupAgentEnv::test_instrumentation_variables_are_removed_from_the_process and ::test_python_path_of_instrumentation_only_is_removed

The registry security scan reported the call that streams build and lint output to the log: it passed an argument for replacing undecodable bytes that the scan's rules flag (python36-compatibility-Popen1), and because an earlier commit of this branch added it, the per-pull-request scan failed. The command's output is now opened as bytes and read through the same text layer the standard library would have put on it, so decoding, line splitting and live streaming are exactly as before (five new tests pass on the old and the new code), and the scan reports nothing.

@krokoko

krokoko commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor Author

Agent runtime (Python) (part 3 of 3): what changes and what it gains

fix(agent): stop failing finished answers over an everyday phrase

Bug: A finished answer that contains an everyday promise is delivered instead of failing the task

A task without a repository delivers the agent's final message as its result. A guard meant to catch a message that only promises the work for later refused every message whose text, outside code and links, contained one of thirteen phrases, among them 'check back later', 'I will share the results' and 'report will follow': a finished reply, notice or status update that used such words failed the task, and the answer was thrown away. The guard now matches two phrases only: 'watch live progress', taken from the hint that the Workflow tool of the Claude Code CLI prints when it starts a background run ('Use /workflows to watch live progress.'), and 'the workflow is now running in the background'. The two tests meant to protect finished answers, which never reached the guard, now do. What is no longer refused: a final message that puts the work off in any other words is uploaded as the answer, and the task ends COMPLETED. That is so for 'Results will follow shortly.', and also for a message that reports a background run: the placeholder recorded on a live task is refused for its last sentence only, and without it ('The deep-research workflow is running in the background. I'll deliver the full cited report here as soon as it completes.') it is now delivered.

Gain: Bug fixed for the default and the web-research workflow: a task no longer fails, with its finished answer discarded, because the answer contains an everyday promise. Ten example answers, each using one of the phrases the way a normal answer does, were all refused; nine are now delivered, and the tenth says 'watch live progress', a phrase that stays. A finished answer that uses one of the two kept phrases outside code still fails, for instance one that tells the reader to run bgagent watch to watch live progress. The placeholder recorded on a live task is still refused, by its last sentence. The cost is the one named above: a message that puts the work off in other words is delivered as written. What stands against that is the prompt rule and the block on the Workflow tool, which caused the recorded incident, and on the sub-agent, Monitor, SendMessage and Cron tools. Two tools that let a session put work off are not blocked: Bash, which can start a command in the background, and ScheduleWakeup, which schedules a later wake-up and has the model end its turn; a session of either workflow has both (pinned CLI 2.1.319). How often real answers were hit is not known: the repository holds no recorded answer, and none of its 109 documents and of the more than 450 commit messages before this change trips the guard before or after. 11 phrases removed ('results will follow', 'report will follow', 'will follow shortly', 'results will be ready shortly', 'I'll deliver the', 'I will deliver the', 'I'll share the results', 'I will share the results', 'launched in the background', 'check back later', 'come back later'); two tests that could not fail now test the guard.

Test: agent/tests/test_workflow_deliverers.py > TestDeliver::test_genuine_answer_with_colliding_tokens_not_rejected (six new answers) and TestDeliver::test_oversize_artifact_rejected_before_the_deferral_scan

Bug: A workflow file with the reserved empty post_hooks key loads, and the CI gate loads every shipped workflow

The workflow file format reserves a key, post_hooks, that may only be an empty list. The check that runs in CI accepted a file with that key, but the loader the agent uses when a task starts refused it, and with an error type none of its callers handle: every task of that workflow failed before it began. The loader now accepts the reserved key, reports whatever else it refuses as the workflow error its callers expect, and the CI check also loads each shipped workflow the way a task does.

Gain: Bug fixed: a workflow file that passes the CI check can no longer fail every task of its workflow at start. Shown on a copy of the tree: with the key in a shipped file the old check stayed green while building the task configuration raised. The check now also catches another kind of file the validator accepts and the loader refuses: a step with a key that YAML does not read as text, such as a bare 'on:', which it reads as true. No shipped workflow changes verdict.

Test: agent/tests/test_workflow_loader.py > TestParseWorkflow::test_reserved_empty_post_hooks_loads, ::test_model_keeps_post_hooks_empty and ::test_model_rejection_is_a_workflow_validation_error; agent/tests/test_workflow_tree_valid.py > test_first_party_workflow_validates

Bug: A read-only workflow whose pull request step names no strategy fails validation

A workflow declared read-only may not create or push a pull request, and the validator enforces that. It only looked at pull request steps that name a strategy, yet a step without one runs as 'create', which pushes the commits made on the branch and can open a pull request or move an existing one to another base branch. The validator now treats a missing strategy as the 'create' the agent will run.

Gain: Bug fixed at authoring time: a read-only workflow that forgets the strategy on its pull request step is rejected by the validator; before, the step ran as 'create' and could push, open a pull request or move an existing one. Behaviour change: such a file passed validation before and now fails rule 4; writing 'strategy: resolve' fixes it. No shipped workflow and none of the 21 fixtures of the validation corpus changes verdict.

Test: agent/tests/test_workflow_validator.py > TestIndividualRules::test_rule4_read_only_rejects_ensure_pr_without_a_strategy

fix(agent): stop renewing Linear tokens the agent cannot store

Bug: The agent no longer renews a Linear token it cannot store; an expiring one is left to the Lambdas

A Linear access token lasts 24 hours and is renewed with a refresh token that Linear replaces on every use. When a task started in the last minute of the stored token's life, or after it, the agent renewed the token for itself, but it cannot store the result: its role may only read the workspace secret. Secrets Manager was left with the refresh token the agent had used up, which Linear accepts again for 30 minutes only. If no Lambda that can store the new pair renewed the token in that time (a quiet workspace, a task that takes longer than that to open its pull request), the next renewal was refused, the workspace was marked revoked and all its Linear events were refused until somebody ran bgagent linear setup again. The agent now never renews: when the stored token is about to expire it logs a warning and starts without a Linear token, as it already does for Jira, and leaves the renewal to the Lambdas. The same change removes a pointless request: the secret of a workspace that was set up on the Identity vault from the start holds empty token fields, and when one vault call failed the agent posted that empty refresh token to Linear, got no token for it and went on without one. It now goes on without one and without the request.

Gain: An agent can no longer take a Linear workspace offline. Exposed before: every workspace on Secrets Manager, on each task whose token entered its last minute between the creation of the task and the start of the agent (with 90 seconds between the two, about one task in a thousand; more for a task that waited in the admission queue), whenever no Lambda that can store the token then renewed it within 30 minutes. Not ended here: three Lambdas (the orchestration reconciler, its scheduled sweep and the iteration heartbeat) renew with a role that may only read the secret and lose the new pair in the same way; that needs a permission and is left to the owner. Cost: such a task gets no eyes reaction and no move to In Progress at its start, and no final mark either unless a Lambda has stored a new token by the time it ends; on a workspace with no other activity the only renewal in that time follows this task's own 'pull request opened' event, seconds before the agent looks, so the final mark can be missing too. Before, the task got all of them from the token the agent had renewed for itself. 158 lines of renewal code removed from the agent (the file is 135 lines shorter).

Test: agent/tests/test_config.py > TestResolveLinearApiTokenNoRefresh::test_expiring_token_fails_closed_without_network_call; ::test_malformed_expires_at_fails_closed_with_warn_log; TestResolveLinearApiTokenVaultPath::test_vault_error_with_a_secret_that_carries_no_grant_yields_no_token

Bug: The final Linear reaction and the move to In Review use a token looked up when the task ends

For a task that came from Linear the agent read the workspace's access token once, at the start, and used that same value hours later to replace the eyes reaction with the check mark or cross and to move the issue to In Review. A token lasts 24 hours and can be near its end when a task starts, so after a long run Linear refused those calls: the task was completed and had its pull request, but the issue kept the eyes and stayed In Progress. The agent now looks the token up again before the final reaction, when a task ends normally, when it was cancelled and when it crashed. A workspace on the Identity vault gets a current token from the vault. A workspace on Secrets Manager gets the token a Lambda has stored in the meantime; the agent itself still never renews it, so when no Lambda has renewed it by then, the final reaction is tried with the old token and fails as before. A lookup that fails leaves the old token in place and cannot change how the task ends.

Gain: Linear issues get their final mark and the move to In Review on tasks that outlive the token they started with. The share of Linear tasks hit is about the task's duration divided by 24 hours (4% of one-hour tasks, 12% of three-hour tasks). Fixed for workspaces on the Identity vault, and for workspaces on Secrets Manager whenever a Lambda renewed the token during the task (for instance because another task of that workspace started or finished). Not fixed for a Secrets Manager workspace with no other Linear event during the task; that needs the platform to give a task a token that outlives it. Cost: one more read of the secret, or two AgentCore calls, at the end of each Linear task.

Test: agent/tests/test_pipeline.py > TestLinearIssueAtTerminal::test_final_reaction_is_sent_with_a_token_resolved_at_the_end (finished, cancelled); ::test_task_of_another_channel_resolves_no_linear_token; ::test_token_lookup_that_raises_does_not_stop_the_final_reaction; TestEarlyAckOrdering::test_setup_failure_swaps_eyes_to_cross (crash path); agent/tests/test_config.py > TestResolveLinearApiToken::test_force_replaces_the_cached_token_with_the_stored_one; ::test_force_keeps_the_cached_token_when_there_is_nothing_to_resolve; TestResolveLinearApiTokenVaultPath::test_force_asks_the_vault_again_instead_of_returning_the_cached_token; TestResolveLinearApiTokenNoRefresh::test_expiring_token_at_task_end_leaves_the_cached_one_in_place

Bug: A failed pipeline phase records its exception once on its tracing span instead of twice

Each phase of a task runs inside a tracing span, and so does the task as a whole. When an exception left such a span (context hydration, repository setup, the post-hooks, the task itself), the helper that opens the span recorded the exception on it and then let it pass through the tracer's own context manager, which records it again. Every span an exception left carried two identical exception events. The helper now leaves the recording and the error status to the tracer. The agent run of a repository task is not affected: it catches its exception inside its span and records it once itself.

Gain: One exception event instead of two on every span an exception leaves, so a trace view or a count of exception events shows the real number of failures. The module is five lines shorter. The helper had no test and now has two.

Test: agent/tests/test_observability.py > TestTaskSpan::test_exception_is_recorded_once_on_each_span_it_leaves; ::test_phase_that_succeeds_carries_its_attributes_and_no_error

fix(agent): correct the commands and rules the coding prompts give

Lean (merge): Both prompt builders share one memory renderer and one tail for overrides, channel guidance and skills

The builder of the coding prompt had its own copy of the code that lists remembered knowledge, and of the code that appends the operator's extra instructions, the Linear guidance and the skill texts. The builder for tasks without a repository had the same code a second time. Both now call one function for each; the prompts they produce are the same as before, byte for byte.

Gain: The product code is 12 lines shorter. The one place where untrusted memory text is sanitized on its way into the system prompt can no longer be changed in one prompt and forgotten in the other. 2304 rendered prompts were compared before and after: all identical.

Test: agent/tests/test_prompts.py > TestMemoryContextRendering::test_repo_bound_prompt_block_without_memory (new: the one text in which the two copies differed and that no test held); the existing tests of both builders pass unchanged

Lean (delete): The sanitizer has one name; the test that compared it with itself and a duplicate test are gone

The prompt builder imported the sanitizer for untrusted text under a second name. Its own four calls used that name, and outside the builder only tests did. One of those tests compared the function with itself, so it passed whatever the sanitizer did; another repeated an earlier test, with the same input and the same expected result. The second name and those two tests are removed, and the builder and the 22 remaining tests call the sanitizer by its own name.

Gain: 12 lines of test code removed, with 2 tests that checked nothing new. The parity test still passed with a sanitizer rewritten to return its input untouched, so it only looked like protection.

Test: agent/tests/test_prompts.py > TestSanitizeMemoryContent (22 tests, same assertions, now calling sanitization.sanitize_external_content by name)

Test: A test fails when a built system prompt still contains an unfilled {placeholder}

Nothing checked that a system prompt reaches the model with every placeholder filled in, so the template text and the code that fills it could drift apart unnoticed. A new test builds the prompt of every registered workflow and fails when a placeholder such as {default_branch} is left in it.

Gain: A placeholder that would reach the model unfilled now fails a test instead of changing what the agent is told, for example to open its pull request against the literal text {default_branch}. Removing any one of six fill-in lines made the test fail, and it caught the two placeholders added in this change while their fill-in code was still missing.

Test: agent/tests/test_prompts.py > TestBuiltPromptPlaceholders::test_no_placeholder_reaches_the_model (6 cases, one per registered prompt)

Bug: The system prompt names the Blueprint's build and lint commands instead of always the mise ones

A repository can set its own build and lint commands, and the platform runs those before and after the agent. The system prompt ignored the setting: it always said that mise run build had been run and must be run, also where that command does not exist, and it said so for review tasks, where the initial build is skipped. The prompt now names the configured commands, with mise as the default, and points to the setup results for what actually ran.

Gain: Every coding task on a repository with its own build command (npm, gradle, make): the agent is told to run the command the platform's gate runs. Before, it was told to run mise run build, which fails where the repository has no such mise task, and to report the result in the pull request. With no command configured the prompt still names mise run build and mise run lint.

Test: agent/tests/test_prompts.py > TestBuildAndLintCommands (7 cases: the four coding prompts with npm commands, empty and blank commands, the read-only prompt)

Bug: The closing rules of the coding prompt agree with the numbered steps they follow

The rules that close the coding prompts had not followed a change to the steps of the new-task workflow. They called the test step 'Step 3', which there is now the step that writes the code; that workflow pointed to 'step 5' for the pull request, which is the commit step; and the rules said 'Never pause or ask for input' although step 2 of the same workflow says the agent MUST ask when a request is too vague to act on. The rules now name the test step and the pull request description without a number, and tell the agent to ask where the workflow says so and to decide for itself everywhere else.

Gain: Three wrong or contradictory instructions leave the prompt of every task that opens a new pull request. The review prompt loses the same wrong step number, and the PR-iteration prompt the ban on asking, which contradicted its own instruction to ask for clarification. The instruction to ask before spending a run on a guess is no longer overruled by the last section the model reads.

Test: agent/tests/test_prompts.py > TestGetSystemPrompt::test_shared_rules_agree_with_the_new_task_workflow

Bug: The review prompt shows the GitHub review request as valid JSON, with each comment as an object

The prompt for review tasks showed the command that posts the review with doubled braces. Run as written, it sent each line comment as a piece of text that starts with two braces, where GitHub expects an object with a path, a line and a body. The prompt now shows the request as one JSON body handed to the gh command.

Gain: Every review task: the command of the prompt, typed from the first column, sends the request GitHub documents for a review with line comments, so the agent no longer has to find a working form by trial or fall back to a review without line comments. Both forms were run against a local endpoint and what they sent was compared with the documented request. GitHub's answer to the new request was not tried.

Test: agent/tests/test_prompts.py > TestGetSystemPrompt::test_pr_review_shows_the_review_request_as_valid_json

Lean (reuse): The prompts take the two default workflow ids from the one definition in the configuration module

The two default workflow ids were defined in the agent's configuration module and a second time in the prompts package, and written out again as text where a task carries no workflow. The prompts package and the prompt builder now use the definition of the configuration module. That definition is the one a test compares with the platform's defaults; the second copy was out of its reach.

Gain: One definition of each default workflow id for the prompt code, so a default that moves cannot leave the prompt lookup on the old id. The line count stays within one line: the second definition and its comment go (7 lines), the imports that replace them take 6. The four remaining literals of the pipeline are replaced in a later commit of this pull request.

Test: agent/tests/test_prompts.py > TestGetSystemPrompt::test_unknown_workflow_falls_back_to_default_prompt and ::test_repo_less_fallback_uses_repoless_default_not_coding (unchanged, still passing)

test(agent): cover the decisions run_task makes around the agent

Test: A test fails when a pull-request iteration or review is given the post-hooks of another workflow

No test checked what the pipeline decides for the pull request when an iteration or a review ends: whether commits are pushed, and whether the branch is repaired and committed to. It could have handled an iteration or a review like a task that opens its own pull request, or run the branch repair and the safety-net commit on a pull request that is only being reviewed, and every test still passed. One test now runs both kinds of task and checks that an iteration gets the 'push, then look the pull request up' handling, a review the 'look it up only' handling, and that a review neither repairs nor commits on the branch.

Gain: What the pipeline decides for the pull request at the end of an iteration or a review (push or no push, branch repair, safety-net commit) is tested for the first time. Three changes of the pipeline that passed the whole suite before now fail a test: every task handled as one that opens its own pull request, the branch repair run on a review, the safety-net commit run on a review. Test only: 1 test with 2 cases, no production change.

Test: agent/tests/test_run_task.py > TestPostHooksOfAPullRequestTask::test_post_hooks_follow_the_workflow[iteration], [review]

Test: Tests fail when the typed marker stops holding a new task, or an iteration on a pull request is held

When the agent of a new task asks a question instead of guessing, the task is held: nothing is built, no pull request is opened, and the question becomes the task's answer. The hold after the agent calls its question tool got a test earlier in this pull request; the older signal, a marker typed on the first line of the agent's last message, and the rule that an iteration on a pull request is never held had none. Three tests now cover this: the marker holds the task and the requester is shown the question without the marker; a task whose agent asked nothing is built and gets its pull request as before; and an iteration that carries a question still builds and pushes.

Gain: Three changes that passed the whole suite before now fail a test: ignoring the typed marker (the task would be built and then fail as 'nothing delivered' instead of asking), showing the internal marker to the requester, and holding an iteration (a hold skips the push, so commits made in it would stay in the container). Test only, 3 tests.

Test: agent/tests/test_run_task.py > TestWhichRunsAreHeldForInput::test_marker_that_opens_the_last_message_holds_the_task; ::test_task_whose_agent_asked_nothing_is_not_held; ::test_iteration_on_a_pull_request_is_not_held

Test: A test fails when a build killed at its time limit is reported as a failed build

When the build that runs after the agent is killed at its time limit, the task has to fail as 'timed out', which the platform words differently from a failed build. The pipeline could stop passing that on and every test still passed; the user would then be told that the build or the tests failed. A test now runs a task whose build timed out and checks the marker in the task's error.

Gain: The 'timed out' wording of a build that hit its limit can no longer get lost between the build and the task's error: two changes that passed the whole suite before now fail a test. The other two parts of this gap, a build killed by the machine and a task that delivered nothing, already got their tests earlier in this pull request. Test only, 1 test.

Test: agent/tests/test_run_task.py > TestBuildThatRanIntoItsTimeLimit::test_task_fails_with_the_timeout_marker

Test: A test fails when a task with a repository is not handed its attachment, or its prompt names a wrong path

A task with a repository gets its attached files downloaded into the clone, and its prompt names each file so that the agent can open it. No test ran such a task: the download or the lines in the prompt could be dropped, or the path in the prompt be wrong, without a test failing, and the agent would never see what the user attached. A test now runs a task with an image attached and reads the file at the path the prompt names.

Gain: The hand-over of attachments to the agent is tested for tasks with a repository. Four changes that passed the whole suite before now fail a test: no download, no mention in the prompt, a download outside the clone, a wrong path for an image. That a file which fails its integrity check stops the task was already tested earlier in this pull request. Test only, 1 test.

Test: agent/tests/test_run_task.py > TestAttachmentsOfATaskWithARepository::test_attachment_is_in_the_clone_and_named_in_the_prompt

Test: Tests fail when a task is remembered under the wrong name or the agent's notes are not stored

After a task the agent stores an episode in memory, and the notes it left in its pull request as learnings about the repository; later tasks are given what is stored under their repository, or under their user when they have no repository. No test looked at the name these are stored under or at the storing of the notes, so an episode could end up where no later task finds it. Two tests now check that a task without a repository is stored under its user, a task with a repository under the repository, and that the notes reach both the episode and the repository's learnings.

Gain: What later tasks are told about earlier ones, and under whose name it is stored, is checked where the pipeline decides it. Six changes that passed the whole suite before now fail a test, among them an episode given a name under which no later task finds it, and notes that are never stored as learnings. Test only, 2 tests.

Test: agent/tests/test_run_task.py > TestWhatIsWrittenToMemory::test_task_without_a_repository_is_filed_under_its_user; ::test_notes_of_a_task_with_a_repository_are_filed_under_the_repository

Test: Tests fail when a finished task is recorded with the wrong status, or Linear gets the wrong final mark

The last thing a task does is record itself as COMPLETED or FAILED, with its cost and what its build and lint did; the API, the notifications and the budgets read that record. For a task with a repository that ends normally no test looked at the status it records: every task could have been recorded FAILED, or a failed one COMPLETED, and a Linear issue could have got the success mark after a build that regressed. Two tests now check the record of a task that succeeded and of one whose build regressed, and that the Linear issue then gets the failure mark in place of the eyes.

Gain: The write that decides whether a task with a repository shows as COMPLETED or FAILED is checked in both directions, together with the pull request, build, lint, cost and turns it carries. Six changes that passed the whole suite before now fail a test, among them 'always FAILED', 'always COMPLETED' and a success mark on the Linear issue after a failed build. Test only, 2 tests.

Test: agent/tests/test_run_task.py > TestHowAFinishedTaskIsRecorded::test_green_build_with_a_pull_request_is_recorded_as_completed; ::test_build_that_regressed_is_recorded_as_failed

Test: Tests fail when a blueprint command, a branch or a limit of a task is dropped on its way to the agent

The platform sends each task the build and lint commands of the repository's blueprint, the branches it stacks on, its turn and budget limits, its model and the blueprint's extra instructions for the agent. No test followed them through the pipeline: one could be dropped on the way, a default would be used instead and nothing would fail, for example the default build command on a repository that has no such task, or the default branch for a task that must start from its predecessor's branch. Three tests now check that eleven of these fields arrive in the configuration the repository setup and the agent work from, that the extra instructions are in the agent's system prompt, and that the build and lint checks run the blueprint's commands.

Gain: A field can no longer disappear silently between the platform and the agent: fourteen changes that passed the whole suite before now fail a test, one for each of eleven fields, one for the blueprint's instructions and one each for the build and the lint check running the default command instead of the blueprint's. Test only, 3 tests.

Test: agent/tests/test_run_task.py > TestTaskFieldsReachWhatUsesThem::test_fields_are_on_the_configuration_of_the_repository_setup_and_the_agent; ::test_instructions_of_the_blueprint_are_in_the_system_prompt; ::test_build_and_lint_gates_run_the_commands_of_the_blueprint

test(agent): pin what the runner hands the SDK and records from it

Lean (delete): The agent's session result no longer carries two duration fields that nothing read

The result the runner hands back after an agent session carried two durations in milliseconds, the session's total time and its API time, copied from the final message of the Claude Code CLI. Nothing read them: the pipeline measures the task's duration itself, the trace takes both values straight from the CLI's message, and the log line the total time. The two fields and the two lines that filled them are removed.

Gain: 4 lines removed (2 in the runner, 2 in the data model), and the session result holds only values that something reads. Nothing a task records or reports changes: the agent's whole unit suite, the type check and the dead-code check pass without them.

Test: No new test (a deletion). The agent's whole unit suite passes without the fields (2616 passed in the last run), ty check and vulture are clean.

Test: Tests fail when the tool lock, the policy hooks or a task limit is left out of the SDK session call

The runner starts the Claude Code session with one call. That call carries the list of tools that are locked out because they leave work running after the session ends, the policy hooks (Cedar rules, output screening, cancellation, nudges), which settings files may be loaded, the turn limit and the budget. No test checked that the call receives any of these, so each could be deleted from it and every test still passed. Two tests now run the runner against a stand-in for the session client and check what it is given, for an ordinary task and for a read-only one.

Gain: Ten deliberate breakages now fail a test where all of them passed before: the tool lock removed, the policy hooks removed, every settings file loaded, the permission mode changed, the working directory, the system prompt, the turn limit or the budget dropped, and a read-only task given Write and Edit or the tool for asking the requester a question. No product code changes.

Test: agent/tests/test_runner.py > TestOptionsOfTheSdkClient::test_session_gets_the_tool_lock_the_hooks_and_the_limits_of_the_task and ::test_read_only_task_gets_neither_a_write_tool_nor_the_clarification_tool

Test: A test pins what the runner records from a clean session end: status, final text, cost, session id, usage

When a session ends, the Claude Code CLI reports how it went and the runner copies that onto the task: the status, the final text (for a task without a repository that text is the deliverable), the cost, the session id and the token counts. An earlier commit of this branch added tests for a failed end and for the question an agent asks through the clarification tool, but the ordinary successful end still had none: the line that records the final text, or the one that records the status, could be deleted with every test green. One test now feeds a clean result through the runner and checks each recorded value.

Gain: Five deliberate breakages now fail a test where all of them passed before: the status, the final text, the cost, the session id or the token counts not recorded. These lines run at the end of every task, and without the final text a research task has nothing to deliver. No product code changes.

Test: agent/tests/test_runner.py > TestCleanResult::test_status_final_text_cost_and_usage_are_recorded

Also here, with no change in behaviour: the four places of the pipeline that fall back to a default workflow id now use the two definitions of the configuration module, which completes the change to the prompts listed above, and the comment above the list of locked-out tools says what the deferral guard matches since it was narrowed.

fix(agent): catch a re-clone of the task repository on its own line

Bug: The guard against a second clone of the task repository judges each command of a multi-line command alone

The agent must not clone its own task repository a second time, because work done in the second copy never reaches the pull request. The check read a command of several lines as one command, so an option such as -b, -m, -t or -F on an earlier line (git checkout -b, git commit -m, python -m, grep -F) made it take a clone on a later line for quoted text and let it run. Each command of such lines is now judged on its own, by the rule that judged it before when it stood alone; a line break inside a quoted string and the lines of a here-document stay with their command. The split knows the plain forms of both; a string inside a command substitution inside a string, for example, or a here-document whose word is written \EOF or holds a dash or a blank, is cut at a line break inside it.

Gain: Closes the usual way to the failure the guard exists for, a task that ends with its work in a directory the platform does not track: a clone on its own line below a command with such an option. Measured on 20,000 generated commands (17,121 of them of several lines) whose right answer is known by construction: missed re-clones fall from 2,934 to 178 (2,772 that slipped through are refused now, 16 that were refused pass now), wrong refusals stay where they were (1,375 before, 1,381 now: 331 gone, 337 new), and wrong answers fall from 4,309 to 1,559. Every one of the 20,000 answers is what the old code answers for the commands of the lines taken one by one, and 20,000 generated one-line commands get the answer they got before, so nothing changes in how a command on one line is judged. Three consequences of that rule: a clone of another repository is no longer refused because a later line names the task repository; a command that was refused when it stood alone is now refused as well when an option on a line above used to let it through (a here-document or an echo of several lines that writes a file whose text has a line beginning with a clone of the task repository); and a re-clone in a form the guard does not see by itself (behind sudo, env or a variable assignment, in bash -c, in a script that a shell reads below a line with such an option) is no longer refused because a clone of another repository stands on a line above it. A pull-request body in one of the forms that the split cuts wrongly is refused when one of its lines begins with a clone of the task repository. 52 lines of product code added (net).

Test: agent/tests/test_hooks.py::TestSelfRecloneGuard::test_blocks_a_clone_on_its_own_line_after_a_line_with_a_text_flag and ::test_a_line_of_text_that_reads_like_a_clone_is_no_command

Test: Five tests call the callbacks that the SDK is handed, so a break in what they pass on fails a test

The agent hands the Claude Agent SDK four small callback functions that wrap the real hooks. Three of them were never called by a test on their normal path, so the code that turns an unexpected error in the permission check into a refusal, and the code that hands the hooks the task, the user, the repository, the progress writer, the loop guard and the policy engine, could break with every test green. Five tests now call the callbacks themselves.

Gain: Sixteen ways to break the callbacks now fail a test, among them: an error in the permission check answered with allow, the re-clone guard switched off for every real task, every call that needs an approval refused because the task is not handed on, approval requests written without the user, a second loop guard that never sees the calls that succeed, and a reviewer's denial that is never shown to the agent. Each of the sixteen passed all 675 existing tests of the ten test files that use the hooks before. Tests only, no product code.

Test: agent/tests/test_hooks.py::TestBuildHookMatchers::test_the_pre_tool_use_callback_allows_denies_and_fails_closed, ::test_the_pre_tool_use_callback_asks_for_approval_in_the_name_of_the_task_and_its_user, ::test_the_post_tool_use_callback_reports_to_the_progress_and_the_trajectory, ::test_both_tool_result_callbacks_feed_one_guard, ::test_the_stop_callback_injects_a_denial_that_the_engine_holds

Test: Tests pin that a denied rule refuses its next call without a new request, and that a timeout does not

When a user denies an approval request, the agent remembers the rule for a minute, so that a variation of the denied action is refused at once instead of asking the user again; a request that only timed out must not have that effect. The hook's part in this had no test: deleting it, or letting a timeout count as a denial, passed every test. Two tests now cover both.

Gain: The behaviour that keeps an agent from asking again and again for variations of something the user said no to (up to the limit of 50 requests per task) is pinned at the place that produces it, together with its limit: after a timeout nobody is treated as having said no. Both mutations passed the 675 existing tests before and fail one now. Tests only, no product code.

Test: agent/tests/test_hooks.py::TestDeniedPath::test_another_call_of_the_denied_rule_is_refused_without_a_second_request and agent/tests/test_hooks.py::TestTimedOutPath::test_a_timeout_does_not_count_as_a_denial_of_the_rule

Test: Tests cover the approval flow's refusals for errors other than the two it knows by name

Around an approval several things can fail: the request cannot be written, the timeout cannot be recorded, the task cannot be moved back to running, or there is no task at all. Each case has to end in a refusal (or, for the timeout, in reading the user's answer once more), but only the failures the code knows by name had tests. Five tests now cover the other errors, such as throttling or a network error, and the missing task.

Gain: Eight mutations that passed all 675 existing tests now fail one, among them: an approved call that runs although the task record still says the task is waiting, a wait for the answer to a request that was never written, a late approval that is dropped because recording the timeout failed, and a request opened without a task. Tests only, no product code.

Test: agent/tests/test_hooks.py::TestResumeFailure::test_any_other_resume_error_denies_the_approved_call, agent/tests/test_hooks.py::TestWriteFailure::test_any_other_write_error_denies_and_is_not_waited_for, ::test_without_a_task_id_the_call_is_denied_and_nothing_is_written, agent/tests/test_hooks.py::TestLateApprovalRace::test_an_error_of_the_timed_out_write_still_reads_the_row_again, ::test_an_error_of_the_second_read_leaves_the_call_timed_out

Test: Tests pin the numbers of the session-lifetime limit on an approval window, not only its label

An approval request waits at most as long as the session has left, minus two minutes kept for cleanup, and is not opened at all when less than the shortest window of 30 seconds would remain. The tests checked only the label of that shortening, not the numbers, and no test went near the point where the request is refused. They now check that 200 seconds left give a window of 80, that 149 seconds left refuse the request without writing it, and that 150 seconds left open it with a window of 30.

Gain: Since this branch made the limit take effect (the start time of the task is parsed now), these lines run in production for the first time. Five mutations of them passed every existing test before and fail one now: a window that runs to the end of the session without the cleanup margin, a request that nobody can answer in time, the edge one second off in either direction. Tests only, no product code.

Test: agent/tests/test_hooks.py::TestTimeoutCapping::test_maxlifetime_ceiling_clip_emits_milestone (two assertions added) and ::test_a_gate_is_refused_when_less_than_the_shortest_window_is_left

Lean (reuse): One helper writes every best-effort progress event of the hooks, where two did the same

The hooks had two helpers that write a progress event and must not let a failed write disturb the agent: one for the approval flow and one for the acknowledgements of nudges, denials, a cancellation and the loop guard's advisory. The second is removed and its four callers use the first. What is written to the event stream is the same; three log lines are worded differently and name the writer's method, no longer the milestone that was not written; and repeated failures of these writes are now escalated to an error log like those of the other progress events that the hooks write.

Gain: 24 lines of product code removed (net; the deleted helper had 35), one helper to maintain instead of two, and one coverage-exclusion comment gone with it. The existing tests of the nudge and cancel acknowledgements and of the advisory's milestone pass unchanged and now exercise the shared helper, including its skip when the writer is disabled and its handling of a write that raises; the acknowledgement of a denial had no test and is checked by the new test of the Stop callback.

Test: No new test (one function replaces a copy). agent/tests/test_nudge_hook.py, agent/tests/test_cancel_hook.py and agent/tests/test_hooks.py pass unchanged for the four callers: the milestone is written with the same keyword arguments, not written when the writer is disabled, and a writer that raises does not stop the injection.

The log line of a stuck-guard advisory is screened like the advisory itself.

fix(agent): fail a task whose pinned MCP server the Linear scrub removes

Bug: A task fails when the Linear scrub removes a registry MCP server that its Blueprint pins

A Blueprint can pin MCP servers from the registry, and the agent writes them into the MCP configuration of the session. Right after that it removes every server whose name or connection settings contain the word 'linear', the rule that keeps Linear tools away from the agent. A pinned server caught by that rule, for example one named linear-regression that has nothing to do with Linear, was removed with only a warning in the log: the task ran without the server while the task record listed it as loaded. Such a task now fails before the agent starts, as it does when the loader cannot load a pinned server, with an error that states the rule, lists the pinned servers and says what to change.

Gain: Bug fixed for any Blueprint that pins a registry MCP server with 'linear' in its namespace, its name or anywhere in its connection settings (URL, headers, command, arguments; for example acme/linear-regression, a host such as streamlinear.io, or a real Linear server): the task record can no longer name a server that this rule took away from the agent, and the operator gets a failed task with the reason and the remedy instead of runs that silently lack the tool. The rule that the agent has no Linear tools is unchanged. 13 lines added and 7 removed in one function of the pipeline, comments included; its complexity does not grow.

Test: agent/tests/test_pipeline.py > TestWhatTheAgentStepIsGiven::test_registry_server_that_the_linear_scrub_removes_fails_the_task (two cases: 'linear' only in the name of an unrelated server; a server whose URL is Linear's)

Lean (merge): Task verdict and error chaining are tested in one file, each case once (8 duplicate tests removed)

Two test files each had a class for the function that decides how a task ended and a class for the function that joins an agent error with a later failure, and eight of their tests checked a case the other file already checked, two of them with a failed build where the other file had a passed one. There is now one class per function, in the file named for this subject. Every case is kept once, with the stricter check of each pair, those two with both results of the build, and the 12 tests that only one file had were moved without a change. A fixture that reset the blocker latch around each of these tests is removed as well, because the shared test setup already resets it before every test.

Gain: 67 lines of test code fewer (148 removed, 81 added, nearly all of them moved) and 22 tests, run as 24 cases, where there were 30, with no case lost: 27 deliberate breakages of the two functions gave the same answer before and after, 26 caught by both sets of tests and one by neither. A status message or a signature that changes is now followed in one file instead of two.

Test: agent/tests/test_pipeline_outcomes.py > TestResolveOverallTaskStatus (17 tests) and TestChainPriorAgentError (5 tests); no new test

The agent README and the usage text of the local run script described three things that were not true. They said a dry run prints the prompt: it prints the length and a hash of each prompt, and there is no switch for the text. The README's command for building the image by hand used the agent folder as the build context, which cannot work because the Dockerfile copies its files from the repository root: the command now builds from the root and names the Dockerfile, as the run script, the CDK stack and the image scan do. And the README said the run script takes credentials from the AWS command line tool whenever one is installed: it does so with version 2 only, and with version 1 it mounts the AWS folder. Gain: the documented manual build works again (all 8 paths the Dockerfile copies were missing from the old build context), and nobody starts a dry run expecting to read the prompt. Documentation only, in two files; no code changes.

When a task loads MCP servers from the registry, the agent keeps the file it writes them to (.mcp.json, which can hold credentials) out of commits by listing it in the clone's own exclude file; an earlier change of this pull request introduced that. A review of it found two kinds of clone it did not cover. Where the last line of the exclude file had no final newline, the entry was glued onto that line: '.swp' became '.swp/.mcp.json', so the pattern that was there stopped working, the file was not ignored, and the agent went back to the older protection, with which git stash, rebase and merge fail. Where the exclude file could not be written, the guard logged a warning and stopped, and git add -A or an add that names the file would have staged it. The entry now starts on a line of its own, and when the exclude file cannot be written the agent uses the older protection instead of none. Where the exclude file does the work, the advice lines git prints when it refuses an add that names the file are switched off in the clone; the refusal stays. Gain: in these two kinds of clone the session's file stays out of git add -A, git add . and an add that names it, and a clone whose exclude file lacks a final newline keeps its own pattern and can stash, rebase and merge. Both kinds are rare: a fresh clone gets an exclude file that ends with a newline and can be written. One function and one import changed, 3 tests with real git.

refactor(agent): use one hash for approval rows and the deny cache

Lean (reuse): The approval hook stores a decision under the policy engine's own hash of the tool input

When a user denies an approval request, or nobody answers it, the agent remembers the call for a minute and refuses the identical call without asking again. The hook that stores the decision and the policy engine that looks it up each had their own function for the key, a hash of the tool input, and the two had to be kept identical by hand: a change to one of them would have switched that memory off without any error for a request that nobody answered (a denied call is also remembered by the rule it matched). The hook now calls the engine's function. Its own copy is deleted, with two fallbacks in it that could not run: the hook refuses a tool input that is not an object before it asks the engine, and the engine refuses one that it cannot hash before an approval is asked for.

Gain: The key a decision is stored under can no longer drift from the key it is looked up by; a drift would make the agent ask the user again for a call that nobody had answered a minute before. 20 lines of product code removed (net), 2 of them statements that no test could reach. One test added for the one kind of tool input for which the two copies gave different answers: an object that cannot be hashed is refused and no approval request is opened. On 20,000 generated tool inputs the deleted copy and the engine's function gave the same hash for each of the 14,809 that can reach the approval step, and the engine refused the other 5,191.

Test: agent/tests/test_hooks.py::TestWriteFailure::test_an_input_that_cannot_be_hashed_is_denied_and_nothing_is_written (new: the one case in which the two copies differed); agent/tests/test_hooks.py::TestTimedOutPath::test_a_timeout_does_not_count_as_a_denial_of_the_rule (existing, unchanged: it needs the key the hook stores to be the key the engine looks up)

Lean (delete): Five pieces of the tool hooks that could never run are deleted, with two silent-failure suppressions

Five pieces of code in and around the agent's tool hooks could never run and are deleted. A second check for a task id stood below the point where the approval step has already returned without one. The short preview of a tool input that is shown with an approval request had two fallbacks for inputs that never get that far. An error handler wrapped a call that only copies and empties a list, inside a hook whose errors are caught one level up anyway. A fallback for a missing Claude Agent SDK stood in a function that is only reached after the SDK has been imported. And a second name for the function that clears the record of the last blocker existed only for test fixtures, which repeated what the shared test setup does before every test. Nothing changes for a task. A sixth piece of the finding, accepting the start time of a task in epoch seconds, is left in place: pull request #904, open at the time and merged since, changed the same lines.

Gain: 22 lines of product code and 3 lines of test code removed (net), among them 7 statements that no test could reach, two suppressions of the silent-failure lint rule and one coverage-exclusion comment. The module of the clarification tool is now covered in full, and the most complex function of the approval step has one branch less. Each deletion rests on a condition that a test pins: four mutations of those conditions each fail a test, and with a blocker left set after every one of 645 tests no test starts with it.

Test: No new test. Existing tests that pin why each piece was dead, each shown by a mutation (mutations.txt): (a) agent/tests/test_hooks.py::TestWriteFailure::test_without_a_task_id_the_call_is_denied_and_nothing_is_written; (b) agent/tests/test_hooks.py::TestWriteFailure::test_an_input_that_cannot_be_hashed_is_denied_and_nothing_is_written and agent/tests/test_policy_three_outcome.py::TestFailClosedPosture::test_unhashable_tool_input_surfaces_distinct_reason; (e) agent/tests/test_nudge_hook.py::TestStopHook::test_hook_exception_swallowed; (f) agent/tests/test_clarification_tool.py::TestClarificationTool::test_build_server_returns_sdk_config and agent/tests/test_runner.py::TestClarificationToolIsOfferedPerWorkflow::test_new_task_workflow_is_offered_the_tool

The approval step, the tool hooks and the repository setup asked twenty times whether a progress writer is present before they handed an event to the helper that writes it, although that helper already does nothing for a missing writer. Those checks are removed; the one inside the loop that waits for a decision stays: pull request #904, open at the time and merged since, rewrote that loop. Nothing changes for a task, which always has a writer. A hook that is called without one, as some tests do, now leaves a debug line for each event it skips, as the acknowledgement events already did. Gain: the function that handles an approval request goes from 35 to 24 on the complexity scale of the lint, and to 23 with the task id check removed above; the limit for new code is 15, and the number recorded with the function's exemption from that limit is lowered to 23. Main's MicroVM approval lifecycle (#904) has since added one branch to the function: on the rebased branch it measures 24, and the record says 24. 15 lines of product code removed (net).

@krokoko

krokoko commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor Author

Task orchestrator, hydration, budgets and memory: what changes and what it gains

fix(hydration): fail a task that cannot run without its issue or PR

Bug: A review task on a pull request too large for the prompt keeps its 'Review this pull request' instruction

When a pull request was too large for the prompt and had to be trimmed, a read-only review task submitted without a description lost its instruction: the trimmed prompt ended with 'Address the review feedback on this pull request', which a review agent that may not change code cannot follow. The trimmed prompt now ends with the same 'Review this pull request' instruction as the untrimmed one.

Gain: Review tasks on large pull requests (long bot or review threads, over about 400,000 characters) get the review instruction instead of one they cannot follow. Two identifiers changed. The trimming branch of hydration had no test at all; it now has six.

Test: cdk/test/handlers/shared/context-hydration.test.ts > 'a read-only review keeps its instruction when the PR is over the budget %s' (two rows: 'as it was fetched', 'only once it is assembled')

Bug: When its issue or pull request cannot be fetched, a task that cannot run without it fails and says why

A task that named only an issue, with no description, still started an agent when the issue could not be fetched (a mistyped issue number, a GitHub error): its prompt held the task id and the repository and no task. A pull-request task whose pull request could not be fetched started an agent with a placeholder instead of the branch, and failed on a git error after the session start and the clone. Both now fail during hydration and say why, for example 'Failed to fetch issue #42 from GitHub'. A task that has a description still runs without its issue, as before.

Gain: No agent session, clone and model spend for a task that has nothing to do or cannot check out its branch, and the user reads the real reason within seconds instead of a git error or the output of an agent that ran without a task. This is what the orchestrator design already states: fail if the issue is essential, degrade if the user also gave a description.

Test: cdk/test/handlers/shared/context-hydration.test.ts > 'GitHub fetch fails for a task that is only its issue ... fails hydration, the prompt would hold no task' (new) and 'PR fetch failure fails hydration ... a fallback context has no PR branch for the agent to check out' (the changed existing test)

Bug: The agent gets up to the newest 300 comments of an issue instead of only its 30 oldest

Hydration asked GitHub for an issue's comments without a page size, and GitHub then returns only the 30 oldest. On an issue with 45 comments the agent never saw the last 15, although the prompt budget is built to keep the newest comments and drop the oldest. Comments are now read 100 to a page, and for a longer thread the newest three pages; the copy of this fetch that the agent uses in local mode does the same.

Gain: An issue with 31 to 300 comments reaches the agent complete, and a longer thread arrives as its newest 201 to 300 comments instead of its 30 oldest, so the latest clarification is in the prompt. The cost is at most two more GitHub requests per task, and only for issues with more than 100 comments.

Test: cdk/test/handlers/shared/context-hydration.test.ts > 'hydrates the newest of %i comments' (45, 150, 345); agent/tests/test_context.py::TestFetchGitHubIssueCommentPages::test_hydrates_the_newest_comments (same three cases)

Speed: Trimming an oversized pull request applies the budget by arithmetic first and sanitizes no text twice

When a pull request was over the prompt budget, hydration removed one comment at a time and rebuilt and re-sanitized the whole prompt after each removal. The budget is now applied to the fetched text by arithmetic first, the way it already was for issues, and no text is sanitized twice. The one-at-a-time loop stays for what is still over the budget once the prompt is assembled (the diff, diff hunks, markup); it rebuilds the prompt for each comment it drops but sanitizes nothing again.

Gain: For a pull request with 100 conversation comments of 5,000 characters the sanitizer runs 82 times instead of 4,504 and the prompt is assembled once instead of 24 times; with a diff of 10 files on top, 82 times instead of 4,658 and 4 assemblies instead of 25 (counted with a probe on the code before and after). The comments kept are the same as before the change: the newest 79, or 78 with the diff.

Test: cdk/test/handlers/shared/context-hydration.test.ts > 'of %i conversation comments of %i characters, sanitizes only the newest, which fit' (row 100, 5000)

Scale: Each text the prompt budget admits is sanitized once: the work no longer grows with the dropped comments

Hydration sanitized every comment of a pull request before it looked at the prompt budget, and again for each comment it then dropped, so its work grew with the number and the size of the comments, which on a public repository anyone can add. It now first drops the oldest comments and review threads by their fetched length, as it already did for issues, and it sanitizes each text once per hydration, however often the prompt is rebuilt while trimming and although the same text also goes to the guardrail. One limit: a comment that the sanitizer shortens (HTML tags) counts at its fetched length, so a pull request over the budget can keep fewer of its old comments than before.

Gain: Thirty comments of 65,000 characters cost 9 sanitizer calls instead of 1,040. A small pull request that is under the budget as fetched and over it once assembled (eight short comments, a diff of 12 files, six review comments of 65,535 characters from one account) costs 6 calls on those six comments instead of 75. For pull requests and for issues alike the budget now sets the sanitizer's work: each text that the budget admits is sanitized once (an issue's texts were sanitized twice), so the time hydration spends sanitizing no longer grows with the number of comments it drops.

Test: cdk/test/handlers/shared/context-hydration.test.ts > 'of %i conversation comments of %i characters, sanitizes only the newest, which fit' (row 30, 65000); 'drops review threads whole, oldest first, once the conversation comments are gone'; 'a PR over the budget only once it is assembled sanitizes a comment once, not again for each comment it drops' (the review's case D); 'a later hydration in the same process sanitizes its own texts and gets its own prompt'; 'sanitizes each text of the issue once, for the prompt and the screening text together'

fix(orchestration): stop false timeouts and stray agent sessions

Bug: No agent session is started for a task that is already failed or cancelled when the start step runs

When starting the agent session failed (for example a throttled AgentCore call), the orchestrator marked the task FAILED and the durable-execution SDK then ran the same step up to five more times; every run that got through started a real agent session for a task the user had been told had failed. A task cancelled just before the start got sessions too. On AgentCore and ECS the step now reads the task again, with a strongly consistent read, before it starts anything, and starts nothing when the task is already failed, cancelled or otherwise finished. A Lambda MicroVM task is left to the start code that #904 brought to main, which makes that check itself.

Gain: No agent session is started any more for a task that is already FAILED or CANCELLED when the start step runs. Before, one failed start could leave up to five extra AgentCore sessions working on one task, with their Bedrock spend and nothing on the task record to stop them by (a Lambda MicroVM task is not part of this change in the end: the start code that #904 brought to main makes the check itself). A cancel that arrives while the start call itself is in flight still gets that one session.

Test: cdk/test/handlers/orchestrate-task-handler.test.ts > 'start-session step' > 'starts no session when the durable SDK runs the step again after it failed the task' and 'starts no session for a task that was cancelled while its context was hydrated'

Bug: On AgentCore and ECS the orchestrator waits about 8.5 hours at any poll interval, not 85 minutes at 5 seconds

On AgentCore and ECS the orchestrator stops waiting for an agent after a fixed number of status polls (1020), which is 8.5 hours only at the default 30-second interval. A repository set to the 5-second interval that the developer guide shows as its example had every task longer than 85 minutes marked TIMED_OUT while the agent was still working; with a 300-second interval the limit was 85 hours, longer than the orchestration itself can live, so it never applied. The number of polls is now derived from the interval (6120 at 5 seconds, 102 at 300), so the waits between polls add up to about 8.5 hours whatever the interval. The time the polls themselves take comes on top, as before, and was not measured: at 5 seconds, 6120 polls that each take more than about 0.29 seconds reach the 9-hour limit of the orchestration before the timeout.

Gain: Repositories with a short poll interval stop losing every task longer than 85 minutes to a false timeout (on AgentCore and ECS the agent kept running behind it and could still open a pull request for a task shown as TIMED_OUT; a Lambda MicroVM task is outside this change since #904, which bounds its wait by a deadline on the clock). With long intervals the 8.5-hour safety net exists again. Nothing changes at the default interval: still 1020 polls.

Test: cdk/test/handlers/orchestrate-task-handler.test.ts > 'poll window' > 'is still 8.5 h at a 5 s interval, not 85 minutes' and 'is still 8.5 h at a 300 s interval, not 85 hours'

Bug: A failed DynamoDB status read counts as a missed poll; only a refused read still ends the orchestration

While a task runs, the orchestrator reads its status from DynamoDB at every poll. One failed read (a throttle, a 5xx, a socket timeout) ended the whole orchestration: the task stayed RUNNING with nothing left to finalize it. A failed read is now logged and counted as one missed poll, and polling goes on, however many reads fail in a row. Only a read that is refused (access denied, a malformed request, credentials or a signature that are not accepted) still ends the orchestration at that poll, as before this pull request.

Gain: A DynamoDB blip during hours of polling no longer costs the completion message in Slack, Linear, Jira or GitHub, the cleanup or the user's concurrency seat until the reconciler's next pass, and no longer leaves a task RUNNING for ever when the agent dies afterwards. That holds on AgentCore and ECS; a Lambda MicroVM task is watched by the supervisor that #904 brought to main, which has its own rule for failed reads.

Test: cdk/test/handlers/orchestrate-task.test.ts > 'pollTaskStatus' > 'counts a failed read as one missed poll and keeps the last known status'

Bug: The 'queued' comment on a Linear or Jira issue is posted only when the task really was queued

When a user is at the concurrency limit, the orchestrator queues the task and comments on the Linear or Jira issue that it has been queued and will start automatically. It posted that comment even when the task could not be queued because the user had cancelled it at the same moment, so a cancelled task was announced as waiting to start. The comment is now posted only when the task really was queued.

Gain: No 'queued, will start automatically, no action needed' comment on an issue whose task is cancelled and will never start. Rare (the cancel has to land between two database calls), but the message was simply false when it happened, and the function already returned the answer that its only caller ignored.

Test: cdk/test/handlers/orchestrate-task-handler.test.ts > 'admission step at the concurrency cap' > 'says nothing on the Linear issue when the task was not queued' (and its Jira twin)

Bug: A queued Linear issue gets the queued notice as a plain comment, without the cross mark of a failed task

A Linear issue whose task was only queued at the concurrency limit got the comment that the task has been queued and no action is needed, together with the cross-mark reaction that the platform uses for a failed task. The reaction was left over from the time when hitting the limit failed the task. The queued notice is now a plain comment, as it already was on Jira.

Gain: A queued Linear issue no longer shows the failure marker next to a comment that says no action is needed. The marker stayed for the whole queue wait, and for good when the task was cancelled or expired in the queue. Linear and Jira now behave alike.

Test: cdk/test/handlers/orchestrate-task-feedback.test.ts > 'notifyLinearOnConcurrencyCap' > 'posts a plain Linear comment when channel_source is linear and issue id + workspace are set'

fix(api): make failure titles and retry advice match what failed

Bug: A task whose GitHub token is expired or revoked reads 'GitHub token rejected' and is not retryable

When the GitHub token stored for a repository had expired or was revoked, GitHub answered 401 and the task was reported as 'GitHub API unreachable': a temporary network problem, retryable, with the advice to check connectivity and the reply 'reply here to try again'. GitHub had been reached and had refused the token, so every retry failed the same way. The failure now reads 'GitHub token rejected', not retryable, with the advice to store a valid token; other answers of GitHub, a 503 for example, keep the network reading.

Gain: Bug fixed. Everyone who submits a task for a repository whose token has expired or was revoked (every task fails at pre-flight until the token is replaced) is no longer invited to retry, and the admin is sent to the token and not to the network or the DNS firewall. 18 lines of product code, 20 lines of test.

Test: cdk/test/handlers/shared/error-classifier.test.ts > 'classifies a 401 from GitHub as a rejected token, not as an unreachable API'

Bug: A task the platform dropped reads 'The platform lost track of this task', retryable, not 'Unexpected error'

A task that the platform itself dropped, because its orchestrator or its agent container died before the run started or while it waited for an approval, is failed by a periodic sweep. The error classifier did not know the two messages this sweep writes, so the task showed 'Unexpected error', not retryable, while the same condition noticed by the orchestrator showed 'Agent session never started', retryable. Both messages now read 'The platform lost track of this task', retryable, with the advice to retry.

Gain: Bug fixed. A user whose task was lost to a platform crash is told to retry in the CLI, the web console and the threaded reply, and the status comment on the issue carries the new title; all four used to say 'Unexpected error', the CLI with 'Retryable: no'. The web console shows only the classified text, so there the cause was not visible at all. 16 lines of product code, 24 lines of test.

Test: cdk/test/handlers/shared/error-classifier.test.ts > 'classifies a task found stranded in $status as a retryable platform fault' (three cases: SUBMITTED, HYDRATING, AWAITING_APPROVAL)

Bug: The reply under a timed-out task says a retry may not resolve it instead of 'reply here to try again'

A task that was still running when the orchestrator stopped waiting for it (about 8.5 hours) is marked not retryable with the advice to split it into smaller tasks, and so was a task whose approval never came in that time, until #904 gave that case a message of its own. The reply under the issue nevertheless said 'This is usually a temporary infrastructure issue ... reply here to try again', because the entry was also tagged as a transient fault. It is now tagged as a problem of the request, so the reply says a retry may not resolve it.

Gain: Bug fixed. The reply under a timed-out task stops inviting a blind retry of work that just ran for 8.5 hours. One word of product code, 14 lines of test.

Test: cdk/test/handlers/shared/error-classifier.test.ts > 'does not answer "%s" with "temporary infrastructure issue, reply to retry"' (three cases: the plain poll timeout, the message an approval wait got before #904, and the one it gets since)

Bug: A task whose agent finished but whose build failed reads 'Build or tests did not pass', retryable

When the agent finished its change but the build or the tests failed on the result, the task detail said 'Agent task did not succeed: the agent completed but reported a non-success status', not retryable, although the agent had reported success and a retry with guidance is the normal next step. The task now reads 'Build or tests did not pass', retryable, and when the build ran out of time, 'Build/tests didn't finish in time (timed out)'. The threaded reply on an issue already told these cases apart; the CLI, the web console and the status comment did not.

Gain: Bug fixed. A task whose agent finished cleanly and whose build then failed or timed out gets a true title and description in bgagent status and in the web console, and 'Retryable: yes' in bgagent status; the status comment on the issue, which read 'Shipped a PR but stopped early - Agent task did not succeed', now names the build. 31 lines of product code, 28 lines of test.

Test: cdk/test/handlers/shared/error-classifier.test.ts > 'a red build after agent_status=%s is a retryable build failure, not "the agent reported a non-success status"' (success, end_turn) and 'a build gate that timed out reads as "didn't finish in time", not as a red build'

Bug: A task for a repository whose compute backend is not deployed says so and is not retryable

A repository can be configured for a compute backend that the deployed stack does not have, or, for Lambda MicroVMs, has without an image yet (the documented state after the first deploy). Such a task failed as 'Blueprint configuration error' with 'Retryable: yes', or as 'Agent session failed to start' with the advice to check cluster health and to try again, although only a redeploy or a change of the repository's backend helps. Both cases now read 'The repository's compute backend is not deployed in this stack', not retryable, and name those two remedies.

Gain: Bug fixed. An operator who pinned a repository to a backend that is not deployed, or who deployed the MicroVM backend before its image, reads the cause and the remedy in the CLI and the web console, and the user is not sent into a retry loop. 23 lines of product code, 38 lines of test.

Test: cdk/test/handlers/shared/error-classifier.test.ts > 'classifies a backend the stack does not deploy as a non-retryable config fault ($where)' (three cases: the pin refused when the blueprint loads, the MicroVM strategy without an image, the ECS strategy without a cluster)

Bug: A hung clone, install or push is titled 'A setup or git command timed out', not as a slow build

When a command that the agent runs around its work hung until its time limit (cloning the repository, fetching a branch, installing tools, pushing), the failure was titled 'Build/tests didn't finish in time' and the user was told that the build was slow. The build was not what had timed out: the build commands catch and report their own timeouts since an earlier change, and since then this entry sees only the other commands. The failure is now titled 'A setup or git command timed out' and points at a slow network or a very large repository.

Gain: Bug fixed. A user whose clone, install or push hung is no longer sent to look for a slow build, and an admin is no longer asked for more build capacity. The repository holds a recorded case: a 'claude --version' timeout shown as 'Build/tests didn't finish in time' (docs/verification/645-p2-smoke-runbook.md). Product code 4 lines shorter; the test now covers three real commands.

Test: cdk/test/handlers/shared/error-classifier.test.ts > 'classifies an uncaught $command TIMEOUT distinctly from a crash, and not as a slow build' (three cases: gh repo clone, mise install, git push)

fix(orchestration): treat temporary GitHub and ECS failures as temporary

Bug: A GitHub timeout, 5xx or 429 on the push-permission check fails the task as temporary, not as a bad token

Before a task starts, the platform checks that the GitHub token may push to the repository, and for some tokens that takes a second request to GitHub. When that second request timed out, or GitHub answered it with a server error or with HTTP 429, the task failed with 'insufficient GitHub permissions' and the advice to change the token, although the token was fine. Such a failed request is now reported as GitHub being unreachable, which is temporary and can be retried; the code comment that claimed the task is let through in this case was wrong and is gone. A used-up request quota on that second request is not covered: GitHub documents HTTP 200 with an error body, or 403, for it, and both are still reported as insufficient permissions.

Gain: A GitHub hiccup on one request (5 second timeout, 5xx or 429) no longer fails a task as a permanent permission problem that sends the admin to fix a token that is correct; the failure now carries the retry guidance, and a retry passes. Hit: every task whose repository answer does not report push permission, so that the second request decides (the tests model a fine-grained token this way), and every review task run with a triage-only token. One suppression of the silent-failure lint rule is removed together with the code it excused.

Test: cdk/test/handlers/shared/preflight.test.ts > 'fails GITHUB_UNREACHABLE, not a permission failure, when the GraphQL permission lookup times out'; 'fails GITHUB_UNREACHABLE when the GraphQL permission lookup answers HTTP 502'; 'fails GITHUB_UNREACHABLE when the GraphQL permission lookup answers HTTP 429'

Bug: A GitHub server error on the pull-request check is reported as temporary, not as a missing pull request

For a task on an existing pull request, the platform first asks GitHub for that pull request. Every failed answer, a GitHub server error included, was reported as 'pull request not found or closed', a permanent user error with the advice to check the pull request number. Now only the answers 'not found' and 'forbidden' are reported that way; any other failed answer is reported as GitHub being unreachable, as the repository check next to it already did.

Gain: One bad response from GitHub (502, 503, 429) on the pull-request request is shown as temporary, with the retry guidance, instead of telling the user that an open pull request does not exist. For these answers the pull-request check now does what the repository check does. One difference remains: a 403 that carries the rate-limit marks is temporary for the repository check and still 'pull request not found or closed' for the pull-request check.

Test: cdk/test/handlers/shared/preflight.test.ts > 'fails GITHUB_UNREACHABLE on PR 5xx' (and 'fails PR_NOT_FOUND_OR_CLOSED when PR returns 403', which pins the half of the rule that stays)

Bug: A rate-limited GitHub token fails new tasks as temporary ('rate limited'), not as a missing repository

When the GitHub token has used up its request quota, GitHub answers 403 ('forbidden') to its requests, except to the one request the platform uses to test whether GitHub is reachable. The platform read that 403 as 'repository not found or no access' and failed every new task with the advice to check the repository name and the token's access. A 403 that GitHub marks as a rate limit (no requests remaining, or a retry-after header) is now reported as a temporary GitHub condition whose text says 'rate limited'; a 403 without those marks is reported as before.

Gain: While the token is rate limited (until the hourly quota resets), new tasks fail as temporary and retryable, with 'rate limited' in the failure detail, instead of as a permanent access problem that sends the admin to the repository name and the token's scopes. By default one token serves all repositories and users, so every task submitted in that window was hit.

Test: cdk/test/handlers/shared/preflight.test.ts > 'fails GITHUB_UNREACHABLE on a rate-limited repo 403 (primary limit: x-ratelimit-remaining is 0)' and '... (secondary limit: retry-after is present)'

Bug: An ECS task that a status read does not see yet is asked for again and fails only after three misses

On the ECS backend the orchestrator asks ECS for the state of a task in the same moment it has started it, and AWS documents that such a read may not yet see a task that was just created. When ECS did not return the task, the orchestrator marked the task as failed on the spot, while the container went on starting and then ran the agent for a task already reported as failed. A task that ECS does not return now counts as one failed status check: the orchestrator asks again at the next poll and fails the task only after three misses in a row, as it already did for any other error of that call.

Gain: A status read that races the launch no longer fails an ECS task whose container is starting normally, and no longer leaves that container working unowned for a task shown as failed. A task that is really gone still fails, two polls later (one minute at the default interval), with a message that says the task was not found. Not observed in a deployment: it rests on the eventual consistency AWS documents for RunTask. Also adds the first test that drives the orchestrator's ECS status check end to end.

Test: cdk/test/handlers/shared/strategies/ecs-strategy-poll.test.ts > 'does not fail the task when the first poll, right after RunTask, misses it' and 'fails the task when three polls in a row miss it'; cdk/test/handlers/shared/strategies/ecs-strategy.test.ts > 'throws when DescribeTasks does not return the task: a poll that failed, not a failed task'

fix(hydration): record guardrail blocks and use the repo token for URLs

Bug: An issue task that the content guardrail blocks gets its guardrail_blocked event, as a pull request task did

When the content guardrail blocks the issue a task starts from, the orchestrator fails the task and is meant to record a guardrail_blocked event with the reason. For a task without a pull request that event was never stored: its details carried an unset pull request number, the DynamoDB client refuses an unset value inside a map, and the failure was only logged. The event writer now leaves unset detail values out, so the event is stored.

Gain: An issue task that the guardrail blocks now gets the guardrail_blocked entry in its event stream, as a pull request task already did, with the reason, the sources and their trust levels. That entry is what the user guide tells a user to look for when a task is blocked, and what the security design names as the audit record of hydration screening; until now such a task left one error line in the Lambda log instead. The write stays best-effort: if DynamoDB refuses it, the failure is logged and the task still fails with the reason. No other orchestrator event carries an unset detail value today; the guard is in the shared event writer, so an event added later with an unset top-level value is stored as well.

Test: cdk/test/handlers/shared/orchestrator-hydration.test.ts > 'hydrateAndTransition: guardrail_blocked event' > 'has no undefined value when the task has no pull request'

Bug: URL attachments are fetched with the repository's own GitHub token when it has one, not the platform token

A repository can be onboarded with its own GitHub token, for example because the platform token has no access to its organisation. The pre-flight check and the issue or pull request fetch of a task used that token, but URL attachments were fetched with the platform token, so where the platform token cannot read the repository, an attachment that points into the task's own private repository could not be fetched and the task failed in hydration. URL attachments are now fetched with the repository's token when it has one, and with the platform token otherwise, like the pre-flight check and the issue or pull request fetch.

Gain: Tasks of repositories with their own token can attach files and images that live in those repositories; where the platform token cannot read the repository, such a task failed with a fetch error for the attachment. The platform-wide token (or, where it was never configured, the placeholder the stack seeds its secret with) is no longer sent with the attachment requests of those tasks. The orchestrator now uses one token for all its GitHub calls of a task. As before, the token is sent only to github.com, raw.githubusercontent.com and api.github.com and their subdomains, and is dropped when a request is redirected to another host.

Test: cdk/test/handlers/shared/orchestrator-hydration.test.ts > 'hydrateAndTransition: URL attachments' > 'are fetched with the token of the repository when its blueprint sets one' (control, passes before and after: 'are fetched with the platform token when the repository has none of its own')

Bug: The task detail reports a fetched URL attachment as passed, with its real type and size, not as pending

A task can take an attachment as a URL; the orchestrator downloads the file, screens it and stores it before the agent starts. The result never reached the task record: for the whole life of the task the API reported the attachment as pending, with size 0 and a placeholder type, and nothing on the record said which bytes had been screened and handed to the agent. The record is now updated once the files are fetched and screened; if that update fails, it is logged and the task still runs.

Gain: The task detail (GET /v1/tasks/{id}, bgagent status --output json) reports a fetched URL attachment as passed, with its real type and size, and the record keeps the object version and checksum of what was screened, as it already does for inline and uploaded attachments. Cost: one small DynamoDB write for a task that has URL attachments.

Test: cdk/test/handlers/shared/orchestrator-hydration.test.ts > 'hydrateAndTransition: URL attachments' > 'are put on the task record as fetched and screened' and 'still reach the agent when the record cannot be updated'

fix(memory): load past task episodes and let the team-budget alarm fire

Bug: The memory read before a task asks for the whole episodes subtree, so per-task episodes are in scope again

Before a task starts, the orchestrator reads what earlier tasks on the same repository left in AgentCore Memory. It asked for the records stored at exactly the repository's episodes path, in a request field that the AgentCore API reference defines as an exact match, while each task's episode is stored one level below that path: by that rule no per-task episode could come back, and no warning was logged because an empty answer is not an error. Both memory reads now use the field that covers a whole subtree (namespacePath), as PR #95 had introduced and a commit in PR #176 undid without a recorded reason.

Gain: By the documented matching rule the per-task episodes are in scope of the read again, for a repository's tasks and for a user's repo-less tasks alike: until now the episodic half of the memory read could match at most the cross-task reflection records, without a warning. Two request fields change, and the test of PR #95 is back, so sending the exact-match field again fails the suite. Not observed on a deployed stack (the emulator does not implement this read): it rests on the API reference, the developer guide and the SDK's type declarations, which agree.

Test: cdk/test/handlers/shared/memory.test.ts > 'uses namespacePath (hierarchical retrieval) for both queries'

Bug: The alarm on skipped team-budget enforcement can fire: its metric is published with an empty dimension set

When a headless user cannot be resolved to teams (for example a Linear user mapped to a Cognito user that was deleted), the task is admitted without any team budget being checked, and a metric is written so that an alarm tells the operator. The metric was declared with no dimension set at all, and CloudWatch creates one metric per dimension set, so no datapoint was published and the alarm could never fire. It is now declared with one empty dimension set, which is how the embedded metric format writes a metric without dimensions.

Gain: The alarm on skipped team-budget enforcement can fire, so an operator learns that a user passes every team budget because an identity mapping is stale. One token changes; the metric document now passes the JSON schema AWS publishes for the format, which the old one failed.

Test: cdk/test/handlers/shared/budgets.test.ts > 'continues without team scopes when Cognito no longer has the mapped user'

The message that refuses a task because the billed user belongs to more than 98 teams no longer names that user's platform id: it reads "The user this task is billed to belongs to N teams; budget rollup supports at most 98." The Linear comment paths post the text of a 400 under the comment, and there the person who commented is not always the user the task is billed to. The task-creation log still carries the user id next to the message. This is the last part of the Linear reply fix of this pull request, found by its review and made here because this change owns the budget module.

@krokoko

krokoko commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor Author

Task API: reads, creation, attachments, authorizers: what changes and what it gains

fix(api): stop five read endpoints from failing or hiding data

Bug: bgagent policies list works for a repository whose Blueprint holds Cedar rules without annotations

Listing a repository's Cedar rules answered 503 'policy set invalid' when its Blueprint held a rule written without annotations, although tasks run with such a rule: the agent names it legacy_extra_ and asks for approval under that name. The listing now gives those rules the same generated names. A Blueprint rule annotated as hard is now listed with the hard rules instead of in neither list.

Gain: bgagent policies list works for repositories whose Blueprint holds plain Cedar rules, and it shows the rule ids that approval requests name and that --pre-approve rule: takes.

Test: cdk/test/handlers/get-policies.test.ts > 'lists Blueprint rules written without annotations under the ids the agent gives them', 'numbers the unannotated entries among themselves, whatever stands between them', 'lists a Blueprint rule annotated @tier("hard") among the hard rules'

Bug: The policy listing reads the repository row once: a failed read fails that request and caches nothing

The policy listing read the repository's row twice. When the second read failed it answered 200 with the built-in rules only and kept that answer in its cache, so for five minutes the callers served by that Lambda instance were told the repository had no rules of its own. It now reads the row once; a failed read fails that one request and nothing is cached.

Gain: No wrong listing after a transient DynamoDB error, and one DynamoDB read instead of two on every uncached call.

Test: cdk/test/handlers/get-policies.test.ts > 'a failed read of the repository row fails that request and is not cached'

Bug: The console's issue picker shows up to 50 open issues of a repository that has many open pull requests

The console's issue picker asked GitHub for the 50 most recently updated items and then removed the pull requests, which GitHub returns on the same endpoint. A repository with many open pull requests showed few of its issues, or none together with the text that it has no open issues. The handler now reads up to three pages of 100 items until it has 50 issues, with one time limit for all pages.

Gain: The picker shows up to 50 open issues whatever the share of pull requests among a repository's 300 most recently updated items. Counted on GitHub's live data on 2026-11-17: 50 issues instead of 30 for this project's own repository, instead of 17 for aws/aws-cdk and instead of 13 for kubernetes/kubernetes.

Test: cdk/test/handlers/list-repo-issues.test.ts > 'reads further pages when pull requests fill the first one' (red), with the guards 'answers the 50 most recently updated issues and stops reading', 'reads at most three pages of a repository that shows only pull requests', 'answers 503, not a short list, when a later page fails', 'lists an issue once when an update moves it onto the next page between two reads'

Risk: A repository's issue list is kept for one minute, so repeated requests no longer cost a GitHub call each

Every request for a repository's issue list called GitHub with that repository's token, the one the orchestrator and the agents also use, and nothing kept a script or a reloading browser tab below ten requests a second. The answer is now kept for one minute per repository, which is as long as the console itself treats the list as fresh.

Gain: Repeating the request for one repository no longer costs a GitHub call each time: a delivered list is reused for a minute, so while GitHub answers the cost is at most three GitHub calls a minute per repository and Lambda instance. Before, a script or a reloading tab could spend up to 36,000 calls an hour (10 requests a second) of a token that has 5,000 an hour as a personal access token. Not covered: a caller that asks for many repositories; that needs a throttle on the route.

Test: cdk/test/handlers/list-repo-issues.test.ts > 'answers a repeated request from memory, without spending another GitHub call' (red), with 'asks GitHub again once the kept answer is a minute old' and 'keeps the answers of two repositories apart'

Bug: bgagent trace download on a task whose trace file is gone prints 'No trace artifact', not an internal error

Downloading a trace whose file is gone answered 500 Internal server error instead of 404 TRACE_NOT_AVAILABLE. Trace files are deleted after 7 days while the task record stays 90 days, and the handler's role may read objects but not list the bucket, in which case S3 answers 403, not 404, for a missing file. The handler now treats that 403 as a missing trace and logs the status.

Gain: bgagent trace download on a task older than a week prints the CLI's 'No trace artifact' explanation instead of an internal error, and the handler stops writing an ERROR log line for each such request.

Test: cdk/test/handlers/get-trace-url.test.ts > 'returns 404 TRACE_NOT_AVAILABLE when HEAD returns HTTP 403 (how S3 reports a missing key to this role)'

Bug: The replay of a long --trace task is returned clipped and marked as truncated instead of ending in 502

The replay bundle stops adding events at 5 MiB to stay under Lambda's 6 MB response limit, but it measured each event before the escaping the response adds: the bundle travels as a string inside the Lambda result, where every quote and backslash takes two bytes. A long trace whose previews are JSON, such as tool results that carry JSON inside JSON, went over the limit and the request ended in 502. Events are now counted at the size they have in the response.

Gain: The replay of a long --trace task is returned, clipped and marked as truncated, whatever its previews contain. Measured with 4,000-character previews: 6.9 MB before for JSON inside a JSON string (over the limit), 5.2 MB after.

Test: cdk/test/handlers/get-task-replay.test.ts > 'keeps the Lambda response under 6 MB when the previews are JSON (quotes escaped once more)'

Scale: The pending-approvals list allows a user 60 calls a minute instead of 10, which two console windows reached

The list of pending approvals allowed each user 10 calls a minute. The operator console asks for it every 10 seconds in each visible window, and again when a page that shows approvals opens (the overview, the inbox, most task pages), when a hidden window is shown again and after each decision, so a second window or some clicking reached the limit, and the approvals inbox then showed a rate-limit error in place of the requests until its next poll. The default limit is now 60 a minute.

Gain: The approvals inbox no longer turns into an error for a user with two console windows, or with the console and the CLI side by side; a runaway script is still held to one call a second.

Test: cdk/test/handlers/get-pending.test.ts > 'the default limit is one call a second, enough for the console in several windows'

fix(api): make confirm-uploads fail closed and safe to repeat

Bug: Submitting a local file over 500 KB together with a URL attachment works instead of failing every time

A task that combines a large local file with a URL attachment could never be confirmed. Large files are uploaded straight to storage and then confirmed; the confirmation also looked in storage for the URL attachment, which is only fetched later, when the task starts. So it answered 'upload not found' on every attempt and the task was cancelled 30 minutes later. The confirmation now checks and screens only the files the client uploads and leaves the URL attachment to be fetched when the task starts.

Gain: Submitting a local file over 500 KB together with a URL attachment works. Until now it failed every time after 3 seconds and left a task that was cancelled 30 minutes later with the unrelated reason 'Upload window expired'.

Test: cdk/test/handlers/confirm-uploads.test.ts > 'confirms the uploads of a task that also has a URL attachment, which stays pending for hydration'

Bug: A rejected upload is removed from storage at once instead of staying readable by version id for 7 days

When an upload is rejected during confirmation, the task is failed and its uploaded files are deleted. The storage bucket keeps old versions of files, and the delete request named the files without their version, which only hides them: the rejected content stayed retrievable by version for 7 days. The delete request now also names the version that was just checked, so that content is removed at once. A second confirmation of the same task that is still screening at that moment can no longer read the files; it now answers that the upload is no longer in storage, instead of reporting the screening as unavailable and asking to try again later.

Gain: Rejected content is gone from storage when the task fails, as the comment in the code already promised, instead of staying readable by version id for 7 days. A confirmation that runs at the same time is told that the upload is gone (400) and not to try again later (503) for a task that has failed for good.

Test: cdk/test/handlers/confirm-uploads.test.ts > 'returns 400 ATTACHMENT_BLOCKED when screening rejects content' (new assertion on the DeleteObjects request), 'when an upload cannot be read for screening, %s' (2 rows: 'says that the upload is gone when it has been deleted in the meantime', 'reports the screening as unavailable for any other storage error')

Bug: The first blocked upload fails the task; a retried confirmation can no longer step over a blocked file

When the content filter blocked one upload, the confirmation still screened all the remaining uploads before failing the task. If it ran out of time while doing so, it saved its progress, including the blocked file, and told the client to retry; the retry skipped the blocked file and submitted the task. Now the first blocked upload stops the screening and fails the task, a blocked file is never saved as progress, and a task that already holds a blocked file is failed instead of submitted.

Gain: A task that holds a blocked attachment can no longer be submitted: the path by which a retry stepped over a blocked file is closed, and a block now ends the screening, so up to 7 content filter calls are no longer spent on a task that is already lost. A 4-line shortcut that went around the blocked check and the size check is deleted.

Test: cdk/test/handlers/confirm-uploads.test.ts > 'stops screening and fails the task as soon as the guardrail blocks an attachment, %s' (2 rows), 'fails a task that holds an attachment stored as blocked, even when the rest passes', 'fails a task that holds an attachment stored as blocked when nothing is left to screen', 'submits a task whose uploads are all screened already, without screening them again'

Bug: After a gateway timeout bgagent submit waits for the running confirmation and prints the task or its error

API Gateway ends a request after 29 seconds, but confirming several large attachments can take longer. The confirmation then keeps running on the server and submits the task, while bgagent submit printed 'HTTP 504: Gateway Timeout' and exited with an error, which invites submitting the same task a second time. After such a timeout bgagent submit now reads the task every 5 seconds until the confirmation has finished (for at most 165 seconds) and takes the task it read as the result: it prints the task, or reports a failed, cancelled or timed-out one with the reason the task gives. It confirms again only when the task still waits for its uploads after that time. A read that fails for a moment is repeated. It sends at most three confirmations.

Gain: A confirmation that takes longer than the gateway's 29 seconds is no longer reported as failed by the CLI while it succeeds on the server: the command waits for the confirmation that is running, instead of starting a second one beside it, and then prints the task it read. One case remains in which the command ends with an error although the task may still be submitted: a third confirmation that outlasts the gateway as well. For this finding only the CLI changes; the server still measures its deadline against its own 180 seconds.

Test: cli/test/commands/submit.test.ts > 'confirming presigned uploads' > 'after a gateway timeout, waits for the task to leave PENDING_UPLOADS and prints it', 'confirms again when the first confirmation cannot be running any more', 'keeps waiting when a read of the task %s' (2 rows: 'is answered 502', 'loses its connection'), 'ends with the error of a read of the task that no later read can change', 'reports the gateway timeout when the third confirmation times out too', 'does not wait or confirm again after an answer that is final'

Bug: A repeated upload confirmation is answered with the task in all six live states instead of three

After a successful confirmation a task moves on through several states. A client that repeated the confirmation, for example because the first answer was lost, got the task back while it was submitted, hydrating or running, but an error 409 'cannot accept upload confirmations' once the task was queued behind the concurrency limit, waiting for an approval, or finalizing. A repeated confirmation is now answered with the task in every state in which the task is still alive.

Gain: A retried confirmation gets the task back in all six live states instead of three, so while the task is alive a client is no longer told that a confirmation which succeeded was refused. The CLI change of this commit relies on it when it confirms again after a gateway timeout and the task has moved on in the meantime.

Test: cdk/test/handlers/confirm-uploads.test.ts > 'returns 200 idempotently when the confirmed task has moved on to %s' (QUEUED, AWAITING_APPROVAL, FINALIZING)

Bug: Uploads beyond the 50 MB limit fail the task at once with that reason, not later as an expired upload window

If the uploaded files together exceeded the 50 MB limit of a task, the confirmation deleted the files and returned an error, but left the task waiting for uploads. Repeating the confirmation then failed with 'upload not found', and after 30 minutes the task was cancelled with the reason 'Upload window expired'. The task is now failed at once with the size limit as its error message, and the files are deleted only when that change of state succeeded, as for a blocked attachment. A client can no longer post smaller files to the same upload forms and confirm again; it has to create a new task.

Gain: The task ends immediately with the real reason instead of being listed as waiting for uploads for up to 35 minutes and then reporting an expired upload window. Only API clients that declare a smaller size than they upload can get here; the CLI declares the real size.

Test: cdk/test/handlers/confirm-uploads.test.ts > 'uploads that are over the task size limit together: %s' (2 rows: 'fails the task with that reason and deletes the uploads', 'leaves the uploads alone when another call has moved the task in the meantime')

Risk: A file uploaded straight to storage as text fails the task when its bytes are not valid UTF-8 text

A file sent inline, by URL or from Linear or Jira is refused when its bytes do not match the declared type: an image must start with its signature, a text file must be valid UTF-8 without NUL bytes. Text files uploaded straight to storage, the path for everything over 500 KB, skipped that check: an archive, an executable or UTF-16 text declared as plain text was shown to the content filter as garbled text and, if the filter found nothing in it, delivered to the agent. The confirmation now applies the same check before screening and fails the task when the bytes do not match.

Gain: The path that takes the largest files follows the same rule as the four other ways an attachment arrives. A text attachment marked as passed can no longer be binary content or text in an encoding the content filter could not read.

Test: cdk/test/handlers/confirm-uploads.test.ts > 'fails the task when an upload is not what its content type declares'

fix(api): limit what the server behind a URL attachment can do to a task

Bug: A URL attachment answered with status 204 or 999 fails the task instead of crashing the orchestrator

A link attached to a task is downloaded by the orchestrator while it prepares the task. When the server behind the link answered 204, 205, 304 or a status outside 200-599 (999, for example), the code built a fetch Response object from the answer inside an event listener. The Response constructor throws for those statuses, an exception thrown there cannot be caught, and the orchestrator invocation died instead of failing the task. The answer is now kept as a plain status, headers and body, so it reaches the checks that were already written for it: a 204, a 205 without a body, a 304 without a Location header and a status outside 200-599 fail the task at once with the reason, for example 'URL attachment response has no body (status 204)'. A 205 that carries a body is taken as the file, and a 304 that carries a Location header is followed like any other 3xx answer, with the same checks of its target.

Gain: A status chosen by a remote server can no longer crash the orchestrator. Any Markdown image in a Jira or Linear issue and any --attachment URL could do it; the task now fails immediately and names the status, where before the invocation died without recording a reason. 39 lines of response handling removed and 24 added: the header copy and a second size check that could never run are gone, and a downloaded file is no longer copied again through a stream. The download path had no test at all; it now has 12, seven of them for this change.

Test: cdk/test/handlers/shared/resolve-url-attachments.test.ts > resolveUrlAttachments > 'fails with the reason when the server answers 204' (the same test for 205, 304 and 999)

Risk: The URL attachments of a task share 30 seconds; a slow server then fails its own task with the reason

Each request for a URL attachment had its own 10-second limit, but nothing limited the URL attachments of a task together: a link may be redirected twice, a task may carry ten links, and the name lookups were not timed at all. Slow servers could therefore hold the orchestrator for up to 300 seconds inside a function that is stopped after 60, so the invocation was killed before it could record the reason. The URL attachments of a task now share 30 seconds: no request starts after that, a request that is running is cut off at that moment, and the task fails with 'URL attachments could not be fetched and screened within 30s' and the URL it stopped at. A name lookup or a screening call that is running when the 30 seconds end is still not cut off: its time counts, and the task fails when it returns. A task whose links took more than 30 seconds in total but still finished inside the 60 used to get through and now fails with that message.

Gain: How long the servers behind the links of a task can keep it waiting for their answers is set by the platform (30 seconds for all of them together) and no longer by those servers (up to 300 seconds). A host that answers slowly fails its own task with the reason instead of getting the orchestrator invocation killed. Name lookups are counted but not cut off, so a slow name server can still add the time of one lookup. Measured against a local HTTPS server that takes 9 seconds per request: the call for four files ran 36 seconds before and now stops at 30.0 seconds with the reason.

Test: cdk/test/handlers/shared/resolve-url-attachments.test.ts > resolveUrlAttachments > time limits > 'gives the URL attachments of a task 30 seconds together' and 'starts no request once the 30 seconds are used up'

Risk: Linked files count against the 50 MB attachment limit of a task like every other attachment

A task may carry 50 MB of attachments in total, and every other way in (inline data, uploads, Jira and Linear files) is counted against that limit. A linked file has no size until it is downloaded, and the download never added it up: ten links to 10 MB files gave the agent 100 MB, and so did five uploads plus five links, the example in the comment that explains the limit. Each downloaded file is now added to what the task already holds, and the task fails with the same message as on the other paths as soon as the total passes 50 MB, before that file is screened or stored.

Gain: One limit for every way an attachment arrives: a task can no longer carry up to twice its limit because its files, or some of them, were given as links, and nothing over the limit is screened or stored (with ten 10 MB links, four are never requested). The 10 MB limit per file now comes from the shared constant instead of a second copy of the number.

Test: cdk/test/handlers/shared/resolve-url-attachments.test.ts > resolveUrlAttachments > 'stops at the URL attachment that takes the task over its 50 MB limit' and 'counts the attachments the task already holds toward the 50 MB limit'

fix(api): bound the secret scan of an oversized deny reason

Risk: An oversized deny reason can no longer hold the function until its timeout: 20,000 characters are scanned

The reason a user gives when denying an approval is scanned for secrets and then cut to 2,000 characters before it is stored. The scan ran over the whole text, whatever its length, before the per-user rate limit, and for some texts its time grows with the square of the length, so one very long reason could keep the function busy until its 15-second timeout. A reason longer than 20,000 characters now has only its first 20,000 characters scanned. The stored text stays what it was for every reason of up to 20,000 characters, and for a longer one unless more than nine tenths of its first 20,000 characters lie inside what the scan replaces by a marker, whether it reads the whole reason (as before) or only that start (as now). For a private key the scan replaces everything from a BEGIN line to the next END line, ordinary text included. In such a reason the stored text can end earlier than before, and a secret that lies across the limit is not recognised, so its first part can be stored. Example: a key block that has lost its END line at the start of the reason, then 19,000 characters of ordinary text, then a complete key block. Before, one marker replaced everything from the first BEGIN line to the END line; now the first key is stored.

Gain: A single request with an oversized reason can no longer hold the deny function for its whole timeout, and such a request was never counted by the rate limit. Measured on a laptop for a reason of 540,000 characters that repeats the header line of a private key 20,000 times: 3.3 s before and 5 ms after when it is the first reason the process scans, 1.2 s and 2 ms once the process has scanned an ordinary reason. Before, the time quadrupled with each doubling of the length. An ordinary reason of that size took 4 ms before. Not measured on Lambda, where this function has about a seventh of a vCPU.

Test: cdk/test/handlers/deny-task.test.ts > 'scans only the first 20,000 characters of an oversized reason' (red: pins the bound) and 'stores an ordinary reason longer than 20,000 characters as if all of it were scanned' (passes before and after: the stored text is unchanged)

fix(api): read auth headers in any casing and log each API key use

Bug: The API-key and webhook authorizers find their headers whatever the casing of the header name

HTTP header names are not case-sensitive, but the two request authorizers found a header only when its name was spelled exactly as in the documentation or all in lower case. A script whose HTTP library sends the name as X-Api-Key (Ruby's Net::HTTP does that whatever the author types) was refused with a valid API key and got a plain 403. Both authorizers now read their headers through one shared helper that ignores the casing of the name.

Gain: A valid API key is accepted whatever casing the client's HTTP library gives the header name; before, such a client got 403 on every call to the webhook management routes. The casing that reaches the authorizer is not in the project's hands: API Gateway documents that an edge-optimized REST API (the default type, which this API has) capitalizes header names and that a Regional one passes them on as sent. The hand-written lookups of the two authorizers become one helper of 7 lines with its own tests.

Test: cdk/test/handlers/api-key-authorizer.test.ts > 'reads the header case-insensitively (X-Api-Key)', '(X-API-KEY)' and, on the JWT path, '(AUTHORIZATION)'; cdk/test/handlers/webhook-authorizer.test.ts > 'reads the headers case-insensitively (X-WEBHOOK-ID)'; cdk/test/handlers/shared/gateway.test.ts > getHeader (3 tests)

Risk: Each allowed use of an API key is logged, and the log line of a new webhook names the key that made it

When a request was allowed on an API key, the authorizer wrote nothing: it logged refusals only, and the log line for a new webhook did not say which key had created it. After a key leaked, an operator could revoke it but could not see what it had been used for. The authorizer now writes one line for each allowed use (the key's id, its owner, the method and the route), and the 'Webhook created' line carries the id of the key when a key made the request. The secret part of a key is never written.

Gain: A leaked key can be investigated: the logs show every call it made and which webhooks it created, so those can be revoked along with it. Before, the logs showed the requests but not that a key had made them, or which key, and a webhook made with it could not be told from the owner's own. Two log statements; no change to the API, the tables or any permission.

Test: cdk/test/handlers/api-key-authorizer.test.ts > 'logs each allowed use of a key: the key, its owner and the method'; cdk/test/handlers/create-webhook.test.ts > 'the "Webhook created" log line' > 'names the API key when the request was authorized by one' and 'has no key for a request authorized by a Cognito token'

Bug: A revoked webhook stops authenticating as soon as its revocation has returned

The webhook authorizer read the webhook's record with the database's default read, which may still return the state from before a change that has already been confirmed. A request that arrived right after a webhook was revoked could therefore be let through and start a task. The authorizer now asks for a strongly consistent read, as the API-key authorizer already does.

Gain: Revoking a webhook holds for the very next request. Before, there was a short window in which a webhook whose revocation had been confirmed to the user could still start an agent run. One line; the read costs one read unit instead of half.

Test: cdk/test/handlers/webhook-authorizer.test.ts > 'does a strongly-consistent GetItem by webhook_id'

Bug: A webhook or API key name that is not a string is refused with 400 instead of being stored

Creating a webhook or an API key with a name that is not text, for example the number 42 or the value true, was accepted: the name check converted the value to text before testing it, and the number was stored. The list command of the CLI then stopped with 'padEnd is not a function' for that user until the webhook or key was revoked. The shared name check now refuses anything that is not a string, so both requests answer 400.

Gain: A malformed request can no longer break the caller's own 'bgagent webhook list' or 'bgagent api-key list', and a stored name is always text, as the API types say. One line in the check that both handlers use.

Test: cdk/test/handlers/shared/validation.test.ts > isValidWebhookName > 'rejects a name that is not a string'; cdk/test/handlers/create-webhook.test.ts > 'returns 400 for a name that is not a string, and stores nothing'

The tests of the authorizer on the webhook management routes replaced the Cognito token verifier with a stand-in, so nothing checked which tokens the real one accepts: letting it take access tokens, or tokens of any app client, passed the whole suite. A new test file runs the real verifier on tokens signed with a key pair that is made when the test runs. No key is stored in the repository and there is no network call: the test supplies the signing key and fails if the verifier tries to download one. It pins the rules as they are today, one test per rule: an ID token of the CLI's app client is accepted; an ID token of another app client of the pool, an access token, a token of another user pool, an expired token and a token signed with another key are refused, each for its own reason. Gain: a change that relaxes one of these rules now fails a test. Four such changes were tried on a scratch copy: dropping the token-use rule, the audience rule or the expiry check each fails exactly the test of that rule, and trusting another pool fails all six. No product change; one new test file of 137 lines with 6 tests.

The handler behind the webhook authorizer read the signature header again with the two old spellings, so a request that sent X-WEBHOOK-SIGNATURE passed the authorizer and was then refused with "Missing X-Webhook-Signature header", and an Idempotency-Key in another casing was ignored without a word. The handler now reads both headers through the same helper as the authorizers, and an event without headers is answered 401 instead of 500. So the webhook authorizer and the handler behind it read their headers in any casing. Not shown: API Gateway itself checks that the two identity-source headers are present before it calls the authorizer, and how that check treats another casing was not tried on a deployed API.

fix(api): refuse malformed task input and let a retried upload finish

Bug: An issue_number has to be a positive integer, as a pr_number already had to; null counts as absent

The API stored whatever a request sent as issue_number. Zero, a negative or fractional number or a text that is not a number were accepted; the task was created and later failed or ran without its issue, because GitHub has no such issue. A null, which typed clients send for a field they leave out, was stored too and became 'Resolves #null' at the top of the pull request. A text with dot segments, such as ../../../other-org/private-repo/issues/7, went unchanged into the address of the GitHub request, so the token of the task's repository read an issue of another repository into the task. An issue number now has to be a positive integer, the rule a pull request number already had, and null counts as absent. One request that worked is refused by this rule: a number sent as text ("issue_number": "42") reached its issue before and is answered 400 now, as it always was for pr_number. The API contract asks for a number, and the CLI, the web console and the Slack path send one.

Gain: A wrong issue number is answered with a 400 that names the field, where the task used to be admitted and then failed at hydration or ran without the issue. Pull requests of clients that send null no longer start with 'Resolves #null', and no request for /issues/null is made. A caller can no longer make the platform read an issue of a repository other than the task's with that repository's GitHub token. About 10 lines of product code; the rule is the existing one of pr_number.

Test: cdk/test/handlers/shared/create-task-core.test.ts > 'returns 400 for issue_number %j' (0, -1, 1.5, "12", a text with dot segments), 'takes an issue_number of null for an absent one', 'stores a valid issue_number on the task and on its task_created event'

Bug: A replayed Idempotency-Key for a task that still waits for uploads returns new upload instructions

A task with attachments too large to send inline is created waiting for uploads, and the answer to that request held the only copy of the upload instructions. When the upload or its confirmation failed and the user ran the same bgagent submit again with the same idempotency key, which is what the key is for, the API answered with the task alone. The CLI found nothing to upload, printed the task and exited with success; the task was cancelled half an hour later and the key stayed bound to it. A replay for a task that still waits for its uploads now carries new upload instructions for the uploads that are still missing, so the second run uploads and confirms.

Gain: A retried submit with large attachments completes. Before, the second run reported success for a task that could never start, and the user found out when it was cancelled 30 minutes later. The design document of the attachment feature already asked for upload instructions on such a replay; that part had not been built. The instructions are now made from the stored attachment records alone, which removes three parameters and the pairing of two lists by position. Nothing changes for a task that has left the upload stage or for a replay without attachments.

Test: cdk/test/handlers/shared/create-task-core-upload-instructions.test.ts (new) > 'a task that still waits for its uploads comes with new instructions for them' (red), 'a task that has left PENDING_UPLOADS comes without instructions', and 'answers 202 with one instruction for each attachment the client has to upload' (the creating request; it passes before and after the change)

Bug: A malformed attachments value gets a 400 with the reason, not a lost attachment, a dead task or a 500

Three malformed attachment shapes passed validation. One attachment object where a list is expected counted as no attachments, so the task was created without it and nothing told the client. An image or file entry with a url (only entries of type url are fetched), or with data that is not text, passed for an upload the client would make later: the task was created waiting for an upload nobody would make and was cancelled 30 minutes later. An entry of null crashed the request with a 500. All of them are now answered with a 400 that says what is wrong.

Gain: A client mistake in the attachment shape is reported at submit. Before, the same mistake produced a task without its attachment, a task that waited 30 minutes for an upload and was then cancelled, or an anonymous 500. 17 lines added and 9 removed in one function, which keeps its recorded complexity of 44.

Test: cdk/test/handlers/shared/validation.test.ts > 'rejects attachments that are not a list', 'rejects an entry that is null', 'rejects a url on an attachment of type image', '... of type file', 'rejects data that is not a string', 'takes attachments of null for none'; cdk/test/handlers/shared/create-task-core.test.ts > 'returns 400 for attachments that are not a list, instead of creating the task without them'

Bug: A next_token that cannot be decoded is refused with 400 instead of restarting the list at its first page

The four list endpoints (tasks, task events, webhooks, API keys) hand out a next_token for the following page. A token that could not be decoded, for example one that lost its end in a copy or a URL, was taken for no token at all: the list started again at its first page with status 200. A client that pages through the list got the first page again where it expected the next one and processed those items a second time; a client whose every token arrives damaged never got past the first page. A token that does not decode to a JSON object is now refused with 400 'Invalid next_token.', before anything is read. A token that decodes to an object which is not a key of the list is still handed to DynamoDB and ends in a 500, as before.

Gain: A damaged token is reported to the client instead of silently restarting the list, so a paging client cannot loop or process items twice. 20 lines of product code in the shared decoder and the four handlers; one test per handler, and the test that task events turn a valid token into the start key, which was missing.

Test: cdk/test/handlers/list-tasks.test.ts, get-task-events.test.ts, list-webhooks.test.ts, list-api-keys.test.ts > 'returns 400 for a next_token that cannot be decoded'; cdk/test/handlers/shared/validation.test.ts (decode)

Bug: A task_description or deny reason that is not a string gets a 400 naming the field, not a 500

Request bodies are JSON, so a field can arrive with any JSON type. A task_description that was a number, an object or a list crashed the create request and the caller got a 500 'Internal server error'; with an issue number beside it the answer was a 400 with the wrong reason ('exceeds maximum length'), or the request crashed later, after the content screening call. A deny reason of the wrong type crashed the deny request in the same way. Both are now answered with a 400 that names the field: 'Invalid task_description. Must be a string.' and 'Invalid reason. Must be a string.'

Gain: A malformed request gets a 400 with the name of the field instead of an anonymous 500 and an ERROR line in the handler's log. 9 lines of product code in two handlers.

Test: cdk/test/handlers/shared/create-task-core.test.ts > 'returns 400 for a task_description that is %s' and '... that is %s beside an issue number' (a number, an object, a list), 'takes a task_description of null for an absent one'; cdk/test/handlers/deny-task.test.ts > '400 when reason is %s' (a number, an object, a list), 'a reason of null is no reason'

The Slack command processor kept its own copies of the two size limits of inline attachments (500 KB per file, 3 MB per task), because the module that defines them belonged to other changes of this pull request when the Slack fix was made. The two constants are now exported from the validation module and the copies are deleted, so the limit the Slack processor checks and the limit task creation enforces cannot drift apart. No behaviour change; 6 lines fewer.

fix(api): log an invalid policy set under its own message

Bug: The log line of an invalid policy set keeps its message and carries the parser text in the field error

When the Cedar policies of a repository do not parse, listing its policies answers 503 and writes an error line to the log. The handler passed the parser's text to the logger in a field named message, and a field of that name replaces the message of the line: the line read 'cedar-wasm rejected policy set' and did not contain the handler's own text, 'Cedar parse failure for repo policies'. The parser's text now goes into the field error, and the line keeps its message.

Gain: A search of the log group for 'Cedar parse failure' finds the line of an invalid policy set; before, it found nothing. This was the only one of the 950 log calls in the platform's Lambda code that passed a field named message, so no other line was affected. One word of product code.

Test: cdk/test/handlers/get-policies.test.ts > 'logs an invalid policy set under its own message, with the text of the parser in 'error''

fix(api): hide expired approval requests and wire the per-user cap

Bug: The pending list leaves out approval requests whose window has passed and reads past up to 2,000 of them

The list of pending approvals (bgagent pending, and the approvals inbox of the console) showed requests whose time window had already passed. That happened whenever the agent was gone when its window ended and so could not close its request: its container had died, or, on MicroVM compute, the platform had terminated it because the task was cancelled while it waited. The request then stayed in the list, with an expiry time in the past, until the database's own cleanup removed it, which can take days. The list now leaves such requests out, and it reads on past them, 2,000 rows at most, until it has found the live requests, so that a pile of expired ones no longer pushes a live one off the list. The bound is there because a user can leave such rows faster than the database deletes them; when it is reached, a warning is logged.

Gain: Users and the console no longer see an approval request once its window has ended: before, a request whose agent was gone by then stayed in the list for up to days. Until its window ends such a request is still listed (five minutes by default, an hour at most). A user with more than 100 pending rows now still gets the live ones among the first 2,000 (before, the first 100 rows were returned whatever they were). The price is one more database read per 100 rows, 20 at most, and only for a user who has 100 pending rows or more. 52 lines added and 12 removed in one handler, 6 unit tests and 1 emulator test.

Test: cdk/test/handlers/get-pending.test.ts > 'leaves out a request whose approval window has passed' (the issue's case), with 'lists a request up to the last second of its window and not from its end on', 'keeps a request that has no window to pass, however old it is', 'reads past a page of requests whose window has passed to a live one behind it', 'lists at most 100 requests and stops reading once it has them' and 'stops after 20 pages of requests whose window has passed' (20 queries, an empty list and the warning in the log); cdk/test/emulator/task-api.emulator.ts > '#1043: pending lists the request that can still be decided, not the one whose window has passed' (run on emulator 1.0.489 with the integration tier)

Bug: The stack passes its per-user task limit to the task API and the queue pickup, not only to the orchestrator

The stack keeps the number of tasks one user may run at a time in a single constant, but did not hand it to two of the components that use it: the task API (queue wait estimate, admission of tasks with attachments) and the job that picks queued tasks up again. Both fell back to a built-in 10, which is also the constant's value today, so nothing was wrong yet. On the day someone changes the constant, the orchestrator would have admitted tasks against the new limit while those two went on counting against 10; the constant is now declared before its first use and passed to both.

Gain: A change of the per-user limit now reaches all eight functions that read it; before, it reached five. A deployment today gives every function the value it had: synthesized in four configurations, the templates before and after differ only in the timestamps of the run and in what any change to a cdk source file changes, the fingerprint of the agent image and two generated resource names. A new stack test fails as soon as one function gets a different limit. 12 lines added, 5 removed.

Test: cdk/test/stacks/agent.test.ts > 'every function that reads the per-user concurrency cap gets the one the orchestrator admits against'

@krokoko

krokoko commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor Author

Linear, Jira, Slack and GitHub integrations (part 1 of 2): what changes and what it gains

fix(jira): ignore ABCA's own comments and another site's stored graph

Bug: On a Jira site without the Forge app, ABCA no longer answers its own orchestration panel as an instruction

On a Jira site that has not installed the Forge app, ABCA posts its comments with the setup user's OAuth token, so Jira shows them as written by a person and delivers them back to ABCA as new comments. The orchestration panel was not among the texts ABCA recognises as its own, and its retry hint spells out the @bgagent mention, so a panel posted in the failed state was read as an instruction and answered with 'I couldn't find an ABCA pull request for this Jira issue'. The three panel headings are now recognised as ABCA's own, whether Jira hands the bold heading back as plain text or with an asterisk.

Gain: Sites on the OAuth fallback no longer get a wrong failure reply under an orchestration panel. That happened for every panel first posted in the failed state (for example when all subtasks are refused for an exhausted budget) and for any panel whose subtask title contains the mention. 8 lines in the comment guard, 4 tests.

Test: cdk/test/handlers/shared/comment-trigger.test.ts > 'does not trigger on the orchestration panel when it is finished with failures' (also 'in progress' and 'complete') and 'does not trigger on a panel whose bold heading arrives as wiki text'

Bug: A Jira issue adopts a stored orchestration only from its own site, so a site change cannot start old tasks

An orchestration is stored under a hash of the bare issue key, so after a change of Jira site (a pilot site revoked, the production site onboarded) the old site's rows can sit under a key that the new site uses too. The processor adopted such rows without comparing the site: a plain issue with that key was dropped with no task and no comment, and '@bgagent retry' on it reset and released the old site's failed subtasks, with the old site's repository and user. The processor now treats a stored graph as this issue's only when it was written for the same site.

Gain: After a site change, an issue whose key was once an orchestration parent runs as a normal task instead of being silently ignored, and a retry comment can no longer start the old site's tasks in the old site's repository. Two conditions. An epic with such a key is still refused with the existing collision message.

Test: cdk/test/handlers/jira-webhook-processor-orchestration.test.ts > 'a graph stored under the same issue key by another Jira site' > 'does not stop a plain issue from running as a single task' and 'is not retried by a comment on this site'

Bug: The run that loses the race to create a Jira orchestration deletes its attachment copies from S3

When the trigger label is added to a new epic twice within seconds, two processor runs both store the epic's attachments, and the run that loses the race to create the orchestration is meant to delete its copies. The code for that was guarded by a condition that can never be true, because the shared discovery step reports the race as an extension of the existing orchestration. The cleanup now runs where the race actually arrives, and the unreachable branch is deleted.

Gain: The losing run no longer leaves its attachment objects in S3 until the bucket's lifecycle rule removes them. 9 unreachable lines deleted, 7 added; the main handler's complexity goes from 116 to 115.

Test: cdk/test/handlers/jira-webhook-processor-orchestration.test.ts > 'deletes its own attachment copies when a concurrent delivery seeded the graph first'

Bug: ABCA's refusal of a Jira retry from an unlinked account no longer starts an agent run on the pull request

On a Jira site that has not installed the Forge app, ABCA's refusal of a retry from an unlinked account ('I can only retry an orchestration for a linked ABCA user ... comment @bgagent retry again') came back to ABCA as a human comment with a mention. It started with no marker that ABCA recognises as its own, so the processor took the sentence for an instruction and started a pull-request iteration task with it on the issue's existing pull request. The refusal now starts with the same marker as ABCA's other failure comments, which the processor ignores.

Gain: No agent run, and no push to a reviewer's pull request, caused by ABCA's own refusal. Before, on a site without the Forge app, every '@bgagent retry' from an unlinked account on an issue with an ABCA pull request started one, charged to the person who ran 'bgagent jira setup' when that person's Jira account is linked to an ABCA user, and to the original task's owner otherwise. One reworded string.

Test: cdk/test/handlers/jira-webhook-processor.test.ts > 'comment-triggered PR iteration' > 'does not take its own refusal of an unlinked retry for an instruction'

Bug: When ABCA cannot get a Jira access token, a site with the Forge app gets a failure comment with the remedy

When ABCA cannot get a Jira access token for a site, for example because the person who authorized it revoked the app or a rotated refresh token was lost, every trigger that would otherwise have started work (a trigger label from a linked user, or an @bgagent comment asking for a change to an issue's existing pull request) was dropped with nothing on the issue; only the Lambda log said why. A site that writes through the Forge app can still post a comment in that state, because that path does not use the token. The processor now posts a failure comment there: nothing was started, try again in a few minutes, and if it keeps failing an admin has to re-run 'bgagent jira setup'.

Gain: A Jira user whose trigger cannot run because the site's authorization is dead, or because the token refresh failed, is told so on the issue with the remedy, instead of watching the label do nothing until somebody reads the Lambda log. Two calls and one message. Sites that are unregistered, inactive or left without a working identity stay silent as before.

Test: cdk/test/handlers/jira-webhook-processor.test.ts > 'drops the event and says so on the issue when no Jira access token resolves' and 'comment-triggered PR iteration' > 'says so on the issue when no Jira access token resolves for the iteration'

Bug: A Jira webhook body of JSON null and a numeric account-link code are answered with 400 instead of 500

Two malformed requests ended in HTTP 500 with an error line in the log instead of 400. One is a Jira webhook delivery whose body is the JSON value null: it failed before the signature was checked, so anyone could send it. The other is an account-link request whose code is a number instead of a string. Both are now answered with 400, like the other malformed bodies.

Gain: Two inputs stop producing a 500 and an ERROR log line that reads like a server fault; the webhook one needed no valid signature. Five lines.

Test: cdk/test/handlers/jira-webhook.test.ts > '400s on a body of null, which parses but is not an envelope'; cdk/test/handlers/jira-link.test.ts > '400s when the code is not a string'

fix(slack): keep retried deliveries from losing or repeating messages

Bug: The final Slack message of a task is posted on a retry after a Slack outage instead of being lost for good

The final Slack message of a task (completed, failed, cancelled, timed out, stranded) and the agent-error alert are guarded by a marker on the task, so that each is posted once. The marker was written before the post and never removed. When the post then failed with something worth retrying (a Slack rate limit or outage, a network error, a throttled secret read), the retry found the marker, logged 'already sent' and skipped: the message was lost for good and the thread kept showing the task as running. The marker is now written only when the post is about to be made, and it is removed again when the post fails in a way that will be retried. A Slack error that no retry can fix keeps the marker, as before. The price: when Slack accepted a post but its answer did not arrive, the retry posts that message a second time.

Gain: Users get the outcome of their task and the View PR button when a Slack rate limit, a Slack outage or a Secrets Manager blip clears within the stream's three retries; before, the first such failure lost the message for good. A failure that outlasts the retries now ends in the dead-letter queue with its alarm instead of behind a log line that said 'already sent'. Quality gate: the dispatcher function drops from complexity 46 to 39, under the ceiling of 40, so its eslint-disable exemption is deleted.

Test: cdk/test/handlers/slack-notify.test.ts > 'the retry of a terminal event whose post was rate-limited posts the message'; also 'a network error on the post gives the slack_notified_terminal claim back (task_completed)', 'an unparsable Slack answer on the post gives the slack_dispatched_agent_error claim back (agent_error)', 'a terminal Slack error keeps the dedup claim (no retry is coming)', 'a bot-token read that fails leaves no dedup claim behind', 'a claim that cannot be given back is logged and does not hide the post failure'

Bug: A replayed 'task created' or 'agent started' record no longer posts and deletes a duplicate Slack message

When the event stream delivers a 'task created' or 'agent started' record a second time (it does so whenever an earlier record of the same batch fails, for example one whose GitHub comment was rejected: the stream then repeats that record and every record after it), the Slack dispatcher posted the message again, reset the reaction on the user's message and then deleted the duplicate. Users saw a message appear and disappear, with a notification each time, and a task that had already finished could end up with the hourglass next to its check mark. The dispatcher now skips such a record when the task already records the message that this event posted.

Gain: No duplicate 'Task submitted' or 'Agent started working' notifications while another channel is failing, no stale hourglass on a finished task, and four Slack API calls and one failed DynamoDB write fewer per replayed record.

Test: cdk/test/handlers/slack-notify.test.ts > 'a replayed task_created does not post again when slack_created_msg_ts is already recorded', 'a replayed session_started does not post again when slack_session_msg_ts is already recorded'

Bug: A Slack mention whose first delivery failed outright is processed on Slack's first retry, not dropped

When Slack could not deliver a mention or a direct message the first time (the endpoint answered with an error, for example because a secret read or the API gateway was throttled), Slack sent the event again, and the endpoint acknowledged every such retry without doing anything. The request vanished: no reaction, no reply, no task. The first retry is now processed when Slack reports that the first delivery failed outright. A retry that follows a delivery that was only too slow, and every second or third retry, is still acknowledged without processing, so a mention still cannot be submitted twice.

Gain: A transient failure of the first delivery no longer silently drops a user's task request when the retry that Slack sends right away gets through; before, every mention whose first delivery got a 5xx or 429 answer was lost. No new way to create a duplicate task. 20 lines added, 2 removed in the handler.

Test: cdk/test/handlers/slack-events.test.ts > 'processes the first retry of a mention whose first delivery got an HTTP error'; guards: 'drops retry 1 of a mention with reason http_timeout without reprocessing', 'drops retry 1 of a mention with reason unknown_error without reprocessing', 'drops retry 2 of a mention with reason http_error without reprocessing'

fix(linear): tell commenters why nothing started and end a reply loop

Bug: The Linear bot recognises two more of its own replies, which ends a reply loop one comment could start

Two replies that the Linear bot posts under a comment name the bot's own handle but did not start with one of the markers by which the bot recognises its own comments. Linear delivers the bot's comments back to it, so the reply to a commenter without a linked ABCA account was read as a new request from an unlinked user and answered again, and that answer again, without end. The reply to a bare mention on an issue whose task ended without a pull request started the same loop. Both replies now start with the waving-hand marker, so the bot ignores them when they come back.

Gain: Ends a reply loop that a single comment could start: any workspace member without a linked account who mentions the bot, or a linked user who sends a bare mention on an issue whose last task ended without a pull request. Each round was two Lambda runs, a reaction and a reply that notifies the issue's subscribers, and nothing stopped it short of a failing Linear call (the rate limit is 5,000 requests per hour per workspace).

Test: cdk/test/handlers/linear-webhook-processor-orchestration.test.ts > 'the reply to an unmapped commenter is not itself a trigger when Linear delivers it back' and 'the bare-mention reply is not itself a trigger when Linear delivers it back'

Bug: A Linear comment whose task is refused gets the reason in place of 'On it' and a cross instead of eyes

When the bot accepts a comment it puts an eyes reaction on it and replies 'On it' before it tries to create the task. If the task was then refused (monthly budget exhausted, text blocked by the content policy, repository no longer onboarded, platform temporarily unavailable) or the call failed, the 'On it' and the eyes stayed for good and the commenter was never told why nothing happened. A file in the comment that could not be screened was reported, but as a second reply under the stale 'On it'. Now the 'On it' reply itself is turned into the reason and the eyes into a cross, on all four comment paths: iteration on a sub-issue, iteration on a plain issue, new work, and the answer to a clarifying question. A budget refusal is reported without amounts, because the task is billed to the user whose task the comment continues, who need not be the commenter. For a temporary outage the reply says to comment again, not to re-apply the label.

Gain: A commenter whose request was refused reads the reason (for example that the text was blocked by the content policy, or that the monthly budget the work is billed to is exhausted) and sees a failed marker, instead of a permanent 'On it'. Four dispatch paths were silent; the label path and the Jira comment path already reported.

Test: cdk/test/handlers/linear-webhook-processor-orchestration.test.ts > 'a comment whose task could not be created' (9 tests) and 'a refused iteration routed from the epic is settled on the epic, where the comment lives'

Bug: A Linear label event processed twice no longer posts a false failure comment on a running task

When the Linear processor ran twice for the same label event (Lambda retries an asynchronous invocation after a timeout or a crash), task creation answered the second run with the task the first run had created, marked as a replay. The processor treated every answer other than 'created' as a failure, so it posted 'ABCA couldn't create this task (status 200)' and a cross reaction on an issue whose task was running. A replay is now recognised: the files the second run uploaded are still deleted, and nothing is posted.

Gain: No false failure comment and cross reaction on an issue whose task is running when a label event is processed twice. The Jira processor already made this distinction.

Test: cdk/test/handlers/linear-webhook-processor.test.ts > 'an idempotent replay (createTaskCore 200) is not reported as a failure'

Bug: A comment to the bot on a Linear sub-issue without a pull request gets a reply that says its state

A comment addressed to the bot on a sub-issue of an orchestrated epic got no answer at all when the sub-issue had started but had no pull request: the comment was logged and dropped. It now gets a reply under the comment and a question-mark reaction: that the sub-issue failed before opening a pull request and that '@bgagent retry' re-runs it, that its task record could not be read, or otherwise that it has no pull request to iterate on. A comment on a sub-issue the epic has not started yet was answered 'I don't have a task linked to this issue ... re-apply this project's trigger label'; a label on such a sub-issue starts a second, separate run of work the epic runs anyway. That answer now says the sub-issue runs as part of its epic and has not started, or that it did not run and can be retried from the epic.

Gain: A reviewer who addresses the bot on a failed, running or waiting sub-issue learns its state and what to do next, instead of being ignored or being told to re-apply the label, which duplicates the sub-issue's work.

Test: cdk/test/handlers/linear-webhook-processor-orchestration.test.ts > '@bgagent on a started sub-issue that has no pull request' (4 tests) and '@bgagent on a sub-issue its epic has not started' (2 tests)

Bug: A retry or follow-up on a plain Linear issue runs with the earlier task's description plus the comment

When a follow-up comment starts new work on an issue whose earlier task ended without a pull request, the new task was given only the text of the comment. '@bgagent retry' on a failed issue started an agent whose whole task was the word 'retry', although the agent cannot read Linear and is told that the issue is in its task description. The new task now gets the description the earlier task had (the issue title and text, with the documents and comments collected at that time), then a short note and the reviewer's follow-up. If the two together exceed the 10,000 character limit, the earlier description is cut from its end and the follow-up is kept whole; a follow-up that is itself longer than the limit is refused, as before.

Gain: A retry or a follow-up on a plain issue runs with the issue it is about, instead of spending a task, and possibly a pull request, on a sentence without context.

Test: cdk/test/handlers/linear-webhook-processor-orchestration.test.ts > 'new work from a follow-up is given the issue, not only the comment' (3 tests)

fix(slack): stop taking the first slash word of a mention as repo

Bug: A Slack file over the inline limits (500 KB, 3 MB per message) is refused by name before it is downloaded

Files attached to a Slack mention are handed to task creation as inline attachments, for which its limits are 500 KB per file and 3 MB per task. The Slack side checked for 10 MB per file instead, so a 1.2 MB screenshot that the processor had downloaded was passed on and then refused with 'inline data exceeds 500 KB limit. Use presigned upload for larger files', an instruction that means nothing in Slack. The processor now applies the real limits before it downloads a file, and again to what it downloaded, and its reply names the file that is too large or that takes the message over 3 MB. This corrects the refusal only: a file within the limits still cannot create a task. The Slack processor is given no attachment bucket, so task creation answers 'Attachment storage is not configured' to every file it has accepted, and the app does not request the files:read scope that Slack documents as required for the download. Neither is fixed in this pull request.

Gain: A Slack user whose file is too large reads the limit that task creation enforces and the name of the file, instead of an error about an upload method that Slack does not have, and that file is no longer downloaded. The Slack side and task creation state the same two limits, where they differed by a factor of 20 (the processor keeps its own copy of the two numbers; four boundary tests fail when the copies disagree).

Test: cdk/test/handlers/slack-command-processor.test.ts > 'file attachments' > 'refuses a file over the 500 KB inline limit before downloading it', 'refuses a file that turns out larger than Slack declared', 'refuses files over the 3 MB inline total, without downloading the one that exceeds it', and four boundary cases '... handed over exactly when validateAttachments takes it' (exactly 500 KB, 500 KB and one byte, exactly 3 MB together, 3 MB and one byte together)

Bug: A Slack request that fails with an unexpected error gets ❌ in place of 👀, like the other refusals

When the Slack command processor failed with an unexpected error, for example because DynamoDB throttled the write of the task, it replied 'Something went wrong' but left the 👀 reaction on the user's message. That reaction means 'received', so the request looked accepted although no task existed. The processor now swaps 👀 for ❌ in that case too, as it already did when the account is not linked, when no repository is found, when an attachment is refused and when task creation rejects the request. It now does the same on the one other answer that left 👀 in place: that the bot cannot post in the channel.

Gain: A request that fails with an unexpected error, or that is refused because the bot cannot post in the channel, now looks failed like the four refusals that already swapped the reaction: the processor does it on each of the six paths on which it answers a mention without creating a task. 14 lines.

Test: cdk/test/handlers/slack-command-processor.test.ts > 'an unexpected error swaps :eyes: for :x: on the mention', 'a reaction swap that fails after an unexpected error does not fail the invocation', 'a refusal because the bot cannot post in the channel swaps :eyes: for :x: too'

Bug: Slack messages round a task's duration before splitting it: '2m' instead of '1m 60s'

The duration in the Slack messages 'Task completed' and 'Task timed out' was split into minutes and seconds first and rounded afterwards. A task that ran 119.7 seconds was reported as '1m 60s', one of 59.6 seconds as '60s' and one of 3599.6 seconds as '59m 60s'. The duration is now rounded once, before it is split: '2m', '1m' and '1h'.

Gain: No more impossible durations in Slack messages. It hit every task under an hour whose runtime ended in the last half second of a minute, about one in 120 (the agent stores the duration with one decimal). The Slack formatter now agrees with the two other duration formatters in the code. Three lines changed, none added.

Test: cdk/test/handlers/shared/slack-format.test.ts > 'rounds 59.6 once, before splitting off the minutes: 1m', '... 119.7 ...: 2m', '... 3599.6 ...: 1h'

Bug: A Slack bot token scheduled for deletion counts as absent, so removing the app no longer raises the alarm

When a workspace removes the Slack app, its bot token is scheduled for deletion with a seven-day recovery window. During that window Secrets Manager refuses to read the token with an error that the code did not take for 'no token', so an event of one of that workspace's tasks counted as an infrastructure failure. A 'task created' or 'agent started' event was retried three times, together with the records behind it in the batch, and then sent to the dead-letter queue, which raises the alarm 'notifications are failing'; a final event failed once and was skipped as already sent on the retry. A bot token that is scheduled for deletion is now treated like one that does not exist, and the event is skipped. This holds for bot tokens only: the app's signing secret and its OAuth credentials in that state remain an error, so a request that cannot be verified is still refused.

Gain: Removing the app from a workspace no longer pages the operator or replays other tasks' records. The fix for lost final messages earlier in this pull request depends on it: since that fix, the final event of every task still running in such a workspace would otherwise end in the dead-letter queue. Ten new lines, three changed.

Test: cdk/test/handlers/shared/slack-verify.test.ts > 'getSlackSecret' > 'returns null for a secret that is scheduled for deletion', 'rethrows the same error for a secret that is not a bot token', 'rethrows an InvalidRequestException that is not about a pending deletion'; cdk/test/handlers/slack-notify.test.ts > 'a workspace whose bot token is scheduled for deletion is skipped, not retried'; cdk/test/handlers/slack-events.test.ts > 'refuses an unsigned url_verification when the signing secret is scheduled for deletion'

Bug: The Slack install page reads the app credentials on every call, so a corrected secret works at once

The page that completes the installation of the Slack app read the app's client ID and client secret through a five-minute cache. An operator who had stored a wrong secret, saw 'bad_client_secret', corrected it and opened the install link again got the same error for up to five minutes, because the warm function still used the old value. The page now reads both credentials from Secrets Manager on every call.

Gain: A corrected credential works on the next click instead of five minutes later, so first-time setup no longer sends operators into deleting and recreating the Slack app, which is what the setup guide suggests for this error. The cache saved nothing there: an installation runs once. Two arguments added.

Test: cdk/test/handlers/slack-oauth-callback.test.ts > 'uses credentials stored since the previous callback'

Bug: The Slack account-link endpoint answers 400 instead of 500 when the code in the body is not a string

The endpoint that links a Slack account answered 500, with an error line in the log, when the code in the request body was not a string (a number, for example), because it called a string method on it. It now answers 400 'Request body must include a code field', as for a missing code. The Jira link endpoint got the same one-line correction earlier in this pull request.

Gain: A malformed request from a signed-in client gets a 400 and no longer writes an ERROR log line that reads like a server fault. One line; the Slack copy of the check is now identical to the Jira copy.

Test: cdk/test/handlers/slack-link.test.ts > '400s when the code is not a string'

Bug: In a channel with a default repository, a mention with CI/CD, and/or or a file path is no longer rejected

In a Slack mention the first word with a slash in it was taken as the repository. In a channel with a default repository, 'fix the CI/CD pipeline' was therefore rejected with 'Repository CI/CD is not onboarded', like any sentence with 'and/or', '24/7' or a file path, and a repository named after such a word was not found either. The repository is now the first word that carries an issue number or names an onboarded repository (or an earlier word of the same owner). Without one, the channel's default repository gets the whole message, unless a word has the owner of that default; with no default either, the first slash word is taken, as before. One answer changes on purpose: a repository that is not onboarded, is written without an issue number and has another owner than the repository the message resolves to (for example 'update the README in other/web' in a channel whose default is acme/api) is no longer answered with 'not onboarded' but read as ordinary text, so the task starts on the channel's default repository, or on the onboarded repository named in the same message. The same now happens to a pasted GitHub link, whatever repository it points to, an onboarded one and one of the default's owner included: a link is still not read as its repository, so in a channel with a default the task starts on the default.

Gain: Members of a channel with a default repository can write ordinary sentences about code: CI/CD, and/or, yes/no, 24/7, file paths and pasted stack traces were all rejected before. An onboarded repository, or one written with an issue number, is found wherever it stands in the message. The events handler loses its own copy of the repository pattern and the reordering of the user's words (21 lines removed, 6 added there). The cost is one read of the repository table per distinct slash word until a repository is found: one or two in a normal sentence.

Test: cdk/test/handlers/slack-events.test.ts > 'forwards the text of a mention as written: ...' (CI/CD and client/server cases); cdk/test/handlers/slack-command-processor.test.ts > 'repo and description of a mention' > 'an onboarded repo is the repo wherever it stands, also behind other slash words', 'a repo with an issue number is the repo wherever it stands, also behind other slash words', 'a slash word that is no onboarded repo leaves the channel default in charge of the whole message' (six sentences), 'a repo ... that is not onboarded is not passed over for an onboarded repo behind it' (two), '... that is not onboarded is not replaced by the channel default' (two), 'without a channel default the first slash word is still named as the repo'

Bug: A Slack message of several lines reaches the agent as written, with its line breaks and indentation

A Slack message of several lines reached the agent as one line: every line break and every indentation was replaced by a single space, by the events handler when the message named a repository and by the command processor otherwise. A pasted diff, stack trace, YAML fragment or list was no longer readable as such. The message is now passed on as written, and the task description is that text without the word that named the repository.

Gain: Code blocks, diffs, logs and lists pasted into Slack reach the agent with their lines and indentation, as they do for a task created through the API. It needs no code of its own beyond the change to the repository lookup.

Test: cdk/test/handlers/slack-events.test.ts > 'forwards the text of a mention as written: "<@BOT> fix this in org/repo:\n line two"'; cdk/test/handlers/slack-command-processor.test.ts > 'repo and description of a mention' > 'the description keeps line breaks and indentation ...' (after the repo, around a repo in the middle, before a repo at the end, before a repo that starts a line, on the channel default)

Bug: A mention inside a Slack thread gets the progress reactions itself, not the first message of the thread

When the bot was mentioned in a reply inside a thread, the progress reactions (:eyes:, hourglass, check mark) were put on the first message of the thread instead of on the mention. Somebody else's message collected the bot's reactions, the mention itself showed nothing, and two tasks started in one thread overwrote each other's state on that first message. The mention's own timestamp now travels with the thread's: reactions go on the mention, replies still go into the thread.

Gain: The reaction is where the help text and the setup guide say it is ('Reactions on your message show progress'), messages of people who asked for nothing stay untouched, and several tasks in one thread each show their own state. About 20 lines in three files; tasks created before the change behave as before.

Test: cdk/test/handlers/slack-events.test.ts > 'a mention written as a reply inside a thread' > 'gets the :eyes: reaction itself and is forwarded with both timestamps', 'is marked :x: itself when forwarding fails, with the reply in its thread', and 'a top-level mention is forwarded with its own ts as thread and as message'; cdk/test/handlers/slack-command-processor.test.ts > 'a mention written as a reply inside a thread' > 'stores its own ts next to the thread ts, for the reactions of the task', 'gets the :x: itself when the request fails, with the answer in its thread'; cdk/test/handlers/slack-notify.test.ts > 'reactions go on the mention itself when the task records it, the post into the thread', 'reactions go on the thread root when the task records no message of its own, the post into the thread'

fix(fanout): retry failed notifications and stop false Jira successes

Bug: A notification that fails for a passing reason is retried from the failed record on, not as a whole batch

The two Lambda functions that read the task events stream told Lambda which record had failed by its event ID. Lambda can only resume a DynamoDB stream from a sequence number, so the promised retry from the failed record did not work as written. Both functions now report the sequence number, as AWS documents and as the orchestration reconciler already does.

Gain: A notification that fails for a passing reason (an outage or rate limit of Slack, GitHub, Linear or Jira, a throttled read) is now retried from the failed record on. Before, the reported identifier matched no record of the batch, and Lambda counts such a batch as failed: all of its records, up to 100, were delivered again up to three times, the ones before the failed record included, and a batch that kept failing went to the dead-letter queue as a whole. (The AWS page on batch failures of streams does not list this case; a test of it recorded against AWS, in the LocalStack repository, shows four invocations and then the failure destination.) The retry paths of the fan-out worked before; they now replay only the failed record and what follows it.

Test: cdk/test/handlers/fanout-task-events.test.ts > 'a failed record is reported by its stream sequence number, not by its eventID'; cdk/test/handlers/approval-metrics-publisher.test.ts > 'poison pill: handler exception flags record for partial-batch retry' and 'heartbeat still emits even when every record in the batch is a poison pill'

Bug: A final reply that Linear refused is delivered again instead of staying on 'On it' for good

When a comment-triggered iteration on a plain Linear issue finished and Linear refused the final reply (a 5xx, a rate limit, a timeout), the code gave its claim back and waited for a retry that could never come: this function is fed by the stream of the task events table, and giving the claim back is a write to the task table. The reply stayed on 'On it' or 'Working' and the comment kept its eyes reaction for good. The failed record is now reported, so Lambda delivers it again; after three failed attempts the reaction alone carries the outcome, as it already did.

Gain: A Linear user whose follow-up request ends during a Linear blip gets the outcome on one of three retries instead of a reply frozen in progress on a finished task. No new state: the claim's existing budget of three matches the three retries of the event source, so the fourth delivery settles and nothing reaches the dead-letter queue.

Test: cdk/test/handlers/fanout-task-events.test.ts > standalone iteration threaded reply > 'a terminal reply that fails reports its record, so the event is delivered again' and 'a reply that keeps failing is retried on three redeliveries, then settled by the reaction alone'

Bug: The 'Opened a pull request' comment on Linear no longer depends on the stream being slower than the agent

The comment 'Opened a pull request' on a Linear issue, and the pull request link of the GitHub status comment at that moment, were read from a field of the task that the agent writes only at the very end of the run, after the event that announces the pull request. Whether they appeared depended on whether the stream was slower than the agent. The link is now taken from that event itself when the task does not have it yet.

Gain: The courtesy comment on Linear appears on every first run that opens a pull request instead of only when timing allows; nothing delivers that event a second time, so a comment that was missed stayed missed. The GitHub status comment shows the link from the moment the pull request exists instead of only at the end of the task. The link itself was not lost before: the final comment carries it on both channels.

Test: cdk/test/handlers/fanout-task-events.test.ts > Linear dispatcher > 'pr_created links the PR from the milestone when the task record has no pr_url yet'; GitHub dispatcher > 'pr_created shows the PR link from the milestone when the task record has no pr_url yet'

Bug: A GitHub token refused twice is logged and dropped instead of replaying the batch to the dead-letter queue

When GitHub answers 401 the function reads the token again and retries once. If the fresh token was refused too, which is what an expired or revoked token does, the error was treated as a passing failure: the batch was delivered three more times, each time running the other channels again, then went to the dead-letter queue and raised its alarm. This happened for every pull request and final event of every task that has an issue or pull request to comment on. A second 401 is now logged as a GitHub API error and dropped, like the other GitHub answers that a retry cannot change.

Gain: An expired GitHub token costs two warnings per such event (the refresh and the refusal, both naming the secret to replace) instead of four invocations, repeated work on the other channels and a dead-letter entry, until someone replaces the token. The other side: a dead token no longer raises the dead-letter alarm; in the fan-out it shows only as fanout.github.api_error warnings, and no alarm watches those.

Test: cdk/test/handlers/fanout-task-events.test.ts > GitHub dispatcher > 'a 401 that persists after the token refresh is swallowed, not retried'

Bug: When the agent stops to ask a question, the Jira issue shows the question instead of 'Task completed'

When the agent stops to ask a question instead of guessing, a Jira issue got the comment 'Task completed' with the cost of the run, and the question appeared nowhere. Linear already shows the question in that case. Jira now gets a comment that opens with 'ABCA has a question before it starts', shows the question, and says how to run again (add the details to the issue, then re-apply the trigger label), because Jira has no way to resume a run from a reply.

Gain: A Jira user sees why nothing was delivered and what to answer, instead of a green check mark on an issue where nothing shipped.

Test: cdk/test/handlers/fanout-task-events.test.ts > Jira dispatcher > 'a run that stopped to ask a question posts the question, not a completion'

Bug: A Jira iteration posts its result even when the status comment was deleted or can no longer be edited

At the end of a comment-triggered iteration on Jira the status comment is edited into a short pointer and the result is posted below it. If the status comment could not be edited for a reason no retry fixes, for example because someone deleted it while the task ran, or once the retries were used up, the function stopped there and the result was never posted. It now carries on and posts the result as its own comment.

Gain: A reviewer whose progress comment was deleted or can no longer be edited still gets the result, the cost and the pull request link of the iteration. Before, the issue showed no outcome at all for that run.

Test: cdk/test/handlers/fanout-task-events.test.ts > Jira dispatcher > 'standalone iteration whose status comment cannot be edited still posts its result' and 'standalone iteration whose status comment stays uneditable after its retries still posts its result'

Bug: A Jira iteration that changed code and ends with a failing build is a failure, not 'Task completed'

A comment-triggered iteration on a Jira issue that finishes with a failing build was announced as 'Finished, result posted below' and 'Task completed'. That outcome exists: a build that was already failing before the iteration does not fail the task. Linear, the orchestration reconciler and the re-rendering of the same Jira comment all report it as a failure. The Jira iteration now gets the failure pointer and the 'Shipped a PR but stopped early' frame as well, with the reason 'Build or tests did not pass'. A run that changed no code is left out: it answered a question on a pull request whose build was already red, and keeps the completed comment with its answer (both added after the first reviews).

Gain: A reviewer who asks for a fix on Jira is no longer told the run succeeded while the build is red, and the three places that write this Jira comment agree on one outcome for a run that changed code.

Test: cdk/test/handlers/fanout-task-events.test.ts > Jira dispatcher > 'standalone iteration that completes with a red build is reported as a failure'

fix(linear): keep vault workspaces online, previews on the right issue

Bug: One throttled vault call can no longer take a working Linear workspace offline until it is re-authorized

A Linear workspace that moved onto the Identity vault keeps its old Secrets Manager token as a fallback, and nothing renews that token once the vault serves every request, so Linear rejects it after 30 days at the latest. When one vault call then failed for a passing reason such as a throttle, the token resolver fell back to that dead token, read Linear's rejection of it as the end of the workspace's authorization, sent the operator an alert and marked the workspace revoked with the one reason that is never checked again. From then on the vault was no longer asked and every Linear event of that workspace was refused until somebody re-authorized it, although its vault grant worked. Now a failed vault call fails only that one event and records nothing. When the vault itself says the workspace needs a new consent and the fallback token is rejected too, that is recorded as the vault's verdict, as it already was for a workspace without a fallback token: the alert names the vault, and bgagent platform doctor checks a mark with that reason against the live vault before it reports the workspace as revoked. Behaviour change to know: a vault call that fails every time (the credential provider was deleted, the function lost its permission) cannot be told from one that fails once. For a workspace with a dead fallback token that used to end in an alert and a workspace marked revoked. Now nothing is marked and no alert is sent: each event is dropped, the function's log has 'Vault token resolution failed' and 'Linear token refresh permanently rejected', and platform doctor reports the workspace as not assessable (a warning), or as authorized when the vault answers the operator's own credentials. A workspace onboarded straight onto the vault, which has no fallback token, already behaved that way.

Gain: A working vault workspace can no longer be taken offline for good, with an alert that names the wrong cause, by one throttled or timed-out AgentCore call. Hit: every workspace that moved from Secrets Manager onto the vault, from 30 days after the move at the latest; this is the group that grows when the vault becomes the default (open pull request 1008). Cost: for the same group a vault that is broken for good is no longer announced and the workspace is no longer marked revoked; the function's log and bgagent platform doctor are what is left. About ten lines of code.

Test: cdk/test/handlers/shared/linear-oauth-resolver.test.ts > 'a transient Secrets Manager error is not a revocation' > 'Linear rejects the refresh token of the stored fallback grant' > 'the vault was unavailable -> NO latch, only this event fails' and 'the vault says consent-required -> recorded as the vault's verdict, so the re-probe can clear it'

Speed: A Linear token from the Identity vault is reused for 60 seconds instead of two AgentCore calls per request

For a workspace on the Identity vault every request for a Linear token asked the vault again: two AgentCore calls each time, although one webhook event asks for a token several times in a row (each reaction, reply and edit asks on its own). The Secrets Manager path has always kept its token for a minute. The vault path now does the same: a token the vault returned is reused for 60 seconds in the same Lambda instance. A workspace that is marked as needing consent is still asked every time, because only a fresh answer of the vault may lift that mark.

Gain: Two AgentCore calls fewer for every Linear token request after the first one within a minute, per workspace and warm Lambda instance: three requests in a row cost two calls where they cost six. Fewer vault calls also means fewer chances of the passing vault error of the previous item. No latency was measured. Cost: the vault's answer carries no expiry date, so for up to a minute a token can be used after Linear stopped accepting it; the Secrets Manager path has the same minute after a re-authorization.

Test: cdk/test/handlers/shared/linear-oauth-resolver.test.ts > 'AgentCore Identity vault path (#809)' > 'a token the vault returned is reused for a minute' > 'two calls in a row ask the vault once; after the minute it is asked again'

Bug: A preview screenshot goes to the Linear issue of the task that opened the pull request, in its workspace

When a preview deployment of a pull request finishes, ABCA posts the screenshot on the linked Linear issue. It found that issue by its identifier (for example ENG-7) and took the first workspace that answered. An identifier is unique inside one workspace only, so on a stack with two workspaces that both have an ENG-7 the screenshot and the preview link of one tenant could be posted on the other tenant's issue, while the right issue got nothing. The task that opened the pull request already records its issue and its workspace: that record is now used, provided the task belongs to the repository of the deployment. For a pull request without such a task the search by identifier remains, and it no longer stops at the first workspace that answers: the workspaces whose recorded team keys list the team are all asked, and when two of them have the identifier nothing is posted on Linear and a warning is logged. The workspaces that do not list the team are asked only when none of the first group has the issue, under the same rule. The search can still pick one of two issues in two cases: a workspace that lists the team is preferred over one that does not (a workspace registered before team keys were recorded, or whose team was added later), and a workspace that cannot be asked at that moment counts as not having the issue.

Gain: A pull request opened by a Linear task gets its preview on that task's own issue, also when another workspace on the stack has an issue with the same identifier, and the search is skipped for it: one registry scan and at least one Linear request fewer per deployment. For other pull requests the search no longer posts on the first of two workspaces of the same group that have the identifier. Behaviour change to know: such a pull request used to get a Linear comment on whichever workspace answered first and now gets none; the GitHub comment is not affected. The search itself is 4 lines shorter (38 to 34).

Test: cdk/test/handlers/github-webhook-processor.test.ts > 'a Linear task's preview goes to the issue and workspace on its own record, not to an identifier lookup'; cdk/test/handlers/shared/linear-issue-lookup.test.ts > 'findLinearIssueByIdentifier' > 'returns null when two workspaces have the identifier and both list the team' / '... and neither records its teams'

Bug: The Linear issue search gives up after 5 seconds and the token renewal after 10; neither had a time limit

Two requests to Linear had no time limit: the search for an issue by its identifier, made after a preview screenshot is posted, and the renewal of a workspace's token. If Linear accepted such a request and did not answer, the Lambda waited until it was killed at its own timeout. For the screenshot function that is a failed asynchronous run, which Lambda repeats twice by default, and each repeat takes a new screenshot and posts a new pull request comment. The search also failed outright when Linear answered with a body that is not JSON. The search now gives up after 5 seconds and the renewal after 10, and a body that cannot be read counts as not found.

Gain: A Linear that takes a request and does not answer costs one missing Linear comment, where it could cost two repeated screenshot runs with duplicate pull request comments and a dead-letter alarm, and it no longer holds a function that needs a Linear token until that function's timeout. Giving up on a renewal after 10 seconds loses nothing when Linear had not yet renewed the token. When it had, Linear answers a retry with the same refresh token with the new credentials, but only within 30 minutes of the renewal; a workspace that asks for no token in that time needs re-authorization afterwards. The same could already happen when a function's own timeout (20 to 120 seconds) cut the request off; it now happens from 10 seconds on.

Test: cdk/test/handlers/shared/linear-issue-lookup.test.ts > 'findLinearIssueByIdentifier' > 'a 200 whose body is not JSON is a miss, not a rejection' and 'gives up on a Linear that takes the request and never answers'; cdk/test/handlers/shared/linear-oauth-resolver.test.ts > 'resolveLinearOauthToken' > 'gives up on a refresh that Linear takes and never answers'

When an attachment of a Linear issue could not be downloaded or screened, the reply ABCA posts on the issue carried the text of the underlying error: for a failed screening call the AWS error, which can name the function's role and the account, and for a failed download the DNS or network error. Both replies now have fixed wording, and the cause is written to the function's log. Gain: no role name, account id or network detail of the deployment in a comment that everyone with access to the Linear issue can read.

fix(linear): answer a named sub-issue with its state, not a question

Bug: A Linear issue whose own text fits the 10,000 character limit is not rejected for a paragraph ABCA adds

For a Linear issue with a paperclip attachment, or with a project document that ABCA could not include, ABCA adds a paragraph to the task description that tells the agent this material exists. That paragraph was added without looking at the size limit, unlike the two other sections ABCA adds (project documents and recent comments). An issue whose own title and text fitted the 10,000 character limit could therefore go over it and be rejected with 'task_description exceeds maximum length of 10000 characters', for example an issue of 9,900 characters with one Figma link. The paragraph is now added only when the issue's own text leaves room for it; otherwise it is left out and the task starts.

Gain: An issue whose own text fits is no longer rejected because of a paragraph ABCA adds. Rare (the issue has to be within a few hundred characters of the limit, or carry a very long attachment title), but the rejection it prevents could not be understood from its message: the user's own text was under the limit, and making it a little shorter did not help.

Test: cdk/test/handlers/linear-webhook-processor.test.ts > 'the hint and the size limit of the description' (2 tests: 'a hint that does not fit is left out, and the issue text is sent whole' and 'a hint that fits is kept, up to the last character of the limit')

Bug: The bgagent:help label on an issue outside an onboarded project gets an answer that says what is missing

The label 'bgagent:help' asks ABCA to explain its labels. On an issue whose project is not onboarded, or that is in no project, it got no answer at all: the code that posts the explainer found no project mapping, wrote a log line and stopped, before the check that tells a user that the project is not onboarded. The same label with the other known name, 'abca:help', did get that message. The explainer is now tried only for an onboarded project; on any other the label goes on to the existing check, and the user is told that the project is not onboarded, or that the issue is in no project.

Gain: The first-time user the help label was made for gets an answer that says what is missing, instead of silence. The helper that posts the explainer lost a parameter and a check that its caller now makes.

Test: cdk/test/handlers/linear-webhook-processor-orchestration.test.ts > ':help label' > ':help on a project that is not onboarded gets the onboarding nudge, not silence'

Bug: A comment on an epic that names a sub-issue without a pull request is answered with that sub-issue's state

On an epic that ABCA runs as sub-issues, a comment that names one sub-issue is applied to that sub-issue's pull request. When the named sub-issue had no pull request, the bot answered 'I couldn't tell which sub-issue that's about' and asked the reviewer to name it, which they had just done, so repeating the comment gave the same answer. For a sub-issue that had not started, the 'Did you mean' line was chosen by title words and could propose a different sub-issue; following it would have changed the wrong pull request. The reply now names the sub-issue that was understood and says its state: it has not started yet; it did not run because a sub-issue it depends on failed, with the retry command; it failed before opening a pull request, which is the existing advice and is now also given when it failed before it became a task; or it has no pull request to iterate on, worded so that it is also true for a run that ended without one.

Gain: A reviewer who names the right sub-issue on the epic learns why nothing happens and what to do, for as long as that sub-issue is waiting, running or failed, instead of being asked to repeat the name or being pointed at another sub-issue's pull request.

Test: cdk/test/handlers/linear-webhook-processor-orchestration.test.ts > 'parent-epic @bgagent comment routing' > 'a comment on the epic that names one sub-issue which has no pull request' (6 tests)

@krokoko

krokoko commented Nov 18, 2026

Copy link
Copy Markdown
Contributor Author

Linear, Jira, Slack and GitHub integrations (part 2 of 2): what changes and what it gains

fix(screenshots): let a branch name only a task of its own repository

Bug: A Linear task's preview reaches its issue or reply even when the pull request never names the issue

When the preview deployment of a pull request finishes, ABCA puts the screenshot on the Linear issue of the task that opened it, but it looked for that issue only when the branch name, the title or the body of the pull request contained an identifier such as ENG-42. Not every pull request of a Linear task has one. A task that a Linear comment starts as new work was described by the comment text alone (for example 'add a dark mode toggle'); another change of this pull request puts the description of the earlier task in front, which brings the identifier into the branch name, but the comment text alone is still used when that description cannot be read. Nothing in such a pull request carries the identifier, and its preview was dropped without a log line. The task's own record, which names the issue, the workspace and the reply, is now used first and no identifier is needed.

Gain: The preview of a Linear task no longer depends on the identifier appearing in its pull request. Hit: a follow-up task started from a Linear comment whose pull request does not name the issue; it got no preview on its reply and now gets it. That was every such task before the change to its description in this pull request, and is one whose earlier description could not be read after it. The handler loses one nesting level and three decision points (complexity 59 to 56, measured with eslint).

Test: cdk/test/handlers/github-webhook-processor.test.ts > 'a task started from a Linear comment gets its preview although nothing in the pull request names the issue'

Bug: A word and a number in a branch name no longer hide the Linear identifier in the title or body

For a pull request without a Linear task record, ABCA searches the branch name, then the title, then the body for an identifier such as ENG-42, and it looked up only the first one found. The branch name is read in upper case, so any word followed by a number counts: on the branch feature/upgrade-node-22 the search took NODE-22, found no such issue and stopped, although the title said ENG-42. The search now goes on to the next place when every active workspace answers that it has no such issue. It stops, and nothing is posted, when the lookup could not be completed or found the identifier in two workspaces: an identifier further down is not taken in place of one that could not be checked.

Gain: Pull requests that are not on an ABCA branch, and tasks from the CLI, Slack or the API whose description has a word and a number before the identifier, get their Linear comment when the title or body names the issue; they have had none since the branch name was given priority. Behaviour change to know: a pull request whose branch holds a word and a number that is no issue (fix/issue-123-crash, or a branch that names a deleted issue) used to get no Linear comment; it now gets one on the first identifier of its title, else of its body, as a pull request on any other branch always did. Cost: one extra lookup for each identifier that no workspace has. The lookup now reports 'no such issue' and 'could not be determined' as different results, which removes two suppressions of the silent-failure lint rule (64 to 62 in the tree).

Test: cdk/test/handlers/github-webhook-processor.test.ts > 'a word and a number in the branch name do not hide the identifier in the title' and 'an identifier that could not be looked up is not replaced by one further down'; cdk/test/handlers/shared/linear-issue-lookup.test.ts > 'is absent when every workspace answers that it has no such issue'

Test: The re-deploy path of the screenshot processor has tests that fail when it breaks

When a later push to a pull request is deployed, the screenshot processor finds the iteration reply that belongs to the pushed commit, stores the screenshot on that iteration's task and appends the preview to the reply once. No test ran any of this: about 110 lines with a database write and a comment edit could be deleted or reversed without a failing test. Two tests now cover it: one where the deployed commit belongs to the older of two iterations, one where no iteration recorded the commit and the newest reply is used.

Gain: Six changes that every test survived before now fail a test: the append removed, the index read oldest first, the oldest reply used as the fallback, the commit not compared, the write without its existence condition, and the append-once marker changed. No product line changed for this item.

Test: cdk/test/handlers/github-webhook-processor.test.ts > 're-deploy on a Linear issue that has iteration replies' (two tests)

Bug: A Jira comment that ends its sentence with the mention ('... onto main, @bgagent.') starts the iteration

A reviewer who ended the sentence with the mention, as in 'Please rebase this onto main, @bgagent.', got no reaction on Jira: the full stop after the mention made the parser take it for part of an address such as foo@bgagent.io, and the comment was dropped with only a log line. A full stop now rules the mention out only when a letter or digit follows it, and a full stop that just ends the sentence is removed together with the mention. A pasted code block in such a comment also keeps its indentation now, as it already does on Linear.

Gain: Jira comments that put the mention at the end of a sentence start the pull request iteration instead of vanishing, and a YAML or Python snippet in a Jira comment reaches the agent with its nesting. The parser is one pattern and one replace where it had two copies of the pattern and three replaces (11 lines added, 12 removed, comments included).

Test: cdk/test/handlers/shared/comment-trigger.test.ts > 'a mention that ends a sentence triggers, and its full stop goes with it' and 'keeps a code block of a Jira comment as the reviewer wrote it'

Bug: A browser command that times out reports the time it was given, where it always said 0ms

When the preview page did not answer a browser command in time, the log said 'timed out after 0ms' whatever time the capture had been given: the message read the remaining time at the moment the timer fired, when nothing remains. It now states the time the command had when it was sent.

Gain: The one log line an operator has for a failed capture no longer reads as if the capture had been given no time, so a slow preview is not mistaken for an exhausted budget. Two lines changed, two added.

Test: cdk/test/handlers/shared/agentcore-browser.test.ts > 'a command that gets no answer reports the time it was given, not what is left when the timer fires'

When a preview deployment finishes, the screenshot function reads a task id out of the branch name of the pull request (bgagent//...) and stores the screenshot and the preview link on that task, from where they are shown in the task's Linear reply, its Jira comment or the panel of its epic. Nothing checked, before that write, that the task belonged to the repository of the pull request. Task ids are visible in the branch names of ABCA's own pull requests, so whoever could push a branch to one repository of a deployment could name a task of another repository on it: the foreign picture and link were written onto that task and shown in its tracker, and the task's own next deployment was then taken for a re-deploy and posted no preview comment. A branch name now names a task only when the task belongs to the repository of the deployment and the branch is in that repository itself. The second condition is a safeguard: for a pull request from a fork GitHub's answers do not lead the function to the pull request today (its lookup by commit lists none, and a check run of a fork's commit lists no pull request), and the function no longer relies on that. Names are compared without regard to letter case, because GitHub reports its own spelling and the task has the one its blueprint was registered with. A pull request whose branch names a task without meeting both conditions gets the screenshot comment on itself and nothing more, with a warning in the log; one for which GitHub names no head repository is refused with a log line of its own. The repository is now compared on a later push as well, where the preview is stored on an iteration task of the pull request's Linear issue and appended to that task's reply: when the issue was found through an identifier in the branch name, title or body of the pull request, that task could belong to another repository, and now only an iteration task of the deployment's repository is taken. GitHub also lists the open pull requests of a commit by the repository of their head branch, so the answer for a deployed commit can hold one that somebody opened in a repository of their own from the branch of an ABCA pull request; the function could take it for the deployment's own, post the screenshot under its number and search its title and body for an issue, and it now keeps only pull requests that live in the deployment's repository. And where a deployed commit is the head of more than one open pull request of the repository, the function now takes the one with the lowest number, not the first that GitHub lists: in a public repository anyone can open a second pull request from the branch of an ABCA pull request into another branch of the same repository, and when GitHub listed that one first it got the screenshot comment and its title could be searched for an issue. Gain: the branch name of a pull request can no longer put a picture and a link onto a task of another repository, and so into that task's tracker, nor silence that task's own preview. Cost: one more DynamoDB read per deployment of an ABCA branch. Behaviour change to know: GitHub goes on answering to the old name of a repository that was renamed or moved, so a blueprint that still has the old name can go on working, but its deployments arrive under the new name; its tasks then get the pull request comment only (log: 'The branch names no task of this repository') until the blueprint is registered under the new name.

fix(jira): stop moving cards backward and show the agent's answers

Bug: A Jira issue that is already In Review or In Progress stays there instead of moving back or sideways

When a pull request was opened or updated, ABCA moved the Jira issue along a list of preferred statuses that ends with In Progress. An issue that was already In Review therefore took the rework transition back to In Progress, and an epic that was already In Progress was pushed to another status of the same band, such as In Review or On Hold, each time it was started, extended, retried or re-opened by a change to one of its sub-issues. An issue that already sits on one of the preferred statuses now only moves to one that ranks before it, and the fallback to any other in-progress status is no longer used for it. The platform and the agent apply the same rule, and after a follow-up request on a sub-issue of an epic the platform uses the review status configured for that sub-issue's own project.

Gain: A card that is In Review, Code Review, Review, Peer Review, Reviewing or In Progress is no longer moved backward or sideways. Hit before, on any workflow that lets In Review go back to In Progress and has no status mapping: every @bgagent follow-up on an issue that was In Review left the card In Progress with its pull request open, and every epic that was already In Progress when it was started, extended or retried showed In Review while its sub-issues ran. The other side: a card In Progress on a board without one of the five review names used to move, when the pull request opened, to the first other in-progress status that is not Blocked. That was wrong on a board with On Hold and right on a board that calls its review column Under Review, Ready for Review, Testing or QA; such a board now needs --status-on-pr, and until it is set the card stays In Progress. Not changed: a review status under another name is still taken back to In Progress by a follow-up unless --status-on-pr names it. About 25 lines in three files.

Test: cdk/test/handlers/shared/jira-feedback.test.ts > 'leaves an issue that is already In Review there instead of taking the rework transition', 'leaves an epic that is already In Progress there when it is re-opened', 'leaves an In Progress issue there when the board has no review status'; agent/tests/test_jira_reactions.py > TestPrTransitionSelection::test_already_in_review_is_not_moved_back_to_in_progress, ::test_in_progress_stays_put_when_the_board_has_no_review_status; cdk/test/handlers/orchestration-reconciler.test.ts > 'a Jira iteration advances the sub-issue with the review status of its own project mapping'

Bug: Italic lines of ABCA's Jira comments render as italics instead of showing their underscores

ABCA writes two kinds of line in its Jira comments in italics: the 'minutes elapsed' line of a running follow-up request and the footer of the epic panel. The converter that turns ABCA's own Markdown into Jira's document format knew bold, code and links but not italics, so Jira showed these lines with a literal underscore at each end. A line that is wrapped in underscores as a whole is now sent as italic text.

Gain: The progress line of every long-running @bgagent request on Jira and the footer of every Jira epic panel read as intended instead of showing markup. 3 lines of code.

Test: cdk/test/handlers/shared/jira-feedback.test.ts > 'renders a whole-line italic as emphasis instead of literal underscores', 'keeps a code run inside an italic line free of emphasis (ADF allows code only with a link)', 'leaves underscores that do not wrap the whole line alone'

Lean (merge): Creating and updating a Jira comment share one code path for identity, token refresh and retry

Posting a new Jira comment and editing an existing one were two copies of the same seventy lines: check the deadline, choose the Forge app or the OAuth token, send, and after a rejected token renew it once and send again. The copies differed only in the id of the comment. Both now go through one private function; nothing a caller sees changes.

Gain: 77 lines fewer in one file (124 removed, 47 added). A rule about the retry or the deadline is written once, and the eight retry tests of the create path now cover the update path as well; before, the update copy's guard against retrying with an unchanged token had no test. Two tests added for the one thing the copies differed in, the comment id.

Test: cdk/test/handlers/shared/jira-feedback.test.ts > 'the retry after a forced refresh is still an update of the same comment', 'an update whose forced refresh returns the same token gives up after one PUT'

Bug: A question asked with @bgagent on a Jira issue gets the agent's answer in the result comment

When a reviewer asks a question with @bgagent on a Jira issue and the agent answers without changing code, ABCA edits its status comment to 'Finished - answer posted below'. The comment posted below held only the completion header, the cost and the pull request link: the answer appeared nowhere on the issue. The result comment now carries the answer between the header and the cost line, on plain issues and on sub-issues of an orchestrated epic. The other half of this finding, the question of a run that stops to ask before it starts, was already fixed earlier in this pull request.

Gain: A Jira reviewer who asks the agent a question gets the answer on the issue. Before, every such request on Jira ended in a pointer to an answer that was not there, while Linear showed it. 6 lines of code in three files.

Test: cdk/test/handlers/fanout-task-events.test.ts > 'standalone iteration that answered a question posts the answer in its result', 'the answer comment is never read as a trigger, even when the answer spells out the mention', 'shows the answer of a completed run between the header and the metrics'; cdk/test/handlers/orchestration-reconciler.test.ts > 'a Jira orchestration iteration that answered a question posts the answer in its result'

Bug: Recent Jira comments given to a task are the ten newest human ones, without ABCA's own comments

When a Jira issue is triggered again, ABCA adds the latest human comments to the task. It asked Jira for the ten newest comments and only then removed those written by apps, so after a few runs ABCA's own comments filled the window and most human comments were left out. On a site that has not installed the Forge app, ABCA's comments are posted as the setup user and were passed on as if a person had written them. ABCA now reads the 100 newest comments, drops those written by apps and those that begin with one of the emoji ABCA's own comments begin with, and keeps the ten newest of the rest. A comment a person begins with one of those emoji (a check mark, a cross, a warning sign and eight more) is left out as well, as on Linear. One ABCA comment, the notice that a task is queued, begins with an emoji that is not on the list and is still passed on from such a site.

Gain: On a re-trigger the agent gets the reporter's clarifications instead of ABCA's own status lines. With six human comments followed by seven ABCA comments it now gets all six; before it got three. Sites on the OAuth fallback no longer feed 'ABCA picked up this issue' and 'Task failed' back to the agent as reviewer comments. The guide's promise of up to ten human comments holds. 5 lines of code.

Test: cdk/test/handlers/shared/jira-attachments.test.ts > 'keeps the newest human comments when ABCA has commented more often since', 'drops the comments ABCA posted as the setup user', 'caps the context at the ten newest human comments, oldest first'

Bug: Jira descriptions and comments keep nested list items, code blocks in lists and pasted links

ABCA turns a Jira description or comment into text for the agent. From a list it took only the own text of each item, so sub-bullets, a code block inside an item and pasted links (which Jira stores as a card with an address and no text) were dropped without a trace. What an item holds besides its text is now rendered under it, indented by level, and a pasted link is rendered as its address.

Gain: The agent gets the sub-requirements, code snippets and links the author wrote. Hit before: every sub-issue of an orchestrated epic and every recent comment that uses a nested list, a code block in a list or a pasted link (ABCA reads both from Jira's REST API as documents); in the test's example the two sub-bullets, the link and the code were all missing. The description of the triggering issue itself is affected only where Jira delivers it as a document: a description that arrives as plain text was and is passed on unchanged. 6 lines of code.

Test: cdk/test/handlers/shared/jira-adf.test.ts (new) > 'keeps what a list item holds besides its own text: nested items, a pasted link, a code block', 'an item that holds only a nested list keeps that list', 'a flat list renders as before, with one blank line after it'

Bug: The renewal of a Jira OAuth token gives up after 10 seconds instead of holding the function

The request that renews a Jira site's OAuth token had no time limit. If Atlassian accepted it and did not answer, the calling function waited until it was killed at its own timeout; for the function that sends notifications that is a failed batch of up to 100 events, which is retried three times and then sent to the dead-letter queue. The renewal now gives up after 10 seconds, the same limit as for Linear, and the caller carries on as after any other failed renewal.

Gain: An Atlassian token endpoint that takes a request and does not answer now costs about 10 seconds for each renewal that is tried and the Jira write or read it was for: a skipped final comment (three tries, about 30 seconds, for the result of a follow-up request), or a Jira trigger that is refused with 'try again in a few minutes' on a site that writes as the Forge app and dropped without a comment on a site that writes through OAuth, which needs the same token to post it. Before, it could cost a failed notification batch (Slack, GitHub and Linear messages of other tasks delayed or lost, a dead-letter alarm) or a five-minute hang of the Jira webhook processor; a batch that holds several such Jira events can still reach the function's 60 seconds. Hit: sites that write through the OAuth token, and the attachment and comment reads of every site. Giving up after 10 seconds loses nothing when Atlassian had not yet renewed the token. When it had, the new pair is lost with the request: Atlassian disables a refresh token once it is used and tolerates a repeated exchange of the same token only within its reuse interval, 10 minutes by default, so a site that asks for no token in that time is rejected afterwards and needs 'bgagent jira setup' again. The same could already happen when a function's own timeout (60 or 300 seconds) cut the request off; it now happens from 10 seconds on. One line and a constant.

Test: cdk/test/handlers/shared/jira-oauth-resolver.test.ts > 'gives up on a refresh that Atlassian takes and never answers'

When an attachment of a Jira issue could not be downloaded or screened, the comment ABCA posts on the issue carried the text of the underlying error: for a failed screening call the AWS error, which can name the function's role and the account, and for a failed download the network error. Both comments now have fixed wording, the same as on Linear, and the cause is written to the function's log. Gain: no role name, account id or network detail of the deployment in a comment that everyone with access to the Jira issue can read.

fix(metrics): publish the approval metrics that have no dimensions

Bug: Approval metrics without dimensions declare one empty dimension set, so CloudWatch can create them

The function that writes the approval metrics declared a metric without dimensions with an empty list of dimension sets. CloudWatch creates one metric per dimension set and the JSON schema AWS publishes for the embedded metric format requires at least one, so by the specification nothing was published for five metrics: the count of approval requests, the counts of the per-task cap, the rate limit and stranded approvals, and the publisher's heartbeat. They are now declared with one empty dimension set, which is how the format writes a metric without dimensions.

Gain: The widget 'Approval Timeout Clip Rate' gets its denominator (the request count), the cap, rate-limit and stranded counters exist, and the heartbeat is published. One line of code. Every metric line the publisher can write now passes the schema AWS publishes: nine metrics, the timeout of the next paragraph in two forms; the five metrics without dimensions failed it before. Not observed on a deployed stack: it rests on the embedded metric format specification and its JSON schema.

Test: cdk/test/handlers/shared/approval-metrics.test.ts > 'declares one empty dimension set when the metric has no dimensions'; cdk/test/handlers/approval-metrics-publisher.test.ts > 'happy path: approval_requested emits ApprovalRequestCount + heartbeat' (new assertion on Dimensions)

Bug: The timeout of a timed-out approval is also published without dimensions, as the dashboard reads it

The dashboard widget 'Approval Timeout Breakdown' asks for the timeout of timed-out approvals without any dimension, while the publisher wrote that metric only with the rule dimension. CloudWatch does not add up a custom metric across dimensions, so by its documentation the widget could not show a data point, for any rule. The publisher now writes the value a second time without dimensions, which is the metric the three percentile lines of the widget read. A new test synthesizes the dashboard and fails when a widget reads an approval metric with dimensions the publisher never writes.

Gain: The second of the three approval widgets can show data: p50, p90 and p99 of the timeout over all rules. Cost: one more CloudWatch custom metric, with no dimension and so of fixed size, written only when an approval times out. Six lines of code, and a test that ties the dashboard to the publisher: it found exactly this metric and no other. Not observed on a deployed stack: it rests on the CloudWatch documentation and on the synthesized dashboard.

Test: cdk/test/handlers/approval-metrics-publisher.test.ts > 'every Cedar-HITL metric a widget reads is written with exactly those dimensions'; cdk/test/handlers/shared/approval-metrics.test.ts > 'approval_timed_out with all fields -> latency + breakdown' (title in the file uses an arrow)

Bug: An answer to a clarifying question starts the resumed run even when the description is full

When the agent stops to ask a question on a Linear issue and the reviewer answers, a new task is created from the earlier description plus the question and the answer. Nothing kept that text within the 10,000-character limit of a task description, and the earlier description fills that limit whenever project documents or comments overflowed, or when the task came from a follow-up comment on such an issue. The new task was then refused and the answer started nothing. The earlier description is now cut at the end of the issue text with its documents and comments; the question, the answer, the exchanges of earlier rounds and the request that a follow-up comment appended are kept whole.

Gain: A reviewer who answers the agent's question on an issue with a lot of context gets the resumed run. Before, every such answer was refused in a project whose documents fill the description, with a message about a length the reviewer cannot change. With a full description the text was 10,191 characters for a short question and answer; it is now 10,000 and accepted. Only the text in front of what the reviewer appended is shortened: the answers, the exchanges of earlier rounds and an appended follow-up request are never cut, and when they do not fit on their own the task is refused with that message as before. Text under the limit is unchanged, character for character.

Test: cdk/test/handlers/shared/clarify-resume.test.ts > 'cuts an original that fills the description limit, never the exchange'; 'keeps the answer of an earlier round when a second question is answered'; 'keeps the request of a follow-up comment whole (a description of %d characters)' (10000, 9831); 'keeps a follow-up request and every answer through further rounds'; 'changes nothing in a description that fits, also in front of a follow-up request'; 'leaves exchanges that exceed the limit on their own whole, for createTaskCore to refuse'; 'never keeps half of a character when the cut falls %s' (in the middle of an emoji, between two emoji)

Bug: A reply rounds its duration once, so 119.6 seconds reads 2m instead of 1m 60s

The duration in the reply under an @bgagent comment was split into minutes and seconds first and rounded afterwards. A run of 119.6 seconds was shown as '1m 60s' and one of 59.6 seconds as '60s'. The duration is now rounded once, before it is split: '2m' and '1m'.

Gain: No impossible durations in the reply under an @bgagent comment on a Linear issue. It hit every run whose time ended in the last half second of a minute, about one in 120, because the agent stores the duration with one decimal. This was the last of the four duration formatters in the handlers with the defect. Three lines changed, one line and one comment added.

Test: cdk/test/handlers/shared/iteration-reply.test.ts > 'rounds a duration of %s seconds once, before splitting off the minutes: %s' (59.4, 59.6, 119.6)

fix(linear): let an admin remove a workspace whose Linear grant died

Bug: The console shows a labeled Linear issue as starting for ten minutes at most, not for as long as it is open

The console marked every Linear issue that carries the trigger label but has no task of its own as 'Starting...', with no time limit. An epic whose sub-issues are being worked on, and an issue whose start was refused, stayed in the list of work not started with a spinner for as long as they were open, and as long as one such issue existed the page asked Linear for the list every 5 seconds instead of every 60. An issue now counts as starting only while it was last updated within ten minutes, the time already allowed for the label's webhook to arrive; after that it is reported as being with the agent and leaves the list.

Gain: An orchestrated epic no longer sits under work not started with a permanent spinner, and an open console tab stops making about 720 Linear requests an hour per mapped project for as long as such an issue is open. That is a seventh of the 5,000 requests an hour a workspace has, which the agent's own comments and reactions share. 6 lines of code, no change to the API type.

Test: cdk/test/handlers/console-linear.test.ts > 'stops calling a labeled issue starting once its webhook can no longer be on the way'

Bug: For a project mapped before its workspace was recorded the console prints the onboard-project command

For a Linear project that was connected before ABCA began to record which workspace owns it, the console said that ABCA cannot reach the workspace and asked to re-run 'bgagent linear setup'. That command does not touch the project mapping, so the message stayed, while the same project kept starting tasks from Linear. The console now says what is missing and prints the command that records it, 'bgagent linear onboard-project', filled in with the project's id, repository and trigger label. The label is free text, so it is printed in single quotes with the escape a POSIX shell needs: the pasted command writes the same label whatever characters it holds.

Gain: Operators of installs older than 2026-10-08 get a command that clears the message instead of one that changes nothing. The command carries the label on purpose: onboard-project rewrites the whole mapping, so re-running it without --label would switch a project with its own trigger label back to the default. One helper of 5 lines replaces two copies of the old sentence.

Test: cdk/test/handlers/console-linear.test.ts > 'gives the command that records the workspace for a project mapped before it was recorded' and 'refuses a project mapped before its workspace was recorded, with the command that records it'

Bug: The Linear webhook answers 400 or 401, not 500, to a null body or an organizationId that is not a string

The public address for Linear webhooks answered HTTP 500 and wrote an error line to the log for two malformed requests that carry no valid signature: a body that is the JSON value null, and a body whose organizationId is a number or an object instead of a string. The first failed while the body was read, the second in the database lookup that picks the workspace's signing secret. A null body is now answered with 400 like any body that cannot be parsed, and an organizationId that is not a string is treated as absent, so the request fails the signature check with 401.

Gain: Anyone could make the endpoint answer 500 and log an error that reads like a server fault; these two requests now get the 400 and 401 that other bad requests get. 4 lines. Nothing changes for a signed delivery.

Test: cdk/test/handlers/linear-webhook.test.ts > '400s on a body of null, which parses but is not an envelope'; cdk/test/handlers/linear-webhook-multi-workspace.test.ts > 'an organizationId that is not a string names no workspace: a bad signature is a 401, not a 500'

Bug: remove-workspace also removes a workspace whose Linear grant died, and deletes its secret

When the Linear app of a workspace is uninstalled or its refresh token is rejected, the platform marks the workspace as revoked but deletes nothing. 'bgagent linear remove-workspace' then answered 'not an active registration' (404) and stopped, so the secret with the OAuth client secret, the webhook signing secret and the tokens stayed in Secrets Manager, the row could not be purged, and a workspace marked for a missing vault consent could become active again by itself. The command now also removes a workspace that something other than the command itself revoked. A workspace it has already removed still answers 404.

Gain: The supported command can clean up after the most likely reason to remove a workspace, a dead grant: the secret is deleted instead of staying behind with no record of it, 'bgagent platform doctor' stops asking to re-authorize a workspace nobody wants back, and the removal is final. 8 lines of code in one handler; the rest of the diff is comments and tests.

Test: cdk/test/handlers/linear-remove-workspace.test.ts > 'removes a workspace that is revoked because Linear rejected its refresh token: its secret is still there' (and the rows for a vault consent and for a hand-made revocation), '403s for a caller who is not the admin of a workspace revoked for a dead grant', 'an active workspace wins over a dead row that still carries its slug' (two rows), 'a dead row is still the one removed when the pages after it hold no active row for the slug', 'the registry scan fail-closes on status via the FilterExpression (pins the filter to the handler)'

Bug: POST /linear/link answers 400, not 500, when the code in the body is not a string

An account-link request whose code is a number instead of a string, for example {"code": 12345}, ended in HTTP 500 with an error line in the log, because the handler called a string method on the number. It is now answered with 400 and the same message as a request with no code.

Gain: A malformed request from a signed-in client gets the validation error instead of what looks like a server fault. One line, now identical to the same check in the Jira and Slack link handlers.

Test: cdk/test/handlers/linear-link.test.ts > '400s when the code is not a string'

fix(linear): stop telling the agent an attached file is missing

Bug: A Linear task's context hint names only the paperclips the task does not carry, not the files it attached

When a Linear issue had a file attached with the paperclip, the task description told the agent that this file lives in Linear and is not attached to the task, although the same file had just been downloaded, screened and attached. The hint now names only what the task really does not carry, such as a Figma or GitHub link, and is left out when there is nothing of that kind.

Gain: Tasks that the trigger label starts for a Linear issue that runs as one task were hit when the issue carried an uploaded paperclip file; the tasks of an epic's sub-issues and pull-request iterations get no hint and were not. The agent is no longer told that a file it holds is missing, with the request to say so in the pull request if the file is essential. 10 lines of product code added, 1 removed.

Test: cdk/test/handlers/shared/linear-issue-context-probe.test.ts > 'lists a linked paperclip and leaves out one that was uploaded to Linear' (and 'gives no hint when every paperclip was uploaded to Linear')

Lean (reuse): The unused wrapper around the Linear issue-to-task lookup is gone; its tests call the lookup production uses

A helper that answered both 'this issue has no task' and 'the lookup failed' with the same empty value had no caller left except its own test. It is deleted, and its four tests now call the lookup that production uses, which keeps the two answers apart.

Gain: 15 lines of product code removed, behaviour unchanged. The unit tests of the lookup now exercise the function that runs in production and check its three answers (found, none, error) directly.

Test: cdk/test/handlers/shared/linear-task-by-issue.test.ts > describe 'lookupTaskByLinearIssue' (4 tests; the one for a failed query asserts kind error with the message)

Lean (merge): One function swaps the status marker of a Linear issue or of a comment, in place of two copies

The code that leaves exactly one status reaction on a Linear issue and the code that does the same on a comment were the same thirty lines, apart from which object they ask Linear about. Both now call one function. What is sent to Linear, what is logged and what is returned are unchanged.

Gain: 23 lines of product code removed (64 out, 41 in) and one place for the rule of the marker swap. The swap on a comment, which had 6 tests of its own, is now exercised by the 10 tests of the issue swap as well.

Test: cdk/test/handlers/shared/linear-feedback.test.ts > the suites of swapIssueReaction (10 tests) and swapCommentReaction (6 tests), unchanged

fix(linear): write "Task timed out" in the final comment, not timed_out

Bug: The final Linear comment of a timed-out task reads "Task timed out" instead of "Task timed_out"

When a task started from a Linear issue ran out of time before it opened a pull request, the closing comment on the issue began with "Task timed_out", the internal event name. The same comment on a Jira issue already said "Task timed out". The Linear comment now prints the outcome in words too.

Gain: Bug fixed: on every Linear task that hits the time limit without a pull request, the requester reads "Task timed out" instead of an identifier, and the Linear and Jira comments agree. Timing out is the only outcome whose name has an underscore, so no other comment changes. One line of product code changed, one test added.

Test: cdk/test/handlers/fanout-task-events.test.ts > renderLinearFinalStatusComment > 'task_timed_out reads "Task timed out", not the raw subtype "timed_out"' (the title starts with the cross-mark emoji)

@krokoko

krokoko commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor Author

Epic orchestration (sub-issues): what changes and what it gains

fix(orchestration): stop the sweep editing every finished epic's panel

Scale: The sweep stops editing the panel of a finished epic one hour after its final status was recorded

Every 10 minutes a scheduled sweep goes through all orchestrations (an epic split into sub-issues) to recover the ones that got stuck. Finished epics stay in its table for good, and for every one of them the sweep rendered the status panel again and edited the Linear comment, on every run, for ever. Once the task records of an old epic had expired (after 90 days by default) that render had no pull request links left, so the edit took the links, the combined pull request line, the preview and the failure reasons off the panel. The sweep now leaves a finished epic alone once an hour has passed since its final status was recorded. During that hour it still repeats the update, about six times, so a panel edit that failed at the moment the epic finished is repaired as before. The limit is new: the record is written before the edit, so a panel whose edit keeps failing for the whole hour (Linear unreachable, a workspace whose token cannot be read) is no longer repaired by the sweep and stays as it was.

Gain: A finished epic now costs the sweep one DynamoDB query per run instead of that query plus two to five more DynamoDB calls, a Linear token lookup and one Linear comment edit. With 200 finished epics in a workspace that is 28,800 Linear requests a day that no longer happen (Linear allows an app 5,000 an hour per workspace). Of the sweep's 5-minute time limit a finished epic now takes one query instead of a round trip to Linear, so the stuck epics at the end of the list are reached; the run still grows by that one query with every epic ever run, because the rows are never deleted. Panels of old epics keep their pull request links when the task records expire.

Test: cdk/test/handlers/reconcile-stranded-orchestrations.test.ts > 'an epic whose rollup is already posted' > 'posted hours ago → left alone: the panel is not rendered again', 'posted minutes ago → still refreshed, so a panel edit that failed after the stamp is repaired' and 'an old stamp on an epic that is running again does not stop the recovery'

Bug: The sweep takes back a sub-issue's claim only after 10 minutes, so a live start gets no second agent run

While a task is being created for a sub-issue, the sub-issue is marked as claimed, so that only one task is created for it. The sweep took every claimed sub-issue it found for the leftover of a crashed run and gave the claim back at once, without looking at its age. When the sweep ran during the second or so that a live start takes, the sweep and the live run each created a task for the same sub-issue: two agents working on it, two pull requests, and a second task whose result the orchestration cannot match to any sub-issue. The sweep now takes back only a claim that is more than 10 minutes old, which is twice the longest time a run that starts tasks is allowed to take, and only if the claim is still the one it looked at.

Gain: No second agent run and second pull request for a sub-issue when the 10-minute sweep falls into a live start. Each such duplicate costs a whole task and leaves a task that nothing accounts for; the window is the time one task creation takes, on every start. The price: a start that really crashed is picked up 10 to 20 minutes after the crash instead of within 10.

Test: cdk/test/handlers/reconcile-stranded-orchestrations.test.ts > 'a child found in releasing' > 'claimed moments ago → left to its releaser: not reset, not released a second time', 'claimed longer ago than any releaser can run → reset and released again' and 'an old claim that a new releaser took over after the sweep read it → left alone'

Bug: After a recovery by the sweep the parent issue shows its final status in the same run, not 10 minutes later

In two cases the sweep brought an epic to its end without posting the final status in that run. In one, a sub-issue had failed while the event handler was down: the sweep marked it failed and its dependents skipped, but then decided whether the epic was finished from the rows it had read before it skipped them, so the final status came one run (10 minutes) later. In the other, the sweep started a waiting sub-issue and the start was refused for good (blocked by content policy, repository not onboarded, budget used up): the sweep neither skipped the dependents nor posted the final status, which came one run later, or two runs (20 minutes) when the sub-issue had dependents. The sweep now reads the rows again after its own changes, skips the dependents of a refused start with the step that the event handler and the first start of an epic already use, and posts the final status in the same run.

Gain: After a recovery by the sweep the parent issue shows its final state 10 minutes sooner when a failure had dependents, and 10 minutes sooner when a start was refused for good (20 when the refused sub-issue had dependents, which now read as skipped at once instead of blocked). A small gain on a rare path.

Test: cdk/test/handlers/reconcile-stranded-orchestrations.test.ts > 'an epic that this run brings to its end' > 'a failed child whose dependents the sweep skips → settled with the skips', 'a release that is refused for good → dependents skipped and the parent settled' and 'a refused release beside one that started → dependents skipped, no settle while a child runs'

Bug: A multi-line Linear comment (a list, a code block) reaches the agent as written, not joined into one line

When a reviewer gives the agent an instruction in a Linear comment, the whole comment was joined into one line before it was handed to the agent. A bullet list became one sentence, and a pasted code block lost its fence and its indentation, so a YAML snippet no longer said which line belongs to which step. The instruction is now passed on as the reviewer wrote it: only the mention and the space on either side of it are taken out.

Gain: Multi-line instructions on Linear (lists, code blocks, YAML or Python snippets) reach the agent as written instead of as one run of words. One line of the parser.

Test: cdk/test/handlers/shared/orchestration-comment-trigger.test.ts > 'keeps the lines of a multi-line instruction' and 'keeps a fenced block and its indentation as the reviewer wrote them'

Bug: A Linear comment that ends its sentence with the mention ('..., @bgagent.') starts the work

A Linear comment that ends its sentence with the mention, such as 'Please rebase this onto main, @bgagent.', was ignored without any reaction or reply: the full stop after the mention made the parser take it for part of an address like foo@bgagent.io, and the hint that ABCA sends for a misspelled handle did not apply either. A full stop now rules the mention out only when a letter or digit follows it. A full stop that just ends the sentence is dropped together with the mention, so '@bgagent.' on its own still means the same as '@bgagent'.

Gain: Linear comments that put the mention at the end of a sentence start the work instead of vanishing. One pattern.

Test: cdk/test/handlers/shared/orchestration-comment-trigger.test.ts > 'a mention that ends a sentence triggers, and its full stop goes with it'

fix(orchestration): stop late task events from undoing an epic's repair

Bug: A late write to an old task record no longer marks a repaired or retried sub-issue failed again

A sub-issue of an epic that had failed and was then repaired through a reviewer's comment went back to failed a few minutes later. The preview screenshot of the fix is written onto the record of the sub-issue's first task, that write arrives as one more 'task failed' event, and the reconciler applied it again: the sub-issue's issue went back to Todo with a cross, waiting dependents were skipped and the epic ended as finished with failures. A terminal event is now applied only while the sub-issue's row still names that task and still waits for its result (or already holds it); the database checks this at the moment of the write, so it also holds when the repair and the late event are processed at the same time.

Gain: Bug fixed: an epic repaired through a comment stays repaired, on every repository whose preview deployments ABCA takes screenshots of (before, each later deploy of the branch failed the sub-issue again). The same check protects a sub-issue that was retried: the old task's event could mark it failed again, and when it arrived while the new run was being started, the new run was never attached to the sub-issue and its result was lost. About 30 lines of code, 11 tests.

Test: cdk/test/handlers/orchestration-reconciler.test.ts > 'orchestration-reconciler handler — an event of a task that no longer decides its row' (11 tests; the finding's case: 'after a comment repaired the child, it stays succeeded and its issue is not reverted'; the interleaved order: 'the repair is processed between the read and the write of the late event: it still stands')

Bug: A question answered on a sub-issue no longer re-stacks its dependents or counts as a repair

When a reviewer asks the agent a question on a sub-issue of an epic and the agent answers without committing anything, the reconciler still treated the sub-issue's branch as changed. It started a re-stack task (a full agent session) on every dependent that had already started, re-opened the finished epic, and, if the sub-issue had failed, marked it succeeded and released the dependents that had been skipped, although nothing was fixed. A task that reports that its branch did not move now only refreshes the panel; the same holds for a re-stack that had nothing to merge.

Gain: Agent runs saved: one re-stack session per started dependent, and one more per further hop of the chain, for every question asked on a sub-issue. The parent epic no longer flips from In Review to In Progress and back, and a failed sub-issue is no longer declared fixed by a question. 3 lines of logic, 5 tests.

Test: cdk/test/handlers/orchestration-reconciler.test.ts > 'orchestration-reconciler handler — cascading onto dependents' > 'an iteration that only answered a question re-stacks nothing and does not re-open the epic' and 'a re-stack that had nothing to merge does not re-stack the next dependent'; 'orchestration-reconciler handler — an iteration on a failed sub-issue' (3 tests)

Bug: A final epic status whose panel edit failed is tried again by the next event or sweep run

When the last sub-issue of an epic ends, the reconciler first records that the final status was posted and only then edits the panel comment and sets the parent issue's state and reaction. When that edit failed (Linear unreachable or rate limited, the workspace token unreadable), the record stayed: later events repaired the panel, but the parent issue stayed In Progress with the eyes reaction for good, because every later attempt saw the record and left the parent alone. The reconciler now takes the record back when the edit of the panel did not land, so the next event or the next run of the periodic sweep settles panel and parent together. It does so for one day after the epic ended or was re-opened last; an edit that still fails then (the comment or the issue is gone) is given up, as before. Not covered yet: an edit that lands followed by a failed state or reaction call; that half needs the panel module and is handed over as a tested patch.

Gain: Bug fixed for one form of the failure, the one in which the edit of the panel comment itself fails at the moment an epic finishes (Linear unreachable or rate limited, the token unreadable): the parent issue no longer shows In Progress for ever, and an outage of up to a day is repaired by the first sweep run after it, where the sweep's one-hour window repaired only the panel text and only within the hour. The case the finding describes (the edit lands, the state or reaction call after it fails) is not fixed here. About 50 lines of code, 9 tests.

Test: cdk/test/handlers/orchestration-reconciler.test.ts > 'orchestration-reconciler handler — the once-only claim of the final status' (8 tests; the finding's case: 'a final panel edit that fails gives the claim back, and the next settle posts the final status')

Bug: The epic panel shows a sub-issue it has just started as running, not as blocked

After a sub-issue of an epic finished, the reconciler started the sub-issues that had waited for it and then drew the status panel from the rows it had read before it started them. The panel said 'blocked', with an hourglass, for a sub-issue whose agent was already running, until the next event of the epic corrected it. The sub-issues started in that pass are now shown as running in the same edit.

Gain: The panel on the parent issue shows a sub-issue that the reconciler has just started as running in the same edit, instead of one event later. 5 lines of code, 1 test.

Test: cdk/test/handlers/orchestration-reconciler.test.ts > 'orchestration-reconciler handler' > 'the panel shows a dependent it has just started as running, not as blocked'

fix(orchestration): let a reworded or long sub-issue of an epic start

Bug: A long sub-issue under a long epic starts: the shared epic text is cut to fit the description limit

Every sub-issue of an epic is started with the epic's own title and body in front of its text, so that sub-issues built in parallel share one statement of names and shapes. That block was not counted against the 10,000-character limit of a task description. A sub-issue of about 5,600 characters or more under an epic with a long body went over the limit, was refused as a 'validation error' that told the user to edit the sub-issue, and everything that depended on it was skipped. The sub-issue's own text is now counted first and the shared block gets what is left: the epic's body is cut, with a visible mark, the title alone stays when there is no room for any of the body, and the block is left out when there is no room for it at all.

Gain: Bug fixed: a sub-issue whose own text is valid no longer fails, with its dependents, because of text it did not write. Measured before the change: a 6,000-character sub-issue under a 4,000-character epic body gave a description of 10,370 characters and a refusal. A sub-issue that is too long on its own is still refused, and the message is then about the right text. About 25 lines of code, 7 tests.

Test: cdk/test/handlers/shared/orchestration-release.test.ts > 'releaseChild — the shared context gives way to the description limit' (7 tests; the finding's case: 'a long sub-issue under a long epic keeps all of its own text and stays inside the limit', which asks the real validator isValidTaskDescriptionLength)

Bug: Re-applying the trigger label reads the title and text of sub-issues that have not started again

When a sub-issue of an epic was refused for its text (blocked by the content policy, or too long), the panel told the user to reword it and reply with a retry. That could not work: a sub-issue is started with the title and description that were stored when the epic was first read, nothing ever updated them, and so every retry sent the same text and was refused again. Re-applying the trigger label on the epic now stores the current title and description of every sub-issue that is not running and has not succeeded. On Linear the same event then retries the failed sub-issues; on Jira it does not, and the retry comment is still needed after the label. The two messages name the label. A retry by comment alone still sends the stored text; the messages say so.

Gain: Bug fixed: a sub-issue that was refused for its text can be repaired by its author, which was impossible although the panel said how. The same gesture picks up edits to sub-issues that are still waiting. About 35 lines of code, 16 tests. The retry comment reads the sub-issues again too, with the change to the two webhook processors listed under epics.

Test: cdk/test/handlers/shared/orchestration-store.test.ts > 'extendOrchestration — add nodes to an already-seeded epic' > 'the text of a sub-issue that has not started is read again' (12 tests; the finding's case: 'a reworded sub-issue that failed is stored with its new title and description'; the other order of the two writers: 'a sub-issue that was started while the graph was read is left as it is'); cdk/test/handlers/shared/orchestration-release.test.ts > 'a text refused by %s is to be changed and then retried' and 'a %i refusal has nothing to do with the text and asks for a retry as well' (4 tests)

Bug: A step added to a chain epic no longer brings a second agent run that opens the same pull request

When a sub-issue without a blocking relation is added to an epic that was a chain, it is stacked on the last step, so the epic still ends in one pull request. The check for 'several loose ends that have to be combined' looked at the relations as they are written on the issues, where the new sub-issue looks like a second loose end, and added an integration task. That task ran a full agent session after the new step, merged two branches of which one already contained the other, and opened a second, 'combined' pull request with the same content. The check now uses the dependencies as they are stored, including the one the new sub-issue was just given, so a later re-trigger of that epic does not add the integration task either.

Gain: Bug fixed: no extra agent session and no duplicate pull request when a step is appended to a chain epic (the case the code calls the common one). Two or more steps added side by side are still combined, and the step they both build on is no longer merged a second time. About 12 lines of code, 4 tests.

Test: cdk/test/handlers/shared/orchestration-store.test.ts > 'extendOrchestration — add nodes to an already-seeded epic' > 'the integration node of an extend follows the edges as they are stored' (4 tests; the finding's case: 'one step added to a finished chain adds one row: it IS the combined result')

Risk: Rows that DynamoDB hands back unprocessed are written again, and a seed that cannot store them fails

The rows of an epic are written in batches of 25. When the table is throttled, DynamoDB accepts such a batch, writes part of it and hands the rest back as unprocessed. Nothing sent those rows again, and the epic was reported as seeded. A sub-issue that waited for a missing one waited for ever, and a missing last step was never run. Unprocessed rows are now sent again, at most five attempts per batch with a growing pause between them (1.5 seconds per batch). If rows are still left then, the write fails and the user is told to re-apply the trigger. When a first seed gives up, no epic exists and nothing is started: the row that makes the epic exist is written after all sub-issue rows, in a request of its own (changed after the first reviews: it was part of the last batch). Not closed: sub-issues added later go to an epic that exists. If DynamoDB keeps handing back one of them, the epic is left short of it, the periodic sweep starts what is ready, and the re-applied trigger adds the missing sub-issue as a new one. Before this change one unprocessed row was enough for that; now it takes five answers in a row.

Gain: Risk removed: no epic that is short of sub-issues while it is reported as seeded. The retry is bounded (five attempts per batch of 25) and the two copies of the batch loop are one function. About 25 lines of code added and 15 removed, 6 tests.

Test: cdk/test/handlers/shared/orchestration-store.test.ts > 'rows that DynamoDB hands back unprocessed' (6 tests; the finding's case: 'the seed sends them again, after a pause, and only them'; the bound: 'rows that stay unprocessed fail the seed after five attempts, before any later row is sent'; what the caller sees: 'what the caller of %s is told when rows stay unprocessed', through discoverOrchestration)

Bug: The epic panel lists sub-issues by their number (ENG-9 before ENG-10) and the integration row last

The panel on the parent issue sorted its rows as plain text. An epic with the sub-issues ENG-9, ENG-10 and ENG-11 listed ENG-10 and ENG-11 first. The row of the integration task has no identifier and was placed by its internal id: last for a team called ENG, first for a team called WEB. The rows are now in the order of the numbers in their identifiers, and the integration row is always the last one.

Gain: Bug fixed: the panel reads in issue order for every epic whose sub-issues cross ENG-9/ENG-10 or ENG-99/ENG-100, and the combined row is at the bottom for every team key. 3 lines of code, 2 tests.

Test: cdk/test/handlers/shared/orchestration-rollup.test.ts > 'renderEpicPanel — the single maturing panel' > 'identifiers are sorted by their number: ENG-9 comes before ENG-10' and 'the integration row is the last one, whatever the team key'

Lean (delete): Five functions of the old status block and rollup comment that nothing calls are deleted

Before the single panel existed, the parent issue got a live status block and then a separate final rollup comment. The panel replaced both, but the functions that rendered and posted them stayed, with a helper for quoting comments that the reconciler never used. Only their own tests called them. They are deleted with those tests, and the header of the module now describes the panel.

Gain: Lines removed: 240 of code and comment in the panel module (net) and 311 of tests. One copy of the status icons, the labels and the row order is left instead of three, which is why the fix of the row order is three lines.

Test: No new test. cdk/test/handlers/shared/orchestration-rollup.test.ts passes (37 tests), and so do typecheck, the build's compile, eslint and the dead-code gate for the cdk workspace.

Bug: After a retry that could not start, the panel says why it did not start, not how the earlier run failed

A sub-issue that failed keeps the id of its task when it is retried. When the retry itself was refused (the monthly budget was used up, the repository was not onboarded, the text was blocked), the sub-issue was marked failed again with the reason of the refusal, but the panel went on showing how the earlier task had failed. The user was not told that the retry never started, nor what to do about it. The panel now shows the reason stored on the sub-issue when there is one, and a start that succeeds removes that reason, so that a later failure of the new task is not hidden behind it.

Gain: Bug fixed: after a refused retry the user sees why nothing started (budget, onboarding, content policy) and the next step, instead of the old error. 2 lines of logic in the reconciler and 1 in the release, 5 tests.

Test: cdk/test/handlers/orchestration-reconciler.test.ts > 'orchestration-reconciler handler — the reason shown for a failed sub-issue' (4 tests: the refused retry, the refusal in the pass that renders the panel, the late event of the earlier task interleaved with the refusal, and the other order, a later retry that starts and fails); cdk/test/handlers/shared/orchestration-release.test.ts > 'starting a task removes the reason of an earlier start that was refused'

The claim of the final status, which an earlier change of this pull request gives back when the edit of the panel did not land, is given back for one day only, counted from the moment the epic ended or was re-opened last. An edit that can never land (the panel comment was deleted, its issue is gone, the workspace was removed) was otherwise tried again by every run of the sweep for as long as the rows exist: each run repeated the parent's state and reaction calls, a parent that somebody had moved back to Todo was put In Review again every ten minutes, and the retry comment kept its eyes. After the day the claim is kept and the retry comment is answered. The length of the window, 24 hours, is a choice for the owner.

fix(orchestration): run a sub-issue added to an epic after a failure

Bug: A sub-issue added to an epic after a failure builds on the work that succeeded and runs

A sub-issue that is added to an epic without a blocking relation is stacked on the epic's last step, so that it builds on the work done so far. That last step was chosen without looking at how it ended. After a failure it could be a step that had failed or been skipped; the new sub-issue was then skipped as well, ten to twenty minutes later, without ever running and without a word why. The last step is now chosen among the sub-issues that have not failed or been skipped: the new sub-issue builds on what succeeded, or starts from the default branch when nothing is left to build on. Where a sub-issue stands beside the combined result of an epic, new work now builds on both instead of on the combined result alone. Not covered: a step that still waits behind a failed one counts as a last step until the periodic sweep has skipped it (up to ten minutes); a second sub-issue added in that time is stacked on it and skipped with it.

Gain: Bug fixed: a sub-issue added to an epic that finished with failures is started at once instead of being reported as skipped 10 to 20 minutes later; the usual case is a sub-issue added to supply what the failed one lacked. About 40 lines changed in one small module, comments included; 10 new tests.

Test: cdk/test/handlers/shared/orchestration-epic-tip.test.ts > 'a failed or skipped node is no tip' (5 tests; the finding's case is 'one of two leaves failed, the integration node was skipped → tip is the leaf that succeeded') and 'a leaf beside the integration node → both, so the new node builds on all of the work'; cdk/test/handlers/shared/orchestration-store.test.ts > 'new unconstrained node after a failure → stacks on the work that succeeded and starts' and 'a step added to a chain whose last step failed builds on the step in front of it, and is combined later'

Bug: Replies on an epic name the project's own trigger label and say to re-apply it on the epic

When someone asks for new work in a comment on an epic, the bot answers how to add it. That answer named a label called abca and said to put it on the new sub-issue. The trigger label is chosen per project (bgagent unless the project was onboarded with another one), so on most projects that label started nothing and nothing told the user; where the label did match, labelling the sub-issue started it as a separate task outside the epic. The answers now name the label the project triggers on, as stored on the epic, and say to re-apply it on the epic, which is the step that adds a sub-issue to it. The reply for a sub-issue that failed, which named the same fixed label, is corrected as well.

Gain: Bug fixed: on every project whose trigger label is not literally abca (the default is bgagent) users are no longer sent to a label that does nothing, and on the others 'add this to the epic' no longer starts an unrelated task. Three replies; about 12 lines of code, 5 new tests.

Test: cdk/test/handlers/shared/orchestration-parent-comment.test.ts > 'the %s reply names the trigger label of the project, to re-apply on the epic' (which-sub-issue, new-work) and 'names the platform default label for an epic that has none stored'; cdk/test/handlers/linear-webhook-processor-orchestration.test.ts > 'new work asked for on the epic → the reply names the label this project triggers on' and 'a sub-issue that failed: the label to re-apply is the one this project triggers on'

When the agent stops to ask a question on a Linear issue, the reviewer's answer starts a new task whose description ends with the question and the answer. If that task ends without a pull request and the reviewer then writes a follow-up such as '@bgagent retry', the next task is given the earlier description and the follow-up. An earlier description that fills the 10,000-character limit was cut from its end to make room, and the end is where the question and the answer are: the new task kept the follow-up and lost the answer, with the text breaking off inside the question. The earlier description is now cut at the end of the issue text, in front of what comments appended, so the exchange and an earlier follow-up stay whole. When those alone leave no room, the task is refused with the message about the length, as an answer that does not fit already is. Gain: Bug fixed: a retry after a clarifying question keeps the reviewer's answer; with a full description the agent used to work without it. 4 lines of code, 3 tests.

A sub-issue of an epic is started from the title and description that were stored when the epic was first read. Another change here made a re-applied trigger label read them again; a retry by comment ('@bgagent retry' on a Linear epic or one of its sub-issues, the same comment on a Jira parent) still sent the stored text, so a sub-issue that was refused for its text and then reworded was refused again. The retry comment now reads the sub-issues again first, on Linear and on Jira, and stores the current title and description of every sub-issue that is not running and has not succeeded. The message on a refused sub-issue therefore says again: reword it, then reply with a retry. That one step works on both trackers; on Jira the step the message named before, re-applying the label, stored the new text and started nothing. When the tracker cannot be read at that moment the retry is not held up and sends the stored text, as it did before. Gain: Bug fixed: a refused sub-issue is repaired with the one step the panel names, on Linear and on Jira. One more read of the tracker per retry comment. About 20 lines of code, 5 new tests.

Also here, with no change in behaviour: the sub-issue release took an option named retry that nothing read (a new task is created for a sub-issue that ran before whenever its row carries a task id); the option, its argument at the two retry call sites and two log event names without an emitter are removed. The store now loads the time stamp of an epic's own row, which the reconciler uses to tell when an epic was last re-opened.

@krokoko

krokoko commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor Author

bgagent CLI (part 1 of 2): what changes and what it gains

fix(cli): make the Linear commands work on a multi-workspace stack

Bug: A workspace added with bgagent linear add-workspace has its events accepted instead of answered with 401

Events of a workspace added with bgagent linear add-workspace were rejected for as long as the stack had another active workspace. The command asked for the workspace's webhook signing secret but did not record that the workspace owns it, and on a stack with more than one workspace the webhook receiver answers every delivery of a workspace without that record with 401, while the command printed 'Workspace added'. It now asks for the secret before it stores anything, stores it with the token in one write, and records the ownership.

Gain: For as long as the stack had another active workspace, a workspace added with add-workspace had its Linear deliveries answered 401 (once the receiver's cached workspace count, five minutes, had refreshed) and started no task, until update-webhook-secret, backfill-secret-provenance or a re-run of setup recorded the ownership; add-workspace needs an existing workspace to start, so every workspace it added began in that state. A mistyped secret can no longer leave an active registry row whose credential bundle has no signing secret. One Secrets Manager write instead of two. The command is run by tests for the first time.

Test: cli/test/commands/linear-multi-workspace.test.ts > 'stores the signing secret with the token and records that the workspace owns it', 'stores nothing when what was pasted is not a signing secret', 'stores nothing when what was pasted is empty', 'dates the token from the exchange, however long the operator takes to paste the secret'

Bug: bgagent linear add-workspace refuses any workspace already registered; five messages point to setup instead

bgagent linear add-workspace is meant to refuse a workspace that is already registered, but its check read one arbitrary row of the registry before filtering, so it only worked when that row happened to be the workspace's own; otherwise the command replaced the workspace's registry entry and credentials, dropping its Identity vault binding, and reported success. The check now reads the registry without a row limit (one Scan request, which covers a registry of up to 1 MB: about 1,700 workspaces). Five messages that sent operators to add-workspace for a workspace it refuses now name setup: the next step printed by add-workspace, its team-keys warning, the remedy platform doctor prints for a revoked workspace, and the errors of invite-user and update-webhook-secret for a workspace that is not installed or was removed.

Gain: On a stack with two or more workspaces, repeating add-workspace, which the CLI itself recommended, could silently move a vault-managed workspace back to stored tokens and make the webhook receiver reject its events. Operators are no longer sent through a browser consent that ends in a refusal. One unreachable branch removed.

Test: cli/test/commands/linear-multi-workspace.test.ts > 'refuses a workspace that is already registered, when its row is the second of the registry', 'names 'setup' as the command to run again, never itself', 'still refuses a workspace that was removed, and sends it to 'setup'', 'sends a workspace that has no credential bundle to 'setup''; cli/test/linear-auth-health.test.ts > 'a revoked workspace is sent to 'setup', the command that takes a registered workspace'

Bug: bgagent linear invite-user works for every workspace of a multi-workspace stack, not just one of them

Two more registry lookups read one arbitrary row before filtering: bgagent linear invite-user <slug> reported a registered workspace as not registered unless its row was the one read, so on a two-workspace stack every invitation for one of the two workspaces failed, and add-workspace reported that no workspace was installed when the row read belonged to a removed workspace. Both now use the existing helper that reads all active rows.

Gain: invite-user works for every workspace of a multi-workspace stack instead of only the one DynamoDB returns first, and add-workspace finds an installed workspace when a removed one exists. Two hand-written scans replaced by one existing helper: 14 lines of product code fewer.

Test: cli/test/commands/linear-multi-workspace.test.ts > 'invites to a workspace that is not the first row of the registry', 'still refuses a workspace that was removed, and sends it to 'setup''; cli/test/commands/linear.test.ts > 'finds the active workspace when a removed one is read first'

Risk: On the Secrets Manager path, bgagent linear setup refuses a slug registered to another workspace

bgagent linear setup <slug> only printed a warning when the workspace authorized in the browser was not the one the slug names, and then wrote anyway: with the slug of another onboarded workspace it stored the wrong workspace's token in that workspace's credential bundle and pointed the authorized workspace's registry entry at it, behind 'Setup complete'. When the token goes to Secrets Manager it now stops before the first write, as add-workspace already did, in two cases: the slug is registered to another workspace, or the slug is not registered and the authorized workspace could have been set up under its own URL key. It goes on, with the warning, for a workspace that was only renamed in Linear and is set up again under the slug it is registered with, and for a workspace whose URL key the CLI does not accept as a slug (it wants 4 to 50 characters, Linear has shorter ones) under a slug that is free, the only way such a workspace can be set up. On a stack with the Identity vault a wrong authorization is still only warned about.

Gain: On the Secrets Manager path, clicking Authorize while Linear shows another workspace can no longer mix two tenants' tokens and signing secrets (still only warned about: a workspace whose URL key cannot be a slug, authorized under a slug that is free). Workspaces that are already registered, renamed ones included, can still be re-authorized under the slug the registry and platform doctor know, and a workspace whose URL key cannot be a slug can still be set up.

Test: cli/test/commands/linear-setup-webhook.test.ts > 'a workspace other than the one the slug names (slug registered to another workspace)', '... (slug not registered)', 'but not a workspace renamed in Linear, under the slug it is registered with', 'and not a workspace whose URL key cannot be a slug, under a slug that is free', 'but a slug that is registered to another workspace, whatever the URL key of the one authorized', 'and not on the Identity vault, where a refusal would repeat on every later run'

Bug: bgagent linear list-projects and onboard-project report a token Linear refuses, not an empty result

Linear answers a token it refuses with HTTP 200 and a list of errors instead of data. bgagent linear list-projects read that answer as an empty project list and told the operator to create a project, and onboard-project reported that no workspace owns the project, gave no reason, and suggested recording an owner unverified. Both now report the error for the workspace concerned, and list-projects no longer says that a workspace has no projects when it could not be queried (it also said so after an HTTP error).

Gain: An operator whose token is refused is told so, instead of being sent to create a project or to record an unverified owner. The list-projects handler went from cyclomatic complexity 41 to 38, under the ceiling of 40, so its complexity exemption is deleted: one grandfathered function fewer. list-projects had one test and now has six.

Test: cli/test/commands/linear-project-workspace.test.ts > 'reports an 'errors' answer as the error of that workspace', 'keeps searching the rest after an 'errors' answer'; cli/test/commands/linear-helpers.test.ts > 'reports an 'errors' answer as the workspace failing, not as a workspace without projects', 'reports an HTTP error as the workspace failing, not as a workspace without projects'

Risk: bgagent linear setup reads the stack-wide signing secret once and stops when that read fails

bgagent linear setup decides whether a workspace's stored webhook signing secret is its own by comparing it with the stack-wide secret. It read the stack-wide secret twice and ignored a failure of the second read, so the comparison ran against nothing, a secret copied from the stack-wide one passed for the workspace's own, and the registry recorded it as owned. The stack-wide secret is now read once, by one function that returns its value, and a failed read stops the command.

Gain: A throttled or failed Secrets Manager call can no longer turn an inherited secret into a recorded proof of ownership, the record that lets the webhook receiver accept deliveries signed with that secret. One GetSecretValue call fewer per setup run on a stack whose stack-wide secret holds a real signing secret (the only stacks on which it was read twice), and 8 lines of product code fewer.

Test: cli/test/commands/linear-setup-webhook.test.ts > 'a stored secret that is the stack-wide one, when the operator supplies none'; cli/test/commands/linear.test.ts > describe 'readStackWideWebhookSecret'

Risk: bgagent linear setup stops, before it writes anything, when it cannot read the workspace registry

bgagent linear setup looks the workspace up in the registry to learn whether it is on the Identity vault, and refuses to move such a workspace back to stored tokens. A lookup that failed was treated as 'not registered', so with a throttled or denied read the refusal did not run and the command rewrote the registry entry without the vault binding. A failed lookup now stops the command, before anything is written and before --code uses up a saved consent.

Gain: The guard against silently moving a workspace off the Identity vault holds when the registry cannot be read, and a failed read costs the operator nothing but a second try.

Test: cli/test/commands/linear-setup-webhook.test.ts > 'a registry that cannot be read', 'a registry that cannot be read, before '--code' uses up the saved consent'

fix(cli): report a corrupt config as not configured, add missing tests

Test: A test fails when the preview call of bgagent linear link or jira link loses its dry-run flag

In text mode, bgagent linear link and bgagent jira link first ask the server whose invite code it is and store the link only after the user confirms (with --output json there is no prompt and the link is stored at once). One line in each of the two client methods marks that first request as a preview, and no test ran either. A test now checks what both calls send, for both commands: the preview carries the dry-run flag under the name the server reads, and the confirming call does not.

Gain: If such a line broke, the link would be stored and the invite code used up before the user answers the prompt, so answering no would undo nothing: a caller who declines because the code names someone else's Linear or Jira identity would already be linked to it, with that person's tasks and spend attributed to the caller, and one who confirms would get 'Invalid or expired link code'. Four breakages of the line were tried (deleted in either method, the field name misspelled, the flag sent on every call) and each now fails the test. 17 test lines, no product change.

Test: cli/test/api-client.test.ts > ApiClient > linearLink / jiraLink > '%s sends dry_run for the preview only, not for the confirming call' (one case each for linearLink and jiraLink)

Test: A test fails when --verbose prints a freshly created API key instead of masking it

With --verbose the CLI prints request and response bodies with secret fields masked. Only the masking helper had tests: nothing checked that the API client applies it to a response, nor that the field holding a freshly created API key is on the list. A test now creates an API key with verbose output on and checks that the key is not in what gets printed.

Gain: Verbose output ends up in terminal scrollback and CI logs, and the key is shown only once. Removing the masking at the call site, or the field from the list, used to pass every test; both now fail. 33 test lines, no product change.

Test: cli/test/api-client.test.ts > ApiClient > --verbose output > 'masks the one-time API key in the logged response body'

Lean (delete): The client call behind bgagent status loses an option that no command passed, and the test of it

The client call behind bgagent status accepted an optional number of events to fetch. No command ever passed it; the only caller that did was a test written for the option. The number is now a named constant and that test is gone.

Gain: 21 lines removed, 6 added: one unused option, its documentation line and its test. The four other unused client options the audit named stay for now: the page tokens of the webhook list and of the API-key list are what the paging fix for webhook list and api-key list will pass, the page token of the task list had no caller (a later commit of this pull request makes bgagent list follow it), and the page size of the event catch-up needs a line in a file of another change set (tested patch handed over).

Test: cli/test/api-client.test.ts > ApiClient > getStatusSnapshot > 'runs getTask and getTaskEvents(desc=1) in parallel and returns both' (existing test, still asserts limit=20)

Test: A test fails when saving credentials does not make an existing credentials file owner-only

Saving credentials makes the file owner-only even when it already existed with looser permissions (restored from a backup, copied from another machine). That half had no test: every test wrote the file fresh, where the creation mode alone is enough. A test now starts from a world-readable credentials file and checks that it ends up owner-only.

Gain: The file holds the long-lived refresh token. Deleting the permission fix used to pass every test; it now fails one. 16 test lines, no product change. The same check for the invite file of bgagent admin is added by a later commit of this pull request.

Test: cli/test/config.test.ts > config > saveCredentials / loadCredentials > 'tightens a credentials file that already exists with loose permissions'

Bug: A config file that cannot be parsed is reported with its path and the reason, not as a bare JSON error

With an empty or cut-short config file, every command that needs the configuration (for example bgagent list) failed with a bare JSON parser message such as 'Unexpected end of JSON input': no file name, no next step. The strict config reader now reports such a file with its path, the reason and what to do: 'Cannot read the config file : . Fix or remove the file, or run bgagent configure to replace it.' So it does for a file that cannot be read at all (permission denied). A missing file is still 'Not configured. Run bgagent configure first.' (Changed again after the first reviews: this commit reported such a file like a missing one, and following that advice replaces a file that may only need a repair.)

Gain: An actionable message instead of a parser error at the 24 call sites of the strict reader; bgagent configure already treated such a file as absent, so the advice works. The strict reader differs from main by one try/catch around the read and the parse; the tolerant reader is as on main.

Test: cli/test/config.test.ts > config > saveConfig / loadConfig > 'reports a config file that %s, with its path and the reason' (rows 'is cut short' and 'cannot be read')

Test: A test fails when the retried statuses are not 500 to 599, or --wait keeps its count after a good poll

bgagent watch and --wait retry on server errors and network failures and give up after more than five in a row. Two edges had no test: status 500 itself (the tests used 503 only) and, in --wait, the reset of the failure count after a successful poll. Tests now pin the range 500 to 599 at both ends, and a wait that sees six failures, never more than three in a row, must still finish.

Gain: 500 is what the platform answers for any unhandled failure, and without the reset a long --wait would abort at the sixth hiccup overall. Three one-character or one-line breakages that passed every test now fail. 33 test lines, no product change.

Test: cli/test/retry.test.ts > isTransientError > 'ApiError %i is transient: %s' (499, 500, 599, 600); cli/test/wait.test.ts > waitForTask > 'a successful poll resets the transient-failure budget'

fix(cli): make --verbose work on subcommands of command groups

Test: A test fails when the cached login expiry is not one hour ahead for a lifetime of 3600 seconds

The CLI caches the time at which the login token expires, computed from the lifetime that Cognito reports in seconds. The tests only checked that some expiry was saved, so a slip in the conversion from seconds to milliseconds passed all of them. The login test and the refresh test now check that a lifetime of 3600 seconds gives an expiry one hour ahead, and the refresh test also checks that the cached refresh token is kept.

Gain: A wrong unit there means either a Cognito call before every request (the token looks expired after 3.6 seconds, and bgagent watch polls every 0.5 to 5 seconds) or a forced bgagent login one hour after each login (the token is never refreshed). Five such slips were tried on a scratch copy and each now fails a test. 16 test lines added, one weak assertion replaced, no product change.

Test: cli/test/auth.test.ts > auth > login > 'saves credentials on successful login'; cli/test/auth.test.ts > auth > getAuthToken > 'refreshes expired token'

Lean (merge): Login and token refresh save Cognito's answer through one function; the auth module is 10 lines shorter

Login and token refresh each had their own copy of the code that checks Cognito's answer, computes the expiry and writes the credentials file. Refresh now hands its answer, together with the cached refresh token, to the function that login already uses. One visible difference: a malformed refresh answer is reported as 'Unexpected authentication response from Cognito.', the login wording, where it said 'Unexpected refresh response from Cognito.'

Gain: 10 lines fewer in the auth module (12 removed, 2 added). The expiry arithmetic and the shape of the credentials file exist once, so the expiry checks of the item above guard login and refresh through the same line. A new 12-line test pins the changed wording.

Test: cli/test/auth.test.ts > auth > getAuthToken > 'rejects a refresh answer without an ID token, as login does'

Bug: --verbose takes effect on the subcommands of command groups, for example bgagent --verbose webhook list

--verbose did nothing on a subcommand of a command group: bgagent --verbose webhook list or bgagent api-key list --verbose printed no debug line, although the user guide says the flag works on any command. The start-up hook looked for the flag one level above the command that runs, and that is the root program only for top-level commands such as bgagent list. The hook now reads the flag from the root program itself, whatever the depth.

Gain: The flag now takes effect on all 53 subcommands of the 15 command groups, where it was silently ignored. The 18 of them that call the REST API (webhook create, list and revoke; api-key; registry; policies; trace download; budget status --me; the link commands of slack, linear and jira; linear remove-workspace) now print the HTTP request and response, for example when diagnosing a failing webhook create or linear link. The jira, linear and slack commands and github webhook-info and set-webhook-secret also print one line when the check of the deployed features cannot read the stack. The other subcommands (admin, repo, ops, platform, runtime, budget set, github set-token, webhook test) call AWS directly and have no debug output, with or without the flag. One-time values stay masked in that output (the key of api-key create, the secret of webhook create) and the caller's API key and tokens are never printed; --verbose trace download does print the presigned trace URL (valid 15 minutes), as --verbose submit already prints presigned upload URLs. Confirmed with the compiled CLI before and after the change. The entry point had no test at all; it now has a test file with six cases.

Test: cli/test/bin/bgagent.test.ts > bgagent entry point > --verbose > 'turns debug output on for %s' (a top-level command; a subcommand of a group; a subcommand of a group, flag last) and 'leaves debug output off without the flag'

Test: A test fails when bgagent status --wait exits with another code than 2 after it gives up waiting

The code that turns a failed command into the process exit code sat in a block that runs only when the CLI is started as a program, so no test could reach it. That code is all that stands behind the documented exit code 2 of bgagent status --wait when the CLI gives up waiting (1 means the task itself failed). Parsing and error handling moved, unchanged, into a function that tests can call, and two tests now check the exit codes 2 and 1.

Gain: Scripts that wrap --wait rely on telling 'the task failed' (1) from 'the CLI stopped waiting, the task may still run' (2). Replacing that line by a fixed exit code 1 used to pass every test and now fails one. Messages and exit codes of the compiled CLI are identical before and after. Because a test now loads the entry point, the measured statement coverage of the CLI rises from 88.5% to 89.5% (branches 85.6% to 85.7%, functions 92.2% to 92.6%).

Test: cli/test/bin/bgagent.test.ts > bgagent entry point > exit code > 'is the code a CliError carries: 2 when --wait gives up' and 'is 1 for an error that carries no code'

Lean (reuse): The CLI's list of final task statuses is typed, so a misspelt status in it is a compile error

The CLI declared its list of final task statuses as a fixed tuple of four literals. A task's status cannot be checked against such a list without a type cast, and that cast was written out in five places. The list is now declared with the status type, word for word like the same list in the web console. The casts, two duplicate one-line helpers and two re-typed copies of the exit-code rule are in files of other change sets; removing them is a tested patch handed over with this change.

Gain: One line changed here, with no effect at run time; a misspelt status in the list is now a compile error. It is what allows the follow-up patch to delete 13 lines net in three files: 2 helpers, 6 casts, a 6-line comment that explained one of the casts, and 2 copies of 'COMPLETED exits 0, anything else 1'.

Test: No new test: nothing changes at run time. 'yarn --cwd cli typecheck' and scripts/check-types-sync.ts check the declaration; cli/test/wait.test.ts, format.test.ts, format-status-snapshot.test.ts and commands/watch.test.ts run every use.

Lean (delete): The CLI's unused library entry point is removed (24 lines), so the dead-code check sees its API types

The CLI package carried a library entry point: a file that re-exports the API client, the error classes and every API type, and two manifest keys that point at it. Nothing imports it. The package is private, no other package depends on it, and it is used only through the bgagent program. Its one effect was on the dead-code check, which treats whatever an entry point exports as used, so an unused export of the CLI's API types file could never be reported. The file and the two keys are removed.

Gain: 24 lines removed (a 22-line file and 2 manifest keys). The zero-tolerance dead-code check now sees the CLI's API types: an export that nothing reads is reported, where it passed before (shown with a probe export on a scratch copy). On today's tree it still reports nothing.

Test: No test: the dead-code check is the check. 'node_modules/.bin/knip --no-progress' over all workspaces exits 0 with the deletion in place; knip-14.txt shows the probe export passing before and being reported after.

fix(cli): correct two Linear command reports and delete dead paths

Bug: bgagent linear setup offers to keep the signing secret only when one is stored, not on a first install

Two texts of bgagent linear setup offered to skip the webhook signing secret and set it later with update-webhook-secret: the help of --webhook-secret, and the error for a value that is not a signing secret. Neither works on a first install: the command refuses an empty value when the workspace has no secret of its own, and update-webhook-secret refuses a workspace that is not installed, so an operator who mistyped the secret was sent from one refusal to the next. The help now says that an empty value keeps the secret already stored, and the error offers Enter only when there is a stored secret to keep.

Gain: A first-time operator who pastes a wrong value is told to copy the secret from the app, instead of being led through three refusals (the wrong value, the empty value the message suggested, then update-webhook-secret). Only the two texts change: what the command accepts and refuses is the same. Both texts are now checked by tests.

Test: cli/test/commands/linear-setup-webhook.test.ts > 'a value that is not a signing secret, without telling a first install to skip it', 'a value that is not a signing secret, saying that Enter keeps a secret already stored', 'and the help of --webhook-secret says what an empty value does: keep, not skip'

Bug: bgagent linear backfill-secret-provenance reports a skipped workspace as skipped only and does not count it

bgagent linear backfill-secret-provenance records, for each workspace whose stored webhook signing secret is provably its own, that it owns it. When a workspace's registry entry disappeared while the command ran (for example through remove-workspace --purge), the command printed that it skipped the workspace, then that it recorded it, and counted it in the total. It now prints the skip only and leaves the workspace out of the count.

Gain: The report matches what was written: the summary 'Recorded N workspace(s)' was one too high for every workspace removed during the run, and that workspace got two contradicting lines. Operators act on this output (it names the workspaces that still need update-webhook-secret). The command had no test and now has two.

Test: cli/test/commands/linear-helpers.test.ts > 'reports a workspace whose row disappeared during the run as skipped, and does not count it', 'stops on any other failure of the write'

Lean (delete): Three unreachable signing-secret paths of bgagent linear setup are deleted: 187 product lines fewer

bgagent linear setup still carried three ways of choosing the webhook signing secret that no input can reach, since the secret is asked for before the browser consent and the command stops there when it has none: a warning about an inherited secret, copying the stack-wide secret into the workspace, and asking a second time and writing the stack-wide secret. They are deleted, with the function that chose between them. What remains is what the command does: store the secret the operator entered, or keep the one the workspace already stores. A secret the operator enters now goes into the credential bundle in the same write as the token; it used to be added by a second write, after the registry entry had already recorded that the workspace owns its secret.

Gain: 187 lines of product code fewer (213 removed, 26 added or reworded) and 75 lines of tests of the deleted function. The setup handler's cyclomatic complexity goes from 114 to 104. One Secrets Manager write instead of two when a new secret is entered, and a failed second write can no longer leave a registry entry that says the workspace owns a secret its bundle does not hold. The deleted branches told the operator to create a second webhook, which the app template warns against, and were the only place where setup wrote the stack-wide secret. With the rest of this commit, the branch coverage of the CLI goes from 85.77% to 86.09% (floor 85%) and its line coverage from 89.53% to 90.38%.

Test: cli/test/commands/linear-setup-webhook.test.ts > 'records ownership when the operator supplies this workspace's own secret (with nothing stored)', 'records ownership when the operator supplies this workspace's own secret (in place of the one stored)', 'the final per-workspace PutSecretValue keeps THIS workspace secret, not the stack-wide other'

Lean (delete): autoLinkTokenOwner, without a caller since the move to OAuth, is deleted with its three tests (191 lines)

autoLinkTokenOwner, a function of the Linear commands that linked the owner of a personal API key to the platform user, has had no caller since the Linear integration moved to OAuth: only its three tests kept it alive. It is deleted with them.

Gain: 191 lines removed: 75 of product code and 116 of tests. Nothing else in the repository names the function or reads the auto_setup link method it wrote.

Test: none needed: the suites pass and 'git grep autoLinkTokenOwner' finds nothing

Lean (reuse): bgagent linear list-projects calls the two shared lookups instead of its own copies: 49 lines fewer

bgagent linear list-projects carried its own copies of two lookups that exist as shared functions: listing the onboarded workspaces, and getting a workspace's Linear token from the Identity vault first and from its stored bundle otherwise. It now calls the shared functions. The rule behind the second one, which keeps the commands working for workspaces on the vault (their bundle holds no token), was run by no test in any of its copies; it now has tests for the shared function and through list-projects and invite-user. invite-user keeps its own copy: it uses the active registry entry it already holds, where the shared function looks the workspace up again and takes an entry of any status.

Gain: 49 lines of product code fewer; the list-projects handler's cyclomatic complexity goes from 38 to 21. The vault-first rule can no longer be broken unnoticed: 7 new tests, and each of 13 deliberate breakages of it now fails one of them, where before no test ran the rule at all. For an operator, only the wording of two skip messages of list-projects changes.

Test: cli/test/commands/linear-project-workspace.test.ts > 'mints from the vault, under the subject the registry row records', 'derives the subject from the workspace id for a row that records none', 'falls back to the token in the bundle when the vault has no live grant', 'does not ask the vault for a workspace whose row names no provider'; cli/test/commands/linear-helpers.test.ts > 'linear list-projects --slug' > 'asks the Identity vault first for a workspace that is on it', 'skips a workspace that has no usable token, and says why'; 'linear invite-user' > 'asks the Identity vault first for a workspace that is on it'

Lean (delete): bgagent linear app-template loses --aws-callback-url, which printed a redirect URI the CLI never sends

bgagent linear app-template had an option, --aws-callback-url, left over from an earlier design: it made the template print any URL as the Redirect URI to register on the Linear app. No command sends such a URL to Linear (they send the local callback, the hosted consent page or the Identity vault's callback), so an app registered with it failed the browser consent with Linear's 'Invalid redirect_uri' error. The option is removed, and the local callback URL in the template, in one error message and in the vault helper now comes from the constant that the local listener uses.

Gain: The template can no longer print a redirect URI that the CLI never sends. 8 lines of product code fewer, and the local callback URL is no longer spelled out in three places beside its definition. The option was in no document and in no test; passing it now gives the 'unknown option' error of the command parser.

Test: cli/test/commands/linear-helpers.test.ts > 'app-template offers no --aws-callback-url: the CLI sends no redirect URI of the operator's choosing'

Lean (merge): The Linear commands read stack outputs through the shared findStackOutput instead of a private copy

The Linear, Jira and Slack command files each defined a private getStackOutput with the same body: read one CloudFormation output, and answer 'none' for a stack that does not exist. The CLI's shared module exports a function of the very same name with another contract (it fails for a missing stack), so a reader had to find out which of the two a call meant. The shared module now also has the lenient variant under its own name, findStackOutput, and the Linear commands use it in place of their private copy. The Jira and Slack copies are in files outside this change and are listed for follow-up.

Gain: One name per contract in the Linear commands, and the rule 'a missing stack is an answer, any other failure is an error' has direct tests for the first time (7). In this commit the line count is about even (a 21-line private copy and its import leave the Linear commands, 25 lines with their description arrive in the shared module); replacing the Jira and Slack copies the same way removes about 40 more lines.

Test: cli/test/stack-outputs.test.ts > describe 'findStackOutput' (7 tests)

fix(cli): let Linear prompts read a piped answer, test consent guards

Lean (merge): bgagent linear setup, add-workspace and invite-user share one login-token decoder and one error wording

Three Linear commands (setup, add-workspace, invite-user) record which platform user ran them. Each read that user from the cached login token through a private decoder, of which a second copy sat in the Jira commands and a third in the login module. A token that could not be read gave two different errors: setup and add-workspace wrapped the reason in a sentence of their own, invite-user printed the bare reason with no remedy. The three commands now call one function of the login module, which shares its decoder with change-password. Without a login they all say 'Not authenticated. Run bgagent login first.'; for a token with the wrong number of segments or a payload that is not JSON, 'Credentials file is corrupt. Run bgagent login to re-authenticate.'; for a token that names no user, 'Could not read your account identity. Run bgagent login to re-authenticate.'

Gain: 24 lines of product code fewer (49 removed from the Linear commands, 5 added there, 20 net added to the login module), and one decoder of the login token where the Linear commands and the login module had two. One wording for a missing or unreadable login in setup, add-workspace, invite-user and change-password. Cyclomatic complexity: setup and add-workspace 4 lower each, invite-user 2 lower. 16 new test cases; the corrupt-token paths of the decoder had none. The rest of this item, moving the browser opener and the OAuth state generator to the callback module and switching the Jira commands to the shared decoder, is handed to the next change as a tested patch.

Test: cli/test/commands/linear-helpers.test.ts > makeLinearCommand > '%s, which records the platform user who ran it' > 'fails on %s with the error of every command that needs a login' (setup, add-workspace, invite-user x no login, an ID token that cannot be read); cli/test/auth.test.ts > auth > cognitoSubFromSession > 'reads the sub claim of the cached ID token' and 'fails with a CliError that names 'bgagent login' when %s' (7 cases); auth > changePassword > 'signs in with cognito:username when the ID token carries no email claim' and 'an ID token that names no user yields a clear error before any call to Cognito'

Lean (merge): Five Linear commands check the workspace slug through one function instead of five copies (15 lines fewer)

Five Linear commands (setup, add-workspace, update-webhook-secret, remove-workspace, invite-user) each began with the same six lines that check the workspace slug and build the same error message, so a change of the rule had to be made in five places. The check is now one function next to the pattern it tests, called by the five commands. Nothing changes for a user: the message is word for word the one each command printed before.

Gain: 15 lines of product code fewer (30 removed, 15 added); the slug rule and its message exist once. Four of the five checks had no test: each command now has a case that fails when its check is dropped (6 deliberate breakages tried on a scratch copy, all caught). Cyclomatic complexity goes down by one in each of the five handlers; with the item above, setup goes from 104 to 99, add-workspace from 35 to 30, invite-user from 26 to 23 and update-webhook-secret from 17 to 16.

Test: cli/test/commands/linear-helpers.test.ts > makeLinearCommand > '%s refuses a slug that cannot be a workspace URL key, before it reads anything' (the five commands); unchanged: cli/test/commands/linear-remove-workspace.test.ts > 'rejects an invalid slug without hitting the API'

Test: A test fails when one of the four Linear consent paths accepts a state the command did not send

The Linear consent flows compare the state value that comes back with the one the command sent, in four places: the local callback of setup and of add-workspace, the value pasted from the hosted consent page, and the value pasted to setup --code. That comparison is what keeps a code the command never asked for from being exchanged for a token. No test ran any of the four with a wrong state, so each could be deleted with every test still passing. Four tests now send a wrong state down each path and check that the command stops before the code is exchanged and before anything is written.

Gain: Deleting or inverting any of the four checks now fails a test: 6 deliberate breakages tried on a scratch copy, all caught, where the 4 deletions passed all 281 Linear tests before. The Jira copy of the check already had such a test, the Linear ones had none. No product change.

Test: cli/test/commands/linear-setup-webhook.test.ts > 'refuses before anything is written' > 'an answer whose OAuth state is not the one this machine sent' > 'to the loopback listener of 'setup'', 'to the loopback listener of 'add-workspace'', 'pasted from the consent page', 'pasted to '--code', for the consent an earlier run saved'

Test: A test fails when bgagent linear update-webhook-secret drops its registry write or the stored tokens

bgagent linear update-webhook-secret is the command the setup guide names for a workspace whose deliveries are rejected. It makes two writes: the new signing secret into the workspace's credential bundle, and a flag on the registry entry that says the workspace owns that secret, without which the webhook receiver keeps rejecting its deliveries on a stack with two workspaces. No test checked either write: the registry write could be deleted, or the stored tokens dropped from the rewritten bundle, with every test passing. Six test cases now check both writes, the two ways the registry write can fail, a stack that publishes no registry table, and that a mistyped secret stores nothing.

Gain: 7 deliberate breakages of the command now fail a test, where the three the audit named passed all 281 Linear tests before: no registry write, a wrong registry key, a bundle rewritten without the stored tokens and client secret, the registry left out when the stack output is missing, a failed registry write ignored, a value that is not a signing secret accepted, an empty value accepted. No product change.

Test: cli/test/commands/linear-helpers.test.ts > linear update-webhook-secret > 'replaces the signing secret in the bundle, keeps the rest of it, and records that the workspace owns it', 'fails when %s: the secret alone is half the repair' (2 cases), 'fails when the stack publishes no registry table, instead of leaving the registry out', 'stores nothing when what was pasted %s' (2 cases)

Test: A test fails when linear backfill-secret-provenance marks a copied secret owned or a dry run writes

bgagent linear backfill-secret-provenance records, for each workspace whose stored webhook signing secret is provably its own, that it owns it; the webhook receiver trusts that record. A workspace that only holds a copy of the stack-wide secret must not get it, because a delivery signed with a shared secret does not show which workspace sent it. The function that classifies a secret was tested, the command around it only for two failures of its write: recording a copied secret as owned, comparing against nothing, or treating an unreadable stack-wide secret as absent passed every test, and nothing checked that --dry-run writes nothing. Three tests now run the command on a registry with an owned, a copied, a missing and an already recorded secret.

Gain: 5 deliberate breakages now fail a test, where the four the audit named passed all 281 Linear tests before: a copied secret recorded as owned, the comparison made against nothing, an unreadable stack-wide secret treated as absent, a dry run that writes, an already recorded workspace written again. The test also pins the report the operator acts on: which workspaces still need update-webhook-secret. No product change.

Test: cli/test/commands/linear-helpers.test.ts > linear backfill-secret-provenance > 'on a registry where one workspace of four is known to own its secret' > 'records that one, and names the others that need a secret of their own', 'writes nothing with --dry-run, and says what it would record', 'records nothing when the stack-wide secret cannot be read'

Test: A test fails when bgagent linear setup stops refusing to move a vault workspace to Secrets Manager

bgagent linear setup refuses to run for a workspace that is on the AgentCore Identity vault when the run would use Secrets Manager instead. It rewrites the registry entry whole, so such a run would drop the vault binding and put a stored long-lived token in the place of minted short-lived ones, behind 'Setup complete'. No test reached that refusal, so it could be deleted unnoticed. Two tests now cover the two ways to get there: a stack that was deployed again without the vault, and --code, which finishes a consent of the Secrets Manager path.

Gain: 4 deliberate breakages of the guard now fail a test, where deleting it passed all 281 Linear tests before: no refusal, a refusal only when the stack has no consent page (which lets --code through), the condition turned round, a registry row that is never read as being on the vault. No product change.

Test: cli/test/commands/linear-setup-webhook.test.ts > 'refuses before anything is written' > 'a workspace that is on the Identity vault, when the run would not use the vault' > 'on a stack that was deployed again without the vault', 'with '--code', which finishes a consent of the Secrets Manager path'

Every visible prompt of the Linear commands failed with 'No input provided.' when its answer came from a pipe or a file instead of a terminal: the confirmations of linear link and linear remove-workspace, the member picks of setup, add-workspace and invite-user, the client id of add-workspace and the value pasted from the hosted consent page. The prompt closed its line reader before it kept the line it had just read, and closing rejects a prompt that has no answer yet. It now keeps the line first, as the password prompt of bgagent login already does. Behind that defect sat a second one, in every command that asks a visible question and a secret one on the same pipe (linear add-workspace, linear setup, jira setup, slack setup): the two prompts read stdin through two readers that did not hand over to each other. A secret prompt asked after a visible one never answered, and the command ended with exit code 0 in the middle of its work, with no error: linear add-workspace after the app was authorized in Linear, with nothing stored; jira setup on a login that sees several sites, after the OAuth bundle and the registry row were written; slack setup in the round after a refused one. A visible prompt asked after a secret one never answered once the input had ended (slack setup without input, jira setup with the client id and secret from the pipe, the member pick of linear setup). A visible answer written while its prompt was waiting was read by both readers, and the copy answered the next secret prompt: jira setup stored the site number as the webhook signing secret, behind 'Setup complete', and slack setup took the Client ID of a refused round as the Signing Secret of the next. And a visible prompt took every line of a write and kept the first, so that answers written at once were lost. There is now one reader: both prompts take their lines from it, so every line answers one prompt, in the order of the questions, whether the answers arrive in one write or one at a time. The reader stops reading while no prompt is waiting, so an input without end (yes | bgagent jira link <code>) stays in the pipe instead of being read into memory. When the input has ended, a visible prompt stops the command with 'No input provided.' and a secret prompt answers with an empty value, which the commands refuse where they need a value ('Webhook signing secret is required.'). Gain: a piped answer is read, so printf 'acme\n' | bgagent linear remove-workspace acme removes the workspace and a wrong line aborts with the message written for that; before, only --yes and --output json, which skip the prompt, could be scripted. The four commands that ask both kinds of question now do their work on a pipe or stop with an error and exit code 1. Of 146 cases run with the compiled CLI before and after (the 122 of the review's probe and 24 more; pipes, /dev/null and a pseudo-terminal), 23 ended without a word before, with exit code 0 or still waiting, and 3 stored the site number as the signing secret; now none does either, and the 26 cases on a pseudo-terminal are unchanged. Where a command stores something before a later question (the workspace before the member pick, the Jira bundle before the signing secret) and the input ends at that question, it now stops there with an error, where such a run could end with exit code 0; the order of those steps is not changed. The first defect was a refusal, so nothing wrong was ever written by it. No test saw either defect because every test replaced the line reader with a double whose close does nothing; the tests now read through the real one, with both prompts on one stream. Found while preparing the move of this prompt to a shared module; it is not one of the audit's findings.

fix(cli): share one visible prompt that fails at the end of input

Lean (merge): Linear, Jira and Slack commands ask through one visible prompt, which fails at the end of the input

The Linear, Jira and Slack commands each had their own prompt for a visible answer, and the three behaved differently when the input ended without an answer: the Linear one stopped with an error, the Jira and Slack ones never answered and the command ended with exit code 0 as if it had worked. There is now one prompt, beside the hidden one for secrets, and all three commands use it. A missing answer is an error (exit code 1), also when the input had ended before the prompt was asked: that covers the confirmations of jira link, linear link and linear remove-workspace, which an empty pipe therefore cannot pass, and it covers slack setup on an empty input and jira setup with the client id and secret read from the same pipe, which now stop with 'No input provided.'. On a pipe the two prompts take their lines from one reader, each the next line in the order of the questions, whether the answers come in one write or one at a time: a visible prompt asked after a hidden one reads its own line, and a hidden prompt asked after a visible one reads its own line and answers with an empty value when the input has ended, which the commands refuse with an error (the single reader is in the follow-up commit of the Linear command fixes). For Jira the prompt text now goes to stderr, where Slack's already went, and for both Ctrl-C ends the command with an error instead of exit code 0. On a terminal the Jira and Slack prompts now read the way the Linear ones always did: Delete works, the other editing keys of readline (arrow keys, Ctrl-U) and Ctrl-D as the end of the input do not, such a key becomes part of the answer.

Gain: One prompt instead of three copies: about 95 lines of prompt code leave the three command files and the shared module grows by 40. jira link now stops with 'No input provided.' and exit code 1 at the end of the input, where it ended silently with exit code 0. So does the site choice of jira setup when the client id and secret are given as options, and the Client ID of slack setup when the input ends after the two secrets. slack setup, whose action no test ran, gets three tests. Product code of this commit: 122 lines added, 330 removed.

Test: cli/test/commands/prompt-secret.test.ts > 'promptLine (non-TTY / piped stdin)' and 'prompts on a terminal (raw mode)'; cli/test/commands/slack.test.ts > 'slack setup' > 'fails, and stores nothing, when the input ends before the Client ID'; cli/test/commands/jira.test.ts > 'text mode does not link when the confirmation cannot be read'

Test: Tests run onboard-project and pin the owning workspace it records, or that nothing is written

No test ran the command that maps a Linear project to a repository. The row it writes names the workspace that owns the project, which is what the webhook path checks a delivery against; a row without it is accepted with a warning only, so losing that value would have gone unnoticed. Seven tests now run the command: the owner that Linear reports is recorded, nothing is written when no workspace can see the project, and input that cannot be used stops the command before any write.

Gain: The value that ties a project to its tenant is asserted where it is written. Three mutations (the owner left out of the row, an unresolved owner still written, a malformed --workspace-id accepted) passed every Linear test before and fail now.

Test: cli/test/commands/linear-onboard-project.test.ts > 'records the workspace that Linear says owns the project'

Test: Tests reach the self-link picker of setup and add-workspace and pin the user mapping it writes

The step that ends setup and add-workspace, where the admin picks their own Linear user from the member list, was reached by no test: every fixture had an empty member list. Two tests now run it, one for each command, and check the user mapping row that is written and that the app's own bot user is not offered as a choice.

Gain: The only user mapping that the CLI writes itself is asserted. Two mutations (the key written the wrong way round, the bot user not filtered out) passed every Linear test before and fail in both new tests now.

Test: cli/test/commands/linear-setup-webhook.test.ts > 'ends by linking the admin to the member they pick, never to the app's own user' (and the test of the same name under 'add-workspace' in cli/test/commands/linear-multi-workspace.test.ts)

Lean (delete): The Linear OAuth module no longer carries an expiry helper that only its own tests called

The Linear OAuth module had a function that tells whether an access token is about to expire. Nothing but its own five tests called it: the Linear commands never refresh on expiry, and the one command that checks an expiry uses the Jira module's function of the same name. The function, its constant and the five tests are deleted.

Gain: 49 lines removed (21 source, 28 test). No behaviour changes; the type check and the dead-code check pass.

Lean (yagni): Linear OAuth and vault helpers lose three parameters and a result field that nothing used

Four ways of calling the Linear OAuth and vault helpers were never used: a scope list for the authorization URL, a return URL for minting a token, a client to finish a consent with, and a session field on the consent result that only one test read. They are removed. Every caller already relied on the defaults, which are now the only behaviour.

Gain: 23 source lines fewer (27 removed, 4 rewritten) and one 17-line test removed. The type check proves that no caller passed the three parameters.

Lean (merge): The Jira OAuth error for an unexpected token response names the fields it got, not their values

When Atlassian's token endpoint answered with something other than the expected token response, the Jira setup commands put the first 200 characters of that answer into the error message. Such an answer can still hold an access token or a refresh token, for example when one other field is missing or has another type, so the tokens were printed to the terminal and into whatever captured its output. The Linear commands had the same defect until an earlier fix; the Jira parser now describes the answer the same way: which fields are present and of which type, never their values.

Gain: A token can no longer reach a terminal scrollback, a CI log or a pasted error report through this message. One line changed and one function exported; a new test file covers the code exchange and the refresh, and fails on the old message.

Test: cli/test/jira-oauth.test.ts (the code exchange and the refresh with an off-contract response)

The Jira commands had their own copies of three helpers that the Linear commands also had: opening the browser, making the OAuth state value, and reading the signed-in user from the cached login. The copies are deleted and both providers use one of each (the browser opener and the state generator live beside the callback listener). Three Jira messages change to the wording Linear already had: without a login, "Not authenticated. Run bgagent login first."; with an unreadable login token, "Credentials file is corrupt. Run bgagent login to re-authenticate." (setup said "Could not read Cognito sub from cached id_token", invite-user printed a bare "malformed id_token"); with a token without a user id, "Could not read your account identity. Run bgagent login to re-authenticate.". Gain: about 60 lines fewer in the Jira command file, and one place to change each helper.

The Jira and Slack command files lose their private getStackOutput, left for follow-up when findStackOutput was added to the shared module: their nine and six calls use the shared function, whose body is the same. About 40 lines fewer, no change of behaviour.

refactor(cli): drop a hand-written JSON walk and two wrapper functions

Lean (yagni): Inviting a user and resetting a password each make their Cognito call in one function, not two

In the code behind bgagent admin, inviting a user and resetting a password were each split over two functions: one that the command calls, and a second one behind it that made the Cognito call and had no other caller. Each pair is now one function, shaped like the delete and list operations next to it, and a test that checked the 'already exists' message a second time through the inner function is gone. The commands behave as before.

Gain: 28 lines fewer (19 of product code, 9 of tests): two functions and one duplicate test. Two of the tests that remain now also check the user pool, the password and the permanent flag that reach Cognito: five wrong values in the merged code passed the whole unit suite without those checks, and each fails a test with them.

Test: cli/test/commands/cognito-admin.test.ts > describe 'adminInviteUser (#238 ...)' > 'creates the user with a TEMPORARY password and never sets a permanent one' and 'propagates UsernameExistsException as a CliError'; describe 'adminResetPassword' > 'sets permanent password for existing user by email' and 'maps UserNotFoundException to CliError'

Lean (stdlib): Verbose output masks secret fields while JSON.stringify writes the body, with no copy made first

With --verbose the CLI prints request and response bodies with secret fields masked. The masking was a hand-written recursive copy of the whole body, and both places that used it only turned the copy into JSON text. The standard JSON writer now masks the fields while it produces that text, so the copy and its recursion are gone. For the bodies this API exchanges, the printed text is the same, with one exception: a field named __proto__ in a parsed body, which the old copy dropped from the log, is now printed, masked like any other.

Gain: 10 lines fewer: a 13-line recursive function became a 3-line call into the standard library, and verbose mode no longer copies every request and response before printing it. Old and new were run side by side on the body shapes the API uses and on 5000 generated bodies holding 11542 masked fields: the same text every time.

Test: cli/test/debug.test.ts > describe 'redactedJson' (the six cases of the old helper, now comparing the parsed text); cli/test/api-client.test.ts > ApiClient > --verbose output > 'masks the one-time API key in the logged response body' (unchanged)

@krokoko

krokoko commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor Author

bgagent CLI (part 2 of 2): what changes and what it gains

fix(cli): follow the API's attachment limits and list pagination

Bug: bgagent submit refuses .gif and .webp itself and uploads small files beyond 3 MB of inline data

The CLI accepted .gif and .webp attachments and sent them, although the API takes PNG and JPEG images only, so the user got an error from the server after the file had been read and sent. It also put every file of up to 500 KB into the request itself, while the API refuses a request that carries more than 3 MB that way: seven screenshots of 450 KB could not be submitted from the CLI at all. The CLI now refuses the two image types itself, with a list of supported types that is true, and uploads the files that no longer fit into the 3 MB, the way it already uploads large files.

Gain: A task with 7 to 10 small attachments that together exceed 3 MB can be submitted from the CLI. Before, the API answered 400 and advised the upload path, which the user could not choose: the CLI picked it by file size alone. A .gif or .webp is refused at once instead of after a round trip. Checked against the API's own validation code: it refuses what the old CLI sent in both cases and accepts what the CLI sends now. The command file gets 4 lines shorter.

Test: cli/test/commands/submit.test.ts > attachments > 'refuses a .gif file before anything is sent', 'refuses a .webp file before anything is sent', 'sends at most 3 MB of files inline and uploads the ones beyond it'

Scale: bgagent webhook list and api-key list follow next_token until the rows asked for are there

bgagent webhook list and bgagent api-key list asked the API for one page and stopped. The API reads a bounded number of rows per request and expects the client to go on with the token it returns, so a page can be short or empty while more entries exist: a user with a few hundred recently revoked webhooks was told 'No webhooks found.' although an active one existed, and no one could list more than 100. Both commands now go on until they have the number of entries asked for with --limit (20 without it) or the list ends.

Gain: An active webhook or API key that sits behind many revoked ones is listed again, so it can be revoked by its id; today the command says there is none. A user with more than 100 webhooks or keys can list them all with a larger --limit. A list that fits into one page still costs one request, and a command never sends more than 100.

Test: cli/test/commands/webhook.test.ts > webhook list > 'follows next_token when a page holds fewer webhooks than asked for', 'stops at --limit, asking each further page only for the webhooks still missing', 'stops after 100 requests when every page is empty and promises more'; the same three in cli/test/commands/api-key.test.ts > api-key list

Risk: bgagent configure drops the cached login when it points the CLI at another user pool

bgagent configure could point the CLI at another deployment and keep the login of the previous one. The next command then sent that token, still valid for the first deployment, to the new API address instead of saying 'Not authenticated'. bgagent setup already removes the cached login when the user pool changes; configure now does the same.

Gain: A token that deployment A still accepts for up to an hour is no longer handed to whoever operates the API of deployment B (a bundle received from someone else, a stack of another team). The user is asked to log in instead of getting a 401 from the wrong API. The two commands that re-point the CLI follow one rule: 2 lines of code and a sentence in the CLI README.

Test: cli/test/commands/configure.test.ts > 'drops cached tokens when the CLI is pointed at another user pool, and keeps them otherwise'

Bug: bgagent watch exits with code 2 and the real failure count when it gives up on a failing API

When the API kept failing, bgagent watch gave up with exit code 1, the code it also returns for a task that ended FAILED, and its message said 5 failures where six requests had failed. A script could not tell a failed task from a lost connection. It now exits with code 2, as --wait does when it gives up, and the message states the real count. The user guide names the code for watch; the CLI README, which has no section on watch, now names it for --wait, where it was missing.

Gain: A script that wraps bgagent watch can tell 'the task failed' (1) from 'the CLI lost the API, the task may still be running' (2), as it already can with --wait. The message agrees with the server logs: six failed requests are reported as six.

Test: cli/test/commands/watch.test.ts > 'exhausted retry budget throws a "re-run to resume" message' and 'initial snapshot exhausts retry budget on persistent 5xx and surfaces a "re-run" hint' (assertions added to both)

When two attachments of a task had the same file name in different folders (before/shot.png and after/shot.png) and had to be uploaded, bgagent submit uploaded the first file for both: for every upload it looked the local file up by name. The task then held the same picture twice and never the second one, and nothing reported it; a small file with the name of a large one was uploaded in its place the same way. Each upload is now paired with its file through its attachment id: the task lists the uploads of one name in the order the files were given, and the place of the upload's attachment among them is the place of its file among the files of that name (changed again after the first reviews: taking the next file of its name sent the wrong file when the same command was sent again). Gain: the agent gets the files the user attached. The mix-up was found while sending small files down the upload path, which would have exposed them to it too.

bgagent replay <id> --output <file> --force over a file that already existed left that file readable by other users (mode 0644): the owner-only mode of a write applies only when the file is created. The replay bundle, the saved login, the pending Linear consent and the invite file of bgagent admin are now written through one function that also sets the mode of a file that was already there (regular files only, so that --output /dev/null keeps working). Gain: a replay bundle written over an old file is owner-only like a new one, and three copies of the write-then-chmod sequence are one function. These are the tested patches an earlier change set of this pull request handed over.

No change of behaviour: two private copies of 'is this status final' and six type casts are deleted, now that the list of final statuses carries the status type, and bgagent watch takes the exit code of a finished task from the function --wait uses instead of two inline copies (13 lines fewer). The upload error handler of bgagent submit no longer declares its error as any, one of the four uses that keep that lint rule switched off in the CLI. Both are tested patches handed over by earlier change sets of this pull request.

@krokoko

krokoko commented Nov 18, 2026

Copy link
Copy Markdown
Contributor Author

Registry: what changes and what it gains

fix(registry): stop publish stranding records and hiding the reason

Bug: A slow registry publish completes or returns the error that names the stranded record, not a gateway error

Publishing a registry record waits for the new record to finish creating. That wait was allowed to last 60 seconds, inside a function that is stopped after 15, so a record that needed more than about 12 seconds was left behind as a draft that blocks every retry of that version, the publisher got a bare gateway error, and no log line named the record. The publish function now gets 28 seconds (API Gateway allows 29) and the wait is 20 seconds, so a slow create either completes or ends in the designed error that names the stranded record.

Gain: A create that takes between about 12 and 20 seconds now publishes instead of stranding a draft. A slower one returns the 502 that carries the record id, and logs it, instead of a gateway error with nothing in the log. The branch that reports a record stuck in creation could never run in the deployed function and now can. The three read functions keep 15 seconds.

Test: cdk/test/constructs/registry-api.test.ts > 'the publish function gets 28 s, the three read functions the standard 15 s'; cdk/test/handlers/shared/agent-registry-client.test.ts > 'publish throws when the record never leaves CREATING (poll budget exhausted)' (one assertion added: the fake clock has advanced at most 25 000 ms)

Speed: Resolving a pinned asset and the publish duplicate check fetch only the records of that asset

To find the records of one asset, the registry client fetched every record of the same kind and namespace in full, one call after the other, and only then kept the ones with the right name. The list it starts from already carries each record name, so it now skips the records of other assets before fetching them. Resolving a pinned asset and the duplicate check before a publish no longer fetch the records of other assets. The listing itself is unchanged: one call per 50 records of the whole registry.

Gain: Resolve and the publish duplicate check send one GetRegistryRecord per record of the asset in question instead of one per record of its kind and namespace: 1 instead of 4 and 0 instead of 3 in the tests, and up to 119 sequential calls less per resolved pin in a namespace of 120 records, at every task start that pins an asset. Results are unchanged. The show command still fetches every record of the kind and namespace: its handler (cdk/src/handlers/registry-show.ts, not changed by this commit) has to pass the asset name to get the same saving.

Test: cdk/test/handlers/shared/agent-registry-client.test.ts > 'resolve fetches the records of the asset it resolves, not those of its neighbours', 'getRecord (the publish pre-check) fetches no record of another asset', 'listBrowseEntries filtered by name fetches and returns that asset only'

Bug: A publish conflict returns the registry's own message, such as the hint to delete a corrupt record

When the version being published is already taken by a record whose stored content is corrupt, the registry client prepares a 409 message that says so and tells the publisher to have that record deleted. The handler replaced every conflict message with one fixed sentence, 'A record with these coordinates already exists.', so the hint never reached anyone. The handler now returns the conflict message it was given.

Gain: The publisher who hits a corrupt slot learns that the record has to be deleted, instead of concluding that the version is published and fine. A conflict reported by AWS itself keeps its own text as well. One line changed, one hard-coded sentence less.

Test: cdk/test/handlers/registry-publish.test.ts > '409 says so when the slot is held by a corrupt record that has to be deleted'

Bug: Registry publish answers 400 with AWS's reason when AWS refuses the record as invalid, not 500

When AWS refused a record as invalid (a name or version longer than 255 characters, a descriptor above its size limit, a server.json that does not follow the MCP schema), the publisher got 500 'Failed to publish record.' and had to ask an operator to read the function log. The publish handler now answers 400 with the reason AWS gave.

Gain: A publisher who sends something the registry cannot store is told what is wrong and can fix it alone, where before it looked like an outage and needed an operator and a log search. The AWS user guide lists descriptor schema errors at record creation as a common case. Three lines.

Test: cdk/test/handlers/registry-publish.test.ts > '400 with the reason when AWS rejects the record as invalid'

Risk: Registry publish answers 400 when namespace, name or asset_version is not a string

The publish handler checked namespace, name and asset_version with a regular expression only, and a regular expression test converts what it is given to text, so a one-element list or a number passed as if it were a string. The duplicate check behind it compares with strict equality, so it found nothing and the handler went on to send the create request for coordinates that were already published; whether AWS then stores a second record is not established. All three fields must now be strings, or the request is answered 400.

Gain: The 400 the API promises for a malformed body, and a duplicate check that the shape of a request can no longer switch off. Three conditions changed, no new branch.

Test: cdk/test/handlers/registry-publish.test.ts > '400 when namespace is an array, and nothing is published' and its three sibling rows (name is a number, name is an array, asset_version is an array)

Bug: An exact registry pin matches only the version as written, in both the TypeScript and Python resolvers

An exact pin such as 1.0.0-rc.1 also matched a version published as 1.0.0-rc.01, because numeric prerelease parts were compared as numbers; with both published, which one a task got depended on the order of the listing. Separately, the TypeScript resolver rounded numeric prerelease parts above 2^53 and could pick a different version than the Python resolver. An exact pin now matches only the version as written, in both languages, and TypeScript compares those parts exactly.

Gain: An exact pin returns the pinned version and nothing else, and the two resolvers rank numeric prerelease identifiers the same way, whatever their length: a comparison of the two on 921,777 generated inputs shows no difference. Rare inputs; two one-line changes in TypeScript and two small ones in Python (the second came from the review: a pin with an identifier of more than 4300 digits made the Python resolver raise ValueError).

Test: cdk/test/handlers/shared/registry-resolver.test.ts > 'exact matches the version as written, not one that only compares equal', 'an exact pin returns the pinned version, whatever the order of the candidates', 'numeric prerelease identifiers above 2^53 are compared exactly', 'picks the higher of two numeric prerelease identifiers above 2^53'; agent/tests/test_registry_resolver.py > TestExactPin

Bug: The Python registry reference parser accepts ASCII digits only and rejects an over-long version part

The Python copy of the registry reference grammar is documented as a byte-for-byte mirror of the TypeScript one, and it was not. It accepted digits from other scripts (1.1 followed by an Arabic-Indic 2 was read as minor version 12), gave a reference that ends in a carriage return a different error reason, and failed with a plain ValueError on a version component of more than 4300 digits. The Python patterns now accept ASCII digits only, exclude the same line terminators as JavaScript, and reject an over-long component before converting it.

Gain: Both parsers give the same verdict and the same reason for these inputs, which is what the parity contract between the platform and the agent promises. No production code calls the Python parser today, so this removes a trap for its first caller, not a live failure. Five small edits in two files.

Test: agent/tests/test_registry_ref.py > TestSameVerdictAsTheTypeScriptParser (five cases); agent/tests/test_registry_resolver.py > TestCandidatesTheTypeScriptResolverSkips (two cases)

fix(registry): delete a registry's records before deleting the registry

Bug: The registry custom resource deletes a registry's records first, as AWS requires, then the registry

A stack whose agent registry holds a published asset could not be deleted, and switching the registry feature off left the registry and its records in the account. AWS refuses to delete a registry while it holds a record, and the custom resource that manages the registry treated that refusal as temporary: it sent the same delete at every poll, deleted no record, and after 15 minutes its delete failed with 'Operation timed out'. The custom resource now deletes the records first, for at most 30 seconds per invocation so that a large registry is emptied over several polls, and then deletes the registry. Its two Lambda roles get the two permissions this needs, ListRegistryRecords and DeleteRegistryRecord. A stack deployed before this change still runs the old handler: deploy the change once, with the registry enabled, before removing the registry or the stack. Tested with unit tests and on the emulator; not run against AWS.

Gain: Bug fixed: deleting a stack now completes when assets are published, and deploying with enableAgentRegistry=false now removes the registry and its records, which is what the deployment guide and the design documents already promise. Before, the custom resource's delete of such a registry timed out after 15 minutes with a message that does not mention records. A stack deletion ended in DELETE_FAILED. A deploy with the feature off completed all the same, because CloudFormation gives up on a resource it cannot delete during an update (CloudFormation user guide): the registry, its records and the nested registry stack stayed in the account, no longer part of the stack. In both cases the operator had to delete each record by hand with the AWS API, because ABCA has no command for it. Cost: 46 lines of product code in 2 files, 2 IAM actions on the resource pattern the roles already had (registry/*, which also matches the records of every registry of the account in that Region), and the first emulator-tier test of the registry (about 5 seconds).

Test: cdk/test/handlers/registry-provisioning/index.test.ts > 'Delete of a registry that holds records' > 'deletes the records, then the registry' (plus 8 tests beside it: two pages, a record that refuses deletion, a record already gone, another error, three answers of the record list, the time budget); cdk/test/constructs/registry.test.ts > 'lets both Provider handlers list and delete the records of a registry'; cdk/test/emulator/registry-provisioning.emulator.ts > 'Delete removes a registry that holds published assets'

Bug: The emulator README lists the registry's one-record-per-name refusal as a known difference from AWS

The emulator README listed two agent registry answers under operations that do not work on the emulator and said that neither had been compared with AWS. Both have been checked since. The refusal to delete a registry that holds records is what AWS does; the custom resource now handles it and an emulator test covers it, so that sentence is removed. The refusal of a second record under a name the registry already holds, whatever its version, is the emulator being stricter than the AWS user guide, which says that name and record version together must be unique; it is now a row in the table of known differences, and the trust table says what a green run shows for the registry.

Gain: A contributor who reads the README to decide where a registry test belongs is no longer led to suspect ABCA's publish code for a difference that the AWS user guide puts on the emulator's side, and learns that creating and deleting the registry through the custom resource can now be tested on the emulator. Documentation only: 3 lines added, 2 removed.

Test: No code test, the finding is documentation. Its emulator half was observed on the emulator with a probe script that is not part of the repository: a second CreateRegistryRecord with the same name answers 409 ConflictException, with another recordVersion and with the same one. The removed sentence is contradicted by cdk/test/emulator/registry-provisioning.emulator.ts > 'Delete removes a registry that holds published assets'. docs markdown-lint (110 files, no structural errors) and markdown-link-check on the file pass.

fix(registry): keep git working in clones with registry MCP servers

Bug: Two pins of one registry MCP server that resolve to different versions fail the task with the reason

A Blueprint can pin the same registry MCP server twice, for example at ^1.0.0 and at ^2.0.0 after a migration that was left half done. Both pins were resolved and both versions were recorded on the task, but the agent keeps one entry per server, so the second silently replaced the first: one version ran and the task record named two. The agent now fails such a task with a message that names the server, as the loader already does for a pinned server whose configuration is missing or invalid. Two pins that resolve to the same server configuration are still accepted.

Gain: Bug fixed for a rare configuration: a double pin can no longer make the task record name an MCP server version that was never loaded, and the operator learns of the double pin from the first task instead of running one of the two versions without knowing which. It takes two published versions of one asset and a Blueprint that pins both. 9 lines in one function; unit tests only, because the emulator cannot hold two versions of one asset.

Test: agent/tests/test_registry_loader.py > TestApplyMcpAssets::test_two_pins_of_one_asset_that_resolved_differently_raise

Lean (delete): The registry documents that tool_prefix is not applied and how a registry server's tools are named

A publisher can set a field named tool_prefix on a registry MCP server, and the code documented it as the prefix under which the server's tools appear. Nothing applies it: the agent copies it into the session's MCP configuration, where the Claude CLI drops it, and the tools are named after the server's namespace and name. The type comment and the design document now say that, with the real name pattern.

Gain: A false promise in the publish contract is gone: a policy rule or a skill hint written against the documented prefix would never have matched a tool, and a forbid rule on such a name would have forbidden nothing. Documentation only, two files, no behaviour change. The field itself is still accepted: removing it is left to the owner, because publish would then refuse requests it accepts today.

Gate: cdk-nag checks again that every registry API route uses the Cognito authorizer

The registry API suppressed the cdk-nag rule that reports a route which does not use the Cognito authorizer, giving as the reason that all routes use it. The rule had nothing to report, so the suppression only switched the check off: a route added later with another kind of authorization, such as IAM, would have passed the build unnoticed. The suppression is removed, so the build now checks what its reason claimed.

Gain: Gate restored: cdk-nag now reports a registry route that is not behind the Cognito authorizer (AwsSolutions-COG4), and the deployment tests of the build fail on it. Shown by switching one route to IAM authorization: it passed before and fails now. The application is clean without the suppression in all 132 deployment profiles that the tests synthesize. 4 lines removed. A route with no authorization at all was already reported, by another rule.

Test: cdk/test/synthesis/deployment.test.ts (existing) > '<profile> deployment keeps every template within budget': its audit lists every cdk-nag error of the synthesized profile as a failure

When a task loads MCP servers from the registry, the agent writes them into .mcp.json in the clone. That file can hold credentials, so the agent keeps it out of commits. For a repository without a .mcp.json of its own, which is the usual case, it did so by registering the file in git's index without content, and git treats such an entry as an uncommitted change: git stash, git rebase, git pull --rebase, git cherry-pick, git reset --hard and every merge that is not a fast-forward failed in the clone for the whole task. The agent now lists the file in the clone's own exclude file, which is never committed, as another change of this pull request does for downloaded attachments. Those commands work again, and the file stays out of git add -A, git add ., git add -u, git commit -a, an add that names the file, the same commands after a git reset, and the commit the platform makes at the end of a task. When git refuses an add that names the file, it no longer prints its hint to force the add. A repository that tracks .mcp.json is handled as before. Where a repository's own .gitignore re-includes the file when the task starts, or the exclude file cannot be written, the earlier protection is kept, because such a rule outranks the exclude file. Gain: every task with registry MCP servers on a repository without a .mcp.json can stash, rebase and merge again, which restack tasks tell the agent to do, and a repository that already ignores .mcp.json no longer gets a warning in the log of every such task. Checked with real git, one fresh repository per command, on git 2.54 and on the git 2.47 of the agent image. With the two corrections from its review, which a later change of this pull request carries: one function and one import, and about 40 tests with real git.

@krokoko

krokoko commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor Author

Follow-up changes in neighbouring files, and documents brought in line (part 1 of 2): what changes and what it gains

chore(cdk): drop dead cdk-nag suppressions, fetch less in registry show

Gate: The coverage drift check's suite covers the removal of the two lists that make pragma comments inert

The agent's coverage settings hold two lists that stop a pragma comment (no cover, no branch) from taking code out of what the coverage floor measures, and the drift check fails when a list is removed from the settings. The check's own test suite had no case for that: it tested a removed setting only for another package. Two cases now remove each list from a copy of the settings and expect the check to name it.

Gain: If the drift check ever stops holding these two lists, its own suite fails: run against the contract as it was before it pinned them, both new cases fail because the check reports no drift. Test only, 8 lines, under one second of test time.

Test: cdk/test/scripts/check-coverage-thresholds-sync.test.ts > 'pytest (agent)' > 'a list that replaces a default of coverage.py removed: exclude_lines' and '...: partial_branches'

Docs: Comments name the admission step and tie the CLI's wait to the upload confirmation timeout

Two comments no longer matched the code. The description of the Jira notice for a task that waits at the concurrency limit still spoke of a rejection path; a task is queued there, not rejected, and the comment now names the admission step, as its Linear twin already does. The comment on the timeout of the upload confirmation did not say that bgagent submit derives its wait after a gateway timeout from that value, which an earlier commit of this branch introduced; it now says so and asks to change the two together. The same comment said that a confirmation screens up to five attachments, where a task may have ten.

Gain: Whoever raises the confirmation timeout is told that the CLI has to follow: with a longer timeout and the same wait, a second confirmation can run beside the first and screen every upload again. Comments only; no behaviour changes.

Docs: The dashboard comment names the timeout metric its percentile lines read, the one without dimensions

A comment on the dashboard widget for the timeout of timed-out approvals said that its three percentile lines add the per-rule metric up over all rules when the dashboard is drawn. CloudWatch does not add a custom metric up across dimensions. The lines read a second copy of each value, which the publisher writes without dimensions since an earlier commit of this branch, and the comment now says that.

Gain: The comment describes what the widget reads, as the test that ties the dashboard to the publisher checks it. It no longer suggests that the per-rule metric alone feeds the widget, the assumption under which, by the CloudWatch documentation, the widget could show no data. Comment only.

Test: cdk/test/handlers/approval-metrics-publisher.test.ts > 'every Cedar-HITL metric a widget reads is written with exactly those dimensions' (existing, unchanged: a comment has no test of its own)

Lean (delete): The orchestrator handler test no longer mocks a repository check that nothing calls

The handler test of the orchestrator replaces the repository settings module with a mock that listed a function, checkRepoOnboarded, which no product code calls any more: its last caller was changed earlier on this branch. The unused entry is deleted.

Gain: One dead line less in the test. A search for the function now finds only its definition, its own tests and comments, which is all that a later removal of the function has to touch. The suite passes with the same tests before and after.

Test: cdk/test/handlers/orchestrate-task.test.ts (the whole suite, unchanged: an unused mock entry has no test of its own; with cdk/test/handlers/start-session-composition.test.ts it passes with 140 tests before and after)

Lean (delete): The session start test no longer mocks a repository check that nothing calls

The test that composes the session start replaces the repository settings module with a mock that listed a function, checkRepoOnboarded, which no product code calls any more. The unused entry is deleted.

Gain: One dead line less in the test; the suite passes with the same tests before and after.

Test: cdk/test/handlers/start-session-composition.test.ts (the whole suite, unchanged: an unused mock entry has no test of its own; with cdk/test/handlers/orchestrate-task.test.ts it passes with 140 tests before and after)

Speed: Showing a registry asset fetches the versions of that asset, not every record of its kind and namespace

To show the versions of one registry asset, the API fetched every record of the same kind and namespace in full, one call after the other, and only then kept those with the right name. The registry client can leave out the records of other assets before it fetches them, which an earlier commit of this branch added for resolving and publishing. The show endpoint now passes the asset name as well. Its answer is the same for every content of the registry. One failure goes away with the calls that are no longer made: a record of another asset that cannot be fetched no longer turns the request into a 500.

Gain: bgagent registry show costs one GetRegistryRecord call per version of the asset instead of one per record of its kind and namespace: 2 instead of 5 in the new test (an asset with two versions beside three other assets). By the same count, an asset with one version in a namespace of 120 records costs 1 call instead of 120. The listing of the registry that comes first is unchanged (one call per 50 records). One line of product code.

Test: cdk/test/handlers/registry-show.test.ts (new) > 'registry-show handler over the registry adapter' > 'fetches the versions of the asset it shows, not the records of its neighbours'

Gate: cdk-nag checks five places again where a suppression covered no finding

Six suppressions of cdk-nag, the rule checker that the build runs over the synthesized stacks, covered no finding in any deployment profile, so each only switched a check off for whatever is added later. Three accepted in advance any wildcard permission on the VPC flow log role, on the AgentCore Memory role and on the Bedrock logging role. One accepted the dead-letter queue of the screenshot processor even if it stopped being one. One said that cdk-nag misreads the origin access control of the screenshot distribution, which the installed version does not. One named a Cognito rule, COG3, that the installed rule pack does not have. All six are removed.

Gain: The deployment tests of the build now fail on five mistakes they let through before: a wildcard permission added to one of the three roles, the screenshot processor losing its dead-letter queue, and the screenshot distribution losing its origin access control. Shown by planting each of the five in a copy of the code: all five pass while the suppressions are there, and each is reported once its own suppression is gone. Without the six the application is clean in all 132 profiles that the tests synthesize (1006 tests pass). 35 lines fewer. The synthesized templates of four profiles differ only in the suppression lists kept in resource metadata, and in the tag of the agent image, which changes whenever a file of its build context changes (the cdk sources are in it).

Test: cdk/test/synthesis/deployment.test.ts (existing, unchanged) > '<profile> deployment' > 'keeps every template within budget': its audit lists every cdk-nag error of the synthesized profile as a failure

docs: bring the design docs and guides in line with the changed code

Docs: The approval design gives the pending-list limit as 60 a minute and what a session scope adds to the allowlist

The design document of the approval gates still gave the limit of the pending-approvals list as 10 calls a minute, in seven places; this branch raised it to 60 for the operator console. It showed an approval with the scope tool_type_session being put into the agent's allowlist under that name, while the agent stores the tool of the approved call (for tool_group_session the group of that tool, and nothing when the tool is in no group). It named only the per-rule dimension of the timeout metric, which is now also published without dimensions because that is what the dashboard widget reads, and it described the secret scan of a deny reason without the bound of 20,000 characters it has now.

Gain: The design matches the code where a reader acts on it: the rate limit a client of the pending list can expect, what an approval scope covers afterwards, which metric the dashboard reads, and how much of a deny reason is scanned. 20 lines added and 16 removed in the document, no behaviour.

Test: No test: documentation. Each sentence was checked against the code; the docs link check and the Markdown structure lint pass.

Docs: The interaction design lists the failure hook and says that text attached to a tool result reaches the model

The appendix on the Claude Agent SDK said that the Stop hook is the only way to hand text to the model in the middle of a run, and that additional context returned by a hook after a tool call never reaches it; two more places of the document repeated that. With the pinned SDK and CLI such context does reach the model, attached to the tool result, and since this branch the advisory of the stuck guard relies on it. The list of hooks the agent registers lacked the hook for failed tool calls, which this branch added.

Gain: A maintainer who reads the appendix before changing the hooks no longer concludes that an advisory on a tool result is lost, and finds the hook for failed tool calls and what the two hooks after a tool call feed. The bullet for the Stop hook names the three functions it runs, in their order. Five statements corrected, no behaviour.

Test: No test: documentation. Each sentence was checked against the code; the docs link check and the Markdown structure lint pass.

Docs: The developer guide says that a dry run prints the length and a hash of the prompts, not the prompts

The developer guide said in two places that a dry run of the local agent prints the prompt. It prints the length and a hash of the system prompt and of the user prompt; this branch removed the hint to a switch for the full text, which did nothing. The guide also named the AWS CLI as the second source of credentials for the local run script. Since this branch the script takes that path only when the CLI is not version 1, which lacks the command, and goes on to the mounted AWS folder otherwise.

Gain: A developer who starts a dry run to read the prompt learns beforehand that it is not printed, and one with AWS CLI v1 knows which credential source applies to them. Three lines.

Test: No test: documentation. Each sentence was checked against the code; the docs link check and the Markdown structure lint pass.

Docs: The workflow design names the step events as emitted and says that a missing strategy counts as create

The workflow design said that the step runner reports each step with the events start and complete. The runner reports start and then succeeded, failed or skipped, and since this branch the pipeline reports the build and the pull-request step of a coding task itself, because the runner runs only the agent step there. Validation rule 4 did not say that a pull-request step without a strategy counts as create, which is why the validator of this branch rejects a read-only workflow with such a step.

Gain: Whoever builds on the step events (the console shows its stages from them) or writes a read-only workflow finds the names and the rule the code uses. Two sentences.

Test: No test: documentation. Each sentence was checked against the code; the docs link check and the Markdown structure lint pass.

Docs: The agent's contributor guide says that pragma comments no longer take code out of the coverage floor

The contributor guide of the agent did not say that coverage pragma comments have no effect there. Since this branch the coverage settings of the agent replace the two default lists of coverage.py that honour '# pragma: no cover' and '# pragma: no branch', so such a comment changes nothing. The guide now has the entry that the guides of cdk and cli already have for their ignore comments: test the code, or leave it counted as uncovered and say why in a plain comment.

Gain: A contributor, or a coding agent that reads this guide before it writes code, does not add a comment that silently does nothing, and learns which check and which test pin the setting. One list entry.

Test: No test: documentation. Each sentence was checked against the code; the docs link check and the Markdown structure lint pass.

Docs: The Linear guide matches the code on workspace removal, a re-applied epic label and the agent token warning

Four statements of the Linear setup guide no longer matched the code. It explained a log line of the token renewal that the agent no longer does; the agent now writes that the stored token is expiring and leaves the renewal to a Lambda. It said that remove-workspace only accepts active workspaces, while the command now also removes a workspace whose Linear grant died. It called re-applying the trigger label on an epic without new sub-issues a no-op, while that retries failed and skipped sub-issues and reads again the text of those that are not running and have not succeeded. And it said that a dead authorization is recorded and announced, which does not hold when a call to the Identity vault fails. One older gap is closed as well: re-running onboard-project without --label sets the trigger label back to the default, and the guide now says so where it tells operators to re-run the command.

Gain: An operator who follows the guide after a grant has died, a sub-issue was reworded or a mapping has to be registered again gets what the guide says, and the troubleshooting list names a log line the agent really writes. Five passages, no behaviour.

Test: No test: documentation. Each sentence was checked against the code; the docs link check and the Markdown structure lint pass.

Docs: The attachment design states the 30-second URL limit, the Slack limits and what a replayed create returns

The attachment design described three things the code does not do. For files on a Slack mention it gave 10 MB per file and an upload from the Slack function to storage; the processor hands the files to task creation as inline attachments, with 500 KB per file and 3 MB per message, and answers with other texts. For a create request that is sent again it described new attachment ids and storage keys; the API of this branch returns new upload forms for the same ids and keys. And it said that a text file is checked in its first 8 KB; the whole file is checked, since this branch for uploaded files too. The limit of 30 seconds for all URL attachments of a task, new in this branch, is added to the limits and to the fetch rules, and the sentence about git ignoring the attachment folder names the mechanism the agent uses since this branch.

Gain: The design reads as a description of the feature again: limits, reply texts and the behaviour of a retried request are the ones a user meets. 26 lines added and 25 removed.

Test: No test: documentation. Each sentence was checked against the code; the docs link check and the Markdown structure lint pass.

Docs: The API contract documents the replay of an upload task, a refused next_token and the confirm-uploads errors

The API contract lagged behind six changes of this branch. A create request that is sent again for a task that still waits for uploads now returns new upload instructions. A next_token that cannot be decoded is refused with 400. An image or file attachment that carries a url is refused. confirm-uploads fails the task when the uploads together exceed 50 MB, and answers ATTACHMENT_BLOCKED also for an upload that does not match its declared type or is no longer in storage. All URL attachments of a task share 30 seconds. And the redaction of a deny reason reads its first 20,000 characters.

Gain: A client written against the contract handles the answers the API gives: it uploads again after a replay, does not retry a size error that has already failed the task, and knows the time limit for linked files. Six sentences or table rows.

Test: No test: documentation. Each sentence was checked against the code; the docs link check and the Markdown structure lint pass.

Docs: The screenshot guide explains how a pull request's Linear issue is found and why a preview can stay on GitHub

The troubleshooting section for a screenshot that reaches GitHub but not Linear said that the usual cause is a pull request without an identifier in its title or body. Since this branch a pull request opened by a Linear task needs no identifier, and for any other pull request the branch name, the title and the body are searched in that order, going on only when no workspace has the earlier identifier. The section now says that, lists the two further reasons for no post (the identifier exists in two workspaces, a workspace could not be asked) and explains the log line for a branch that names a task of another repository. The lookup reason pr_not_linked now says that only pull requests of the repository itself count.

Gain: An operator who looks up the log line finds the causes that exist, including the one a renamed repository produces, and is no longer sent to look for an identifier that a Linear task does not need. One section and one table row.

Test: No test: documentation. Each sentence was checked against the code; the docs link check and the Markdown structure lint pass.

Docs: The Jira guide lists the question comment, the answer to a no-change request and the rule for cards in review

The Jira setup guide described three outcomes of a finished task. Since this branch there is a fourth comment, 'ABCA has a question before it starts', and the result of an @bgagent question that needed no change carries the agent's answer. The section on board transitions did not say that an issue which already has one of the listed review statuses, or In Progress, only moves forward along that list and that the fallback by status category is no longer used for it; a card In Progress on a board without one of the known review names now stays there until --status-on-pr is set. The guide also said that recent comments are filtered by the type of their author only, where the 100 newest are read and ABCA's own are also told by the marker they start with, and it called re-applying the label on a parent without a new subtask a no-op, where it now reads again the text of the subtasks that are not running and have not succeeded.

Gain: Users find all four comments with which ABCA ends a task on an issue, and a team whose board has its own name for the review column learns from the guide, not from a card that does not move, that it has to configure it. Four passages.

Test: No test: documentation. Each sentence was checked against the code; the docs link check and the Markdown structure lint pass.

Docs: The Slack guide says when a mention is answered 'not onboarded' and when it runs on the channel's default repo

The troubleshooting entry for 'Repository not onboarded' said only that the repository has to be registered. Since this branch the first word with a slash in a Slack mention is no longer taken for the repository when the channel has a default repository or the message names a repository for certain. In a channel with a default the answer comes only for a repository written with an issue number, or for one that has the owner of the repository the task would otherwise run on. Any other such word is read as text, and so are the parts of a pasted GitHub link, so the task normally starts on the default. The entry now says so, and points to the message that names the repository and to the button that cancels the task.

Gain: A user whose task started on the channel's default repository and not on the one they named finds the rule and the way to stop the task. One paragraph.

Test: No test: documentation. Each sentence was checked against the code; the docs link check and the Markdown structure lint pass.

fix(orchestration): refuse a fork's pull request before a session starts

Bug: A task on a pull request from a fork is refused before a session starts, with a reason of its own

A review or an iteration on a pull request that comes from a fork could not work: the agent fetches the branch of the pull request by its name from the task's repository, and the branch of a fork is not there. What the user got depended on the repository. If it had no branch of that name, the task started a compute session and failed in setup with a git error (couldn't find remote ref). If it had a branch of the same name, other than the default branch, which an earlier change of this pull request covers, the agent took that branch for the pull request: a review reported on code that is not the pull request's, and an iteration committed and pushed to the repository's own branch. The pre-flight check already asks GitHub for the pull request. It now reads from the same answer whether the branch is in another repository, and fails the task before a session starts. The user sees the reason PR_FROM_FORK with the text 'PR #42 in owner/repo comes from another repository (a fork): its branch is not in owner/repo, so it cannot be checked out or pushed to', the title 'Pull request from a fork', and the advice to open the pull request from a branch of the repository itself. The user guide lists the new reason.

Gain: An iteration can no longer push commits to a branch of the repository that only has the name of a fork's branch, and a review can no longer be about the wrong code. A pull request from a fork costs no compute session and no additional GitHub request, and the failure says what to do instead of showing a git error. 23 product lines for the check, 11 for its title and remedy.

Test: cdk/test/handlers/shared/preflight.test.ts > 'fails PR_FROM_FORK when the pull request comes from a fork', '... comes from a fork that was deleted since', '... has no head repository in the answer of GitHub', and 'passes a pull request of the repository itself when the task spells the repository in another letter case'; cdk/test/handlers/shared/error-classifier.test.ts > 'classifies a pull request from a fork'

Docs: Two code comments state the ECS poll rule and the registry list filters as they are now

Two code comments described behaviour that earlier changes of this pull request replaced. The comment on the MicroVM poll said that the ECS strategy reports a task as failed when ECS no longer returns it. Since the change that treats temporary ECS failures as temporary, the ECS strategy throws instead, which counts as one failed poll, and the task fails after three failed polls in a row. The comment on the list operation of the registry client named two filters, kind and namespace; the filter gained a third, the asset name, with the fix of registry publishing.

Gain: Both comments agree with the code again: a reader who compares the two compute strategies, or who looks for a way to list the versions of one asset, is not sent to a rule that no longer exists. Comments only, 7 lines changed, no behaviour.

Bug: A Jira preview is delivered when the blueprint spells the repository in another letter case than GitHub

After a preview deployment, the screenshot and the link are posted on the Jira issue of the task that opened the pull request. The screenshot processor decides without regard to letter case whether a task belongs to the deployed repository, because GitHub reports its own spelling of a name and a task carries the spelling of its blueprint. The Jira delivery then compared the two names exactly, in two places, and dropped the preview with the warning 'Deployment repository does not match the task', for the first deployment and for every later push, when the blueprint was written, say, Acme/App. Both comparisons now ignore letter case, as the processor does.

Gain: Jira issues of a repository whose blueprint differs from GitHub's spelling only in letter case get their preview comment, for the first deployment and for later pushes; before they got none, and only a warning in the log said so. A task of another repository on the same Jira issue is still left out, which a new test pins. Two comparisons changed and one small helper added; the complexity of the delivery function stays at 52.

Test: cdk/test/handlers/shared/jira-deployment-preview-repo-case.test.ts > 'a task whose blueprint spells the repository in another letter case gets its Jira preview', 'an iteration whose repository is spelled in another letter case gets the preview of its commit', 'an iteration of another repository on the same Jira issue is not taken for the deployed commit'

Lean (reuse): One private-address check guards both attachment downloads and refuses all of fe80::/10

Two functions decided whether a resolved address is private before an attachment is downloaded: one for links that a user submits, one for files uploaded to Linear. They had drifted apart. The one for user-supplied links refused link-local IPv6 addresses only when they began with fe80, so fea9::1, which is in the same range (fe80::/10), was accepted. The Linear one did not know the hexadecimal form of an IPv4-mapped address, such as ::ffff:a9fe:a9fe for the metadata address. There is now one function, used by both downloads, and it refuses every address that either of the two refused. On the Linear path it therefore refuses every IPv4-mapped address, also one that embeds a public address such as ::ffff:8.8.8.8, which the copy let through; for user-supplied links it also refuses the deprecated IPv4-compatible form (::8.8.8.8). A resolver writes an IPv4 address inside an IPv6 address only for these two forms, and neither is the address of a public host.

Gain: A link whose host resolves to a link-local address outside the fe80 prefix is refused now, and the address rule exists once instead of twice: 33 product lines fewer (114 removed, 81 added) and fifteen constants gone. Compared on 72,718 generated addresses, in the spellings a resolver writes and in others: none that either old function refused is accepted by the shared one. The two Linear tests for the mapped metadata address and for fea9::1 pass unchanged.

Test: cdk/test/handlers/shared/resolve-url-attachments.test.ts > 'isPrivateIp' > 'IPv6 private ranges' > 'blocks the whole of fe80::/10 (link-local), not only the fe80: prefix' and 'blocks an IPv6 address written with an IPv4 address inside, whatever it embeds'; unchanged: cdk/test/handlers/shared/linear-attachments.test.ts > the two tests tagged 'finding #8'

Test: A test pins that a failed S3 store of a Linear or Jira attachment fails with the answered error

When S3 refuses to store a screened attachment, the Linear and the Jira download have to fail with their own error, because that is the only error their webhook processors catch and answer on the issue, and its text must not carry the storage error. No test covered that step: with the conversion taken out of both modules, every existing test still passed. One new test file holds both modules to it. The two modules still carry this step twice; merging them into one is left for a separate change.

Gain: A change that lets a storage error escape as it is now fails two tests; it would have left the person who triggered the task without an answer on the issue. Tried against that change: the two new tests fail and the 66 existing tests of the two modules pass. Test only, 123 lines; no product line changed.

Test: cdk/test/handlers/shared/attachment-store-failure.test.ts > 'Linear: an attachment that S3 refuses to store is refused with the error the processor answers, and the S3 error stays in the log' and the same for 'Jira'

An epic that a comment re-opens more than a day after its sub-issues ended (an iteration on a sub-issue, then the re-stack onto its dependents) did not get the claim of the final status back when the final edit of the panel failed: the day was counted from the last write of a sub-issue's row, and a re-stack writes none. The parent then stayed In Progress under a panel that said complete. The day is now counted from the end of the epic or from its last re-open, whichever is later.

fix(cli): make bgagent list follow the page token of the API

Lean (delete): The event catch-up of the CLI client no longer takes a page size that its only caller never varied

The client call that bgagent watch uses to fetch the events it has not seen yet took an optional page size. Only watch calls it, and it always passed 100, the largest page the API returns, so the option could not change anything. The option is gone and the call asks for pages of 100 itself.

Gain: No change of behaviour. One parameter, its documentation line and the argument at the one call site are gone: 4 lines added and 5 removed in two product files. The page size is now checked where it is set. Only the tests of watch named the 100, and they no longer can; without a new check a client that asks for 10 events per request passed all 91 tests of the client and of watch. One assertion in the client's tests now fails for it.

Test: cli/test/api-client.test.ts > ApiClient > catchUpEvents > 'paginates internally across multiple next_token hops' (new assertion: every request of the catch-up carries limit=100)

Bug: bgagent platform doctor names --label in the onboard-project command it tells the operator to re-run

For Linear projects that were mapped before ABCA recorded which workspace owns them, bgagent platform doctor tells the operator to re-run bgagent linear onboard-project <uuid> --repo <owner/repo> for each of them. That command writes the whole mapping again and takes the default trigger label bgagent when --label is not given. An operator who followed the advice for a project that triggers on another label switched it back to the default, and issues carrying the project's own label stopped starting tasks, without any message. The command the doctor prints now carries --label <its trigger label>.

Gain: Following the doctor's advice no longer resets the trigger label of a project that has its own. The printed command now agrees with the Linear setup guide and with the operator console, which were corrected earlier in this pull request. One line of text and a comment; one assertion added to the existing test of that message.

Test: cli/test/platform-doctor.test.ts > 'warns and names the rows that record no owning workspace' (new assertion: the printed command carries --repo and --label)

bgagent list asked the API for one page and stopped. The API reads a bounded number of rows per request, applies the --status and --repo filters to what it read, returns at most 100 tasks, and expects the client to go on with the token it returns. So a list with a filter could come back short or empty while tasks that match existed: a user whose 300 newest tasks belong to other repositories was told 'No tasks found.' followed by '(More results available)' when asking for the repository of an older task; --limit 250 printed 100 tasks. The command now goes on with the token until it has the number of tasks asked for with --limit (20 without it), the list ends, or it has sent five requests. Gain: a filter finds tasks that lie behind the first page, and --limit works up to 500. A list that fits into one page still costs one request. What it costs: a list with a filter that finds fewer tasks than asked for sends up to five requests where it sent one (2 failed tasks among 1,000 others, or among 10,000: five requests each). How far it reaches: as far back as five requests read, which is 1,050 tasks with the default limit when nothing matches before and 5,050 with --limit 100, where the single request read 210 and 1,010. A task further back is still not found, and the command says '(More results available)' as it did; a larger --limit reaches further, up to those 5,050 tasks. The bound is five because the list of running tasks rarely fills a page: over a long history every call sends all five requests, and a call every two seconds then stays under the 1,000 requests in five minutes that the API allows one address. Checked with the command against the API's own list code over 39 table layouts and option sets, before and after: 21 show more tasks, 10 are unchanged, 8 show the same tasks after more requests; no task is listed twice or skipped, and none beyond --limit. Not one of the audit's findings: it was found while checking a proposal to delete the page token of the client's task list as unused; the token is now used, and a test pins it.

The loop that follows the API's page token stood three times, in bgagent list, bgagent webhook list and bgagent api-key list, each with its own two constants and nearly the same comment. It is one function now: it takes the first page, the number of rows asked for, a function that fetches the next page, and the most requests to send. The three commands call it, the task list with its bound of five, the two other lists with the 100 they had. No change of behaviour for those two: 44 runs of them against the API's own list code print the same and send the same requests before and after. Gain: the rule stands in one place, where a change to it is made once, and the four files are 16 lines shorter (55 added, 71 removed; 47 lines of code became 32). Two tests are new, one each for webhook list and api-key list: until now no test noticed a further request that dropped --include-revoked or repeated the token of the first page. The function stands with the output helpers and not next to the client, because the tests of the commands replace the client's module whole.

fix(agent): use the shared redactor in the server, drop deprecated calls

Docs: Comments on the session tags, the Linear token fixture and a nudge test match the code again

Three comments described code as it was before earlier changes of this branch. The comment and the docstring on the agent's session tags said the tags are set once at start-up from the resolved task configuration; since the change that records a start-up failure under the task's own tags, the pipeline sets them twice per task, first from its arguments as they came. A comment in the emulator test of the Linear token said the fixture's expiry keeps the agent from renewing the token against Linear; the agent no longer renews at all, and an expiring token yields no token. A comment in a test of the nudge hook named a helper that has since been merged into another one. The three texts now say what the code does.

Gain: The comments match the code: nobody takes the second call that sets the session tags for a mistake, or goes looking for a token renewal or a helper that no longer exists. No behaviour changes.

Lean (delete): The server no longer calls a function Python removes in 3.16, and the type check reports deprecated calls

The server printed the name of its event loop policy once when it was loaded, and a manual diagnostic script printed it too. Both asked asyncio for the policy with a function that Python deprecates from 3.14 and has announced to remove in 3.16. The printed value cannot vary: the image installs no other event loop and starts the server with the standard one. Both calls are deleted. With them goes the setting that switched the type checker's rule for deprecated calls off for the whole package, which existed only so that these two calls would pass.

Gain: On Python 3.14 or later, loading the server raised a deprecation warning, which the test suite treats as an error: the two test files that import the server, 245 tests, could not be collected (shown by simulating the 3.14 warning for that one call; the call itself was tried on Python 3.14.5), and once 3.16 removes the function the server would not start. 20 lines removed: 14 in the server, 2 in the script, 4 in the settings. The type check now fails on a call of any deprecated function, where one exemption written for two calls used to hide all of them: in a copy of the package a call of datetime.utcnow() passed before and is reported now.

Test: No new test (deletions). The two test files that import the server (245 tests) run with the Python 3.14 warning simulated for the deleted call; the diagnostic script run on Python 3.14.5 with warnings as errors; the type check over the package

Test: A test fails when the agent stops storing an iteration's outcome: code changed or not, answer, commit

When a task ends, the agent stores three values that the platform decides from afterwards: whether the run changed any code, the agent's answer when it changed none, and the commit the run ended on. The reply to a comment on a pull request, the resume of a task that asked a question, the epic reconciler and the preview-screenshot webhook read them. No test covered these three writes: with all three switched off, the 398 tests of the four files that can see what is written to the task record still passed. One test now checks them, including that 'no code changed' is stored as the value false and not left out, because the platform reads a missing value as 'updated'.

Gain: Three writes that could be removed or broken without any test noticing are pinned. The new test fails under each of five one-line changes tried on a copy: each write switched off, the false dropped because it is falsy, and the flag stored as text. Dropping the false is the realistic slip: a question that was answered without a code change would be reported as 'Updated'. Test only: 30 lines, no production change.

Test: agent/tests/test_task_state.py > TestWriteTerminalIterationOutcome::test_answer_of_a_run_that_changed_nothing_is_written

Docs: The comment on the attachment download says what the workspace is for a task without a repository

The agent downloads a task's attachments into a folder of its workspace and, when that workspace is a repository clone, lists the folder in the clone's local exclude file, so that the uploads cannot end up in the pull request. The comment there said the workspace is always the clone. Since tasks without a repository get their attachments too, the function is also called with a directory that is no clone (the task's own directory under the agent workspace), where the entry is skipped. The comment and the description of the argument now say both.

Gain: The comment matches the two callers: a reader no longer concludes that the download is only for tasks with a repository, or that the missing exclude entry of a task without one is a defect. A change of wording only; tests already run both cases.

Test: No new test (a comment). Both cases it names are run by agent/tests/test_attachments.py > TestDownloadAttachments::test_downloads_are_not_picked_up_by_git and agent/tests/test_pipeline.py > TestRepoLessPipeline::test_repoless_task_gets_its_attachments

Risk: The server's own log lines pass through the agent's one redactor instead of a second, narrower copy

The server kept a small redactor of its own for its debug and warning lines, which also carry exception texts and pieces of the request it was sent. It replaced the exact values of four credentials held in the environment and nothing else. The redactor that every other log line of the agent passes through also knows a fifth variable (GH_TOKEN) and recognises GitHub tokens, Authorization headers and token parameters of URLs by their shape. The server's copy is deleted and its three log paths use the shared redactor. In an ordinary line the only difference is the marker: *** where it used to name the variable that was redacted.

Gain: One redactor instead of two, and 18 lines fewer in the server. A credential added to the shared list is covered in the server's lines as well from now on; the two lists had already drifted apart by one variable. A GitHub token that the process does not hold itself, for example the token of another installation inside an error text, is no longer written to stdout and to the server's CloudWatch streams as it came. The server's redaction had no test: 18 cases now cover its three log paths, 6 of which fail against the old copy.

Test: agent/tests/test_server_redaction.py > TestServerLogLinesAreRedacted::test_value_of_a_credential_the_process_holds (5 variables in 3 log paths), ::test_github_token_the_process_does_not_hold (3 log paths)

Gate: Three coverage-ignore comments that have no effect in the agent are removed

Three lines, in the gateway tool bridge and in the policy engine, carried a '# pragma: no cover' comment. In the agent the comment has no effect since the coverage settings stopped honouring it: the lines are measured, and counted as not covered, with or without it. The three comments are removed; where the words after the marker explain the line, they stay as a plain comment.

Gain: A reader no longer takes these lines for code that is left out of the coverage floor. Measured on a copy of the package with and without the comments: the same statements, the same excluded lines and the same missing lines in both files. No behaviour changes. The agent's source holds no such comment any more.

Test: No new test (comments). Coverage of the two files measured with and without them on a copy: identical

Test: Two emulator tests check that updated_at moves with the status the agent writes

Since an earlier change of this branch the agent sets updated_at together with the status when it ends a task and when it pauses one for an approval. Unit tests compare the text of the update it sends; the two emulator tests that run those updates against a DynamoDB interface did not look at updated_at. Each gets one assertion on the stored record: after the terminal write updated_at equals completed_at, and after an approval request it is the moment that the status timestamp carries.

Gain: If the stamp is dropped from one of the two writes, or written with another value than the moment in the status timestamp (a stale one, another format), the emulator tier fails; until now only the unit tests that compare the text of the update would notice. A second reading of the clock inside the same write is not told apart: the stamps have a resolution of one second. Two assertions (four lines with their comments), no production change.

Test: agent/tests_emulator/test_scoped_session.py > TestScopedCredentials::test_agent_writes_its_own_events_trace_and_task_record and agent/tests_emulator/test_approval_transactions.py > TestApprovalRequest::test_pending_row_and_awaiting_status_are_written_together (emulator tier)

Files that a user attaches to a task are downloaded into a folder inside the repository clone, and since an earlier change of this branch the agent lists that folder in the clone's local exclude file, so that the uploads cannot be committed. It appended the entry without a line break in front of it. In a clone whose exclude file does not end with a line break, the entry was glued onto the last line (*.swp became *.swp/.attachments/): the clone's own pattern stopped matching and the folder was not ignored, so a broad 'git add' would have taken the task's attachments into the pull request. The entry is now written behind a line break, as the registry loader writes its own. Gain: the uploads stay out of the pull request whatever the last line of the exclude file looks like. One test builds such a clone and asks git about both patterns; it fails without the change.

test(registry): add six cases to the two-language parity corpora

Test: The shared resolver corpus holds an exact pin beside its leading-zero twin and two identifiers from 2^53 on

The ranking corpus is the list of version-selection cases that the TypeScript and the Python resolver must both answer the same way. It had no case for two defects this branch fixed: an exact pin such as 1.0.0-rc.1 also matched a version published as 1.0.0-rc.01, and the TypeScript resolver could not tell two numeric prerelease identifiers above 2^53 apart. Both are cases of the corpus now.

Gain: Two more cases that both languages run from one file. The first fails on the code before the fix in both languages, the second in TypeScript, and none of the twelve existing cases failed there. A later change that brings either defect back in one language now fails that language's corpus test.

Test: agent/tests/test_registry_resolution_ranking_corpus.py > test_select_highest_matches_fixture[exact-pin-ignores-a-leading-zero-twin] and [numeric-prerelease-above-max-safe-integer]; cdk/test/handlers/shared/registry-resolution-ranking-parity.test.ts > 'exact-pin-ignores-a-leading-zero-twin' and 'numeric-prerelease-above-max-safe-integer'

Test: The shared resolver corpus holds a candidate version written with a digit from another script

The Python resolver used to read a version written with a digit from another script (1.1 followed by an Arabic-Indic 2) as 1.12.0 and could pick it; the TypeScript resolver skips it because it is not a version. The fix made Python skip it too, but the corpus that both resolvers run had no such candidate. It has one now: the candidate is skipped and 1.0.0 wins.

Gain: One more case that both languages run from one file. It fails on the Python code before the fix, where the misread version won, and it is the first case of the corpus with a candidate that is not a version at all.

Test: agent/tests/test_registry_resolution_ranking_corpus.py > test_select_highest_matches_fixture[non-ascii-digit-candidate-skipped]; cdk/test/handlers/shared/registry-resolution-ranking-parity.test.ts > 'non-ascii-digit-candidate-skipped'

Test: The shared grammar corpus holds a digit from another script and two more line terminators at the end of a ref

The grammar corpus is the list of registry references that the TypeScript and the Python parser must both judge the same way. The Python parser used to accept a digit from another script in a version, and gave a reference that ends in a carriage return or a line separator a different error reason than the TypeScript parser. The fix aligned Python, but the corpus only had the line-feed case. The three inputs are cases of the corpus now.

Gain: Three more cases that both languages run from one file. All three fail on the Python code before the fix, and none of the twenty existing cases did. The corpus had one line terminator at the end of a reference (line feed) and now has three.

Test: agent/tests/test_registry_resolution_corpus.py > test_parse_matches_fixture[non-ascii-digit-rejected], [trailing-carriage-return-rejected] and [trailing-line-separator-rejected]; cdk/test/handlers/shared/registry-resolution-parity.test.ts > the three tests of the same names

fix(console): word the last step of a task by what that step does

Bug: The console's activity feed says 'Opening a pull request' only for a task that opens one

While a task runs, the console's activity feed announced the last step of every task as 'Opening a pull request'. That is true for a new coding task only: an iteration, a review and a restack work on a pull request that exists already, and a task without a repository has none. A task without a repository showed the line all along; the other three show it since this branch, in which the agent started to report the beginning of that step for every coding task. The feed now words the step by its name: 'Opening a pull request' for a new task, 'Finishing up on the pull request' for a task that returns to an existing one, and 'Delivering the result' for a task without a repository.

Gain: While the last step of an iteration, a review or a restack runs, the feed no longer announces a new pull request, and the feed of a task without a repository no longer mentions one. 6 lines of code and one test with three cases; the line of a new coding task is unchanged.

Test: web/test/core/util/activity.test.ts > describeEvent > 'words the start of the last step by what that step does'

Bug: The console's raw event list labels an agent turn 'Turn N', the number of the model's answer

In the console's raw event list an agent turn without text was labelled 'Message N', from the time when the agent numbered every message of the model. The agent now numbers the model's answers, which is what the turn limit counts, and the messages of one answer carry the same number, so the list could show 'Message 1' several times in a row. The label is now 'Turn N', the number that bgagent watch prints as 'Turn #N'.

Gain: The raw event list and the CLI show the same number under the same word, and the list no longer calls the number of an answer a message number. One label with its comment; the test follows it.

Test: web/test/core/util/events.test.ts > summarizeEvent > 'reads the same fields as the CLI status view'

Test: The test of the console's raw event list expects 'Turn 7' for an agent turn without text

The test of the console's raw event list expected the old label, 'Message 7', for an agent turn without text. It now expects 'Turn 7', the label the list shows since the agent numbers the model's answers instead of its messages.

Gain: The new label is pinned: with the old label put back, the test fails.

Test: web/test/core/util/events.test.ts > summarizeEvent > 'reads the same fields as the CLI status view'

Bug: The console's API types say that a Linear issue reported as with the agent can come without a task

The console's copy of the API types said of a Linear issue that is with the agent only that its task id is missing when the task belongs to someone else. Since this branch the API also reports in that shape a labeled issue that has no task of its own, an epic or an issue whose start was refused, once it is no longer starting: without a task id, a status or a pull request. The comment on the type now says so. The type itself is unchanged.

Gain: A developer who reads the type no longer concludes that an issue with the agent always has a task behind it. A comment only: nothing changes at run time, and the check that compares the console's types with the API's still passes.

Test: No test: a comment. The shape it describes is pinned on the API side by cdk/test/handlers/console-linear.test.ts > 'stops calling a labeled issue starting once its webhook can no longer be on the way' (run again: proof-4.txt).

refactor(cdk): one pull request number rule, drop unused channel ops

Lean (reuse): One function reads a task's pull request number; the three other copies are gone

Four places worked out a task's pull request number from its record, each with its own copy of the rule: the Linear comment path, the Jira comment path, the reply that closes a comment-triggered run, and the reader used when dependent work is rebuilt. They agreed for every record the platform writes and differed only for values that are no pull request number. There is now one function, the strictest of the four, and all four places call it.

Gain: 17 lines of product code removed (33 added, 50 removed in six files). A change to the rule is made once instead of four times. The cases of the two deleted copies are kept as tests of the shared function.

Test: cdk/test/handlers/shared/task-pr-number.test.ts > describe 'prNumberFromTask' (12 cases: the 6 of the two deleted copies and 6 where the copies differed)

Lean (delete): The Linear adapter no longer carries two channel operations that nothing calls

The Linear adapter of the orchestration channel implemented two operations, one that deleted interim notes from an issue thread and one that read the sub-issue graph, and no code ever called either. The graph is read through a separate graph source. Both implementations and the three imports only they used are removed.

Gain: 29 lines removed from the adapter (3 added, 32 removed). No behaviour changes: neither operation had a caller.

Test: No new test. Suites run after the change: orchestration-channel, orchestration-channel-slack, orchestration-channel-factory, linear-feedback, orchestration-rollup and both processors (in the 258 and 800 tests of commands).

Lean (delete): The function that swept interim notes off a Linear thread is deleted with its query

A function fetched the comments of a Linear issue and deleted the notes of the bot by their prefix. Its only caller was the channel operation that nothing called, so it could never run. It is deleted with the query and the prefix list that only it used; deleting a single comment, which the Linear processor uses, stays.

Gain: 71 lines removed from the Linear feedback module (1 added, 72 removed).

Test: No new test. Suites run after the change: orchestration-channel, orchestration-channel-slack, orchestration-channel-factory, linear-feedback, orchestration-rollup and both processors (in the 258 and 800 tests of commands).

Lean (delete): The five tests of the deleted note sweep are removed with it

The five tests of the function that swept interim notes off a Linear thread tested code that production never reached. They are removed together with the function and its import in the test file.

Gain: 71 lines of tests removed; the 5 tests covered only the deleted function.

Test: No new test. cdk/test/handlers/shared/linear-feedback.test.ts passes without the describe.

Docs: Comments of the Jira and Slack adapters no longer list two operations that do not exist

Comments in the Jira and the Slack adapter of the orchestration channel named the note sweep and the graph read among the operations the adapter leaves out. With both operations gone from the interface the comments named things that do not exist; they now list only the operations the interface has.

Gain: Two comments match the interface again (3 lines added, 11 removed).

Lean (delete): The channel interface and its design document describe only the operations that are used

The channel interface declared the two unused operations and a type for a node of the sub-issue graph, and the design document listed them in five places. They are removed from the interface, from the tests that checked their presence or absence, and from the document, which now says that the sub-issue graph is read through a graph source per tracker.

Gain: 29 lines removed from the interface (6 added, 35 removed), 54 lines of tests removed (4 tests, two list entries, two assertions), and the design document no longer names the two operations.

Test: No new test. Suites run after the change: orchestration-channel, orchestration-channel-slack, orchestration-channel-factory, linear-feedback, orchestration-rollup and both processors (in the 258 and 800 tests of commands).

Bug: A stored number that is no pull request number reads as no pull request in all four readers

Three of the four copies of the pull request number rule did not check the number they found. A stored 0, a negative or a fractional number, or a number in the link that is too large to be exact, was handed on as a pull request number: an iteration or a rebuild of dependent work was then asked for, and task creation refused it, or failed on it, one step later; a reply could name a pull request that does not exist. With the one shared rule each of the four readers answers that the task has no pull request, or takes the number from the pull request link when there is one.

Gain: No record the platform writes is read differently: a pull request number is stored only after it was checked to be a positive integer. What is gained is that the four readers can no longer disagree; 13 test cases pin the rule, 6 of them new.

Test: cdk/test/handlers/shared/task-pr-number.test.ts > 'reports ABSENT when pr_number is not a PR number (0) and there is no pr_url', and the table 'returns null for %s' of describe 'prNumberFromTask'

@krokoko

krokoko commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor Author

Follow-up changes in neighbouring files, and documents brought in line (part 2 of 2): what changes and what it gains

chore(cdk): drop two dead cdk-nag suppressions, correct stale comments

Docs: Two comments and a test title say what the code does (issue list time limit, queued task, timed-out command)

Three texts did not match the code. The comment on the timeout of the console's issue list function said that it covers one GitHub call with a time limit of 8 seconds. Since an earlier commit of this branch the function reads up to three pages from GitHub under one limit of 8 seconds for all of them, and the comment now says so. The title of a test of the Jira notice for a task that waits at the concurrency limit spoke of a rejection path. A task is queued there, not rejected, and the title now names the admission step, as the title of the Linear twin of that test and the description of the function already do. A comment that an earlier commit of this branch added to the test for a command that timed out said that no build ran. That is not what the test is about, and for one of its three cases, a push, it need not be so: the agent pushes after its build check. The comment now says that the command that timed out is not a build.

Gain: The three texts say what the code does. A reader of the console stack learns that the 15 seconds of the issue list function hold up to three GitHub calls that share 8 seconds, not one call. Comments and a test title only: no behaviour changes and no assertion changes, and the two test suites pass with the same 132 tests.

Test: No new test (comments and a title). cdk/test/handlers/orchestrate-task-feedback.test.ts > 'notifyJiraOnConcurrencyCap' > 'reportIssueFailure rejection is swallowed (never blocks the admission step)' is the renamed test, body unchanged.

Lean (delete): cdk-nag now checks the origin access control of the consent page and console distributions

cdk-nag is the rule checker that the build runs over the synthesized stacks. Two CloudFront distributions, the one of the Linear consent page and the one of the operator console, each carried an entry that switched off its rule AwsSolutions-CFR7, which reports an S3 origin without origin access control. The reason given was that cdk-nag misreads the construct that sets up the origin access control. The installed version does not: with the entry gone the rule finds both distributions compliant. The entries covered no finding and only kept the rule from reporting a real one later. Both are removed.

Gain: The build now fails when one of these two distributions gets an origin on a bucket of its own stack without origin access control; the rule does not see an origin on a bucket that is defined elsewhere. Shown on a copy of the code: with a second S3 origin without origin access control added beside the existing one, the deployment test of the consent page, its construct tests and the console suite all passed while the entry was there; without the entry the deployment test and the cdk-nag test of the console stack fail with AwsSolutions-CFR7. When the only origin loses its origin access control, a test that counts the origin access controls failed already; cdk-nag now reports that case as well. Without the entries the checks pass on the code as it is: one deployment profile with the consent page (7 tests) and the console suite (22 tests). 5 lines fewer. In the synthesized templates the suppression lists in the metadata of four resources change (the two distributions and their origin access controls), and with them the address of the nested consent page template, which carries a hash of its content, and the tag of the agent image, which changes with every change of the cdk sources. No property of a distribution changes.

Test: Existing, unchanged: cdk/test/synthesis/deployment.test.ts > 'agentcore-gw0-reg0-vault1-none deployment' > 'keeps every template within budget' (its audit lists every cdk-nag error of the profile); cdk/test/stacks/console.test.ts > 'OperatorConsoleStack' > 'has no unsuppressed cdk-nag errors'.

The console's issue picker asks GitHub for a repository's open issues with one time limit of 8 seconds for all pages. The handler read the body of each page outside the block that answers "GitHub did not answer. Try again in a moment." (503). A request counts as answered when its headers arrive, so the limit could end while a body was still arriving: reading it then failed, and the user got 500 "Could not list issues." with an error line in the log, where a slow GitHub should give the 503 that says to try again. The body is now read inside that block. A 200 answer whose body is not JSON gets the same 503. Gain: a slow GitHub is reported as such in this case too; 4 lines added and 1 removed, one test that failed before (500 where 503 is expected).

fix(agent): fail a task whose pinned MCP server the CLI would skip

Bug: A pinned MCP server with a field of a type the Claude Code CLI refuses fails the task before it starts

A Blueprint can pin MCP servers from the registry, and the agent writes each one into the MCP configuration of the session. The Claude Code CLI validates every entry of that file and skips a server whose headers or environment hold a value that is not a string, whose arguments are not a list of strings, or whose URL or command is not a string; the session then starts without it. A pinned server of such a shape, for example one with the header X-Shard set to the number 3, was written as it was, so the task ran without the server while the task record listed it as loaded. The agent now checks these fields when it loads a pinned server, and the task fails before the agent starts, with an error that names the server, the field and what the field has to be.

Gain: Bug fixed for every task of a Blueprint that pins such a server: the operator gets a failed task that names the server and the field, and such a task no longer runs to its end without the server while its record lists it. Of 28 runtime shapes tried, the agent now refuses exactly the 20 that the CLI skips and loads the 8 it keeps; among those 8 is a server with a wrong-shaped field that its transport does not use, which the CLI ignores. The rule was read in the CLI that the pinned SDK bundles (2.1.319), and that CLI's own claude mcp list was then run on a file that holds the 28 shapes as the old loader wrote them, with the network shut off: it lists the 8 and reports the 20 as skipped, the example with 'headers.X-Shard: expected string, received number'. A session was not run: that it starts without a skipped server is read in the CLI. 16 lines of code in one module and 17 test cases; every refusal was seen failing first, and 18 deliberate breakages of the check each fail a test.

Test: agent/tests/test_registry_loader.py > TestApplyMcpAssets::test_field_of_a_shape_the_cli_refuses_raises (11 rows), ::test_string_headers_args_and_env_load, ::test_field_the_transport_does_not_use_is_not_checked (2 rows)

Docs: Two registry test docstrings name the cases that the two-language parity corpora hold by now

Two Python test files of the registry said in their docstrings that the shared corpora, the case lists that the TypeScript and the Python code both run, hold none of the cases of these files. Since six cases were added to the corpora earlier in this pull request, three cases of each file are in them, and both docstrings now name those three. One docstring also said that every case has a TypeScript twin in a named test file; one case has none, so it now says that most have one.

Gain: The two docstrings match the corpora again, checked case by case against both corpus files. The answers the Python tests expect were also asked of the TypeScript parser and resolver: 11 of 11 the same. Comments only: 9 lines added, 5 removed, no test changes.

Test: none: two module docstrings. tests/test_registry_resolver.py and tests/test_registry_ref.py pass unchanged (11 cases).

Lean (delete): The runner's comment no longer promises a missing-SDK fallback that the clarification tool does not have

A comment in the agent's runner said that the clarification tool is simply not offered when the Claude Agent SDK is missing. The function that builds the tool lost that fallback earlier in this pull request and imports the SDK without a guard, so the sentence was untrue. It is deleted.

Gain: One untrue sentence less: two comment lines become one. Nothing changes at run time.

Test: none: a comment. tests/test_runner.py and tests/test_clarification_tool.py pass unchanged.

Bug: The timed-out approval event's docstring says the publisher also emits its timeout without dimensions

The docstring of the event the agent writes when an approval times out describes what the metrics publisher does with it: it emits the timeout as a metric with the rule as its dimension. Since an earlier change of this pull request the publisher emits the value a second time without dimensions, which is the metric the dashboard's percentile lines read. The docstring now says so.

Gain: The agent's description of the publisher matches the publisher, checked against its code and against the three places where the dashboard reads the metric. Comment only: 3 lines added, 1 removed.

Test: none: one sentence of a docstring. Checked against cdk/src/handlers/shared/approval-metrics.ts lines 348 to 370 and cdk/src/constructs/task-dashboard.ts lines 474 to 494; agent/tests/test_progress_writer.py passes (99).

The publish endpoint of the registry accepted the same shapes: for an MCP server it checked that headers is an object and nothing about its values, and did not look at args at all, although its own contract type gives headers as strings by name and args as a list of strings. A publisher could therefore publish an asset that every task which pins it would refuse. The endpoint now answers 400 for a header value that is not a string and for args that is not a list of strings, with a message that names the field, so the publisher hears it at the publish call. A publish with such a field that was accepted before gets a 400 now. Eight refusals and five accepted shapes are tested; the eight were seen failing first (201 where 400 is expected).

docs: say what a request without a workflow runs, list the fork reason

Docs: The registry design says that an MCP server with 'linear' in its key or settings cannot be loaded

A Blueprint can pin MCP servers from the registry. The agent removes every MCP server whose name or connection settings contain the word linear, the rule that keeps Linear tools away from it, and since this branch a task whose pinned server is removed that way fails before the agent starts. The registry design did not mention the rule. It now states it where it describes how MCP servers from the registry are loaded, with a link to the decision behind it.

Gain: Whoever publishes or pins an MCP server reads in the design, before a task fails, that a server with 'linear' in its namespace, name or connection settings cannot be loaded. One sentence added, no behaviour.

Test: No test: documentation. Each sentence was checked against the code; the link check and the Markdown structure lint pass.

Docs: The Jira guide says what a subtask added after a failure builds on

The Jira guide said that a subtask added later to a parent, without a blocker of its own, stacks on the last step of the work done so far. Since this branch a subtask that failed or was skipped is not such a last step, and neither is work that still waits behind it: the new subtask builds on what is left, or starts from the default branch of the repository when nothing is left. The guide now says so.

Gain: A user who adds a subtask after a failure, usually to supply what the failed one lacked, reads in the guide what it will build on. One sentence added, no behaviour.

Test: No test: documentation. Each sentence was checked against the code; the link check and the Markdown structure lint pass.

Docs: The user guide says what a request without a workflow runs and corrects five commands and limits

The user guide named the repository's Blueprint default as the first fallback for a request without a workflow, in two places, and said that the CLI leaves the choice to the server when no workflow is given. Neither is so: no Blueprint default for workflows exists, and the CLI always names a workflow itself. A REST or webhook request without a workflow gets the fallback workflow, which needs a description, while the table of request fields listed an issue number or a description as enough; such a request with an issue number alone is refused. The guide now says all of that, and which workflow to name for a task that ends in a pull request. Five more statements follow the code: the trace is downloaded already decompressed (the example piped it through gunzip, which fails), the example pre-approval is quoted because zsh refuses the bare pattern, the tool group is called file_write, a pre-approval can be given 20 times, and local attachments are sent inline only up to 3 MB in total.

Gain: A user who builds a request from the table of request fields learns which workflow to name for a coding task, instead of getting a 400 for an issue number or a task on the fallback workflow. Three things of the guide no longer fail as written: the jq example for a trace, which gunzip refused, the pre-approval example, which zsh refused, and the name of the tool group, where the API refuses file-write and accepts tool_group:file_write. 9 lines changed, no behaviour.

Test: No test: documentation. Each sentence was checked against the code; the link check and the Markdown structure lint pass. The two tests that read this guide pass (19 tests).

Docs: The API contract lists PR_FROM_FORK; the attachment design gives the upload rules of the CLI and Slack

Three design documents lagged behind the code. The API contract did not list PR_FROM_FORK, the reason a task fails with since this branch when its pull request comes from a fork, and it did not say that the pre-flight reasons of its error table are never the answer to a request: they arrive on the failed task and on its event. The orchestrator design did not name the fork check among the pre-flight checks. The attachment design gave the CLI's rule for local files without the limit of 3 MB for inline files that this branch added, and named the file content beside the extension as the source of the file type, where the CLI uses the extension alone. In its Slack section, which this pull request rewrites, the order is the processor's: it counts the files first, then checks and downloads them one by one.

Gain: A client author finds the fork reason in the contract and reads that the pre-flight reasons arrive on the failed task and its event, not as an HTTP error. The attachment design gives the limits and the order that the CLI and the Slack processor use. 7 lines added and 4 removed in three documents, no behaviour.

Test: No test: documentation. Each sentence was checked against the code; the link check and the Markdown structure lint pass.

Docs: The contributor guides name the type check's rule for deprecated calls and the coverage pragmas without effect

Two contributor documents missed rules of this branch. Since the exemption for deprecated calls was removed from the settings of the agent's type check, that check fails on any call of a function that the standard library, a dependency or the package itself marks as deprecated; the agent's guide for contributors now has an entry for it, with the fix: replace the call. The contribution guide named the coverage-ignore comments that ESLint rejects in the TypeScript packages; it now adds that the two coverage pragmas of Python have no effect in the agent.

Gain: A contributor, or a coding agent that reads these guides before it writes code, knows why the type check fails on a deprecated call and what to do, and does not add a coverage pragma that silently does nothing. One entry and one clause added, no behaviour.

Test: No test: documentation. Each sentence was checked against the code; the link check and the Markdown structure lint pass.

@krokoko

krokoko commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor Author

Constructs, quality gates, docs and web console: what changes and what it gains

chore(tooling): close a lint bypass in cdk, drop 15 duplicate rules

Gate: A stray ESLint configuration file below cdk can no longer take files out of the cdk lint tasks

ESLint 10 looks for its configuration file from the directory of each file it checks, so a configuration file in a subdirectory (a copied directory or a generated scaffold can bring one along) replaced the package's rules for everything below it while the lint task stayed green. Planted beside a file full of findings, an empty one made the lint commands of cdk, cli and web exit 0 with no output. The two cdk lint tasks now name the package's configuration file, which then applies to every file, and a test fails if a task loses the flag. The cli and web tasks had the same hole; their four lines are in files outside this change and follow in a later commit of this pull request.

Gain: A stray configuration file below cdk can no longer take files out of lint: the same plant now fails the task with the 13 findings of the planted file. The task lints the same 515 files with and without the flag and stays green on the tree. Two command lines and one test.

Test: cdk/test/eslint-config.test.ts > 'the eslint tasks of %s name eslint.config.mjs'

Lean (delete): Fifteen deprecated ESLint core formatting rules that cdk and cli ran twice are deleted (39 lines fewer)

cdk and cli ran seventeen formatting rules twice: the ESLint core rule, which ESLint has deprecated and removes in version 11, and the copy of it that the stylistic plugin maintains. A double-quoted string or a missing semicolon was reported twice, and an exception had to be written twice. Fifteen of the core rules are deleted; the one stricter option that only a core rule had (at most one blank line) moves to the plugin's rule. A second setting went with the deleted rules, the exceptions of the rule against double spaces; a later commit of this pull request puts it back on the plugin's rule. Two core rules stay on beside their copies, because each copy leaves checks out: the space in catch (, and the space after the comma of an array hole such as [, second] (that copy also skips the trailing comma of a type parameter list). A row for each of the two in the config tests fails if one is later deleted as a duplicate.

Gain: One report per formatting violation instead of two (a planted file goes from 20 reported problems to 13), 39 fewer lines of lint configuration in two files, and fifteen fewer rules to replace when ESLint 11 drops them. Nothing that cdk or cli contains today is checked less: each rule was compared with its copy on about 7,100 files (the packages' own TypeScript as it is and deformed, plus TypeScript and JavaScript of the installed packages), under the configured options and two inverted sets. The copy reported everything the core rule did, except in the two rules that were kept for that reason and in two spellings that neither package has: the space before the closing brace of an optional destructured parameter ({ a} ?: T, which only a signature without a body can have), and export default interface, where the core rule asked for a semicolon that no spelling could supply.

Test: cdk/test/eslint-config.test.ts and cli/test/eslint-config.test.ts > 'eslint.config.mjs reports each snippet with exactly the rules listed' (the rows for keyword-spacing and comma-spacing); the lint tasks of cdk and cli stay at exit 0

fix(cdk): deliver nudges on ECS, correct pass rates, redact keys in WAF

Bug: The Build and Lint Pass Rate widgets leave out a task that reports no build or lint result

The dashboard's Build Pass Rate and Lint Pass Rate widgets counted every task that has no build or lint result as a failed run. The agent reports no result (null) for a task without a repository, for a task that crashed and for a build whose command could not run, and the two queries read that null as a value. The queries now pick up only true and false, so a task without a result is left out of both rates.

Gain: A task that reports no build or lint result no longer lowers either rate. With the lines the real metrics emitter writes (the query text applied in a script, not run against CloudWatch), nine completed tasks plus three crashed ones read 75 percent on both widgets before and 100 percent now; with a tenth task whose build and lint both failed they read 90 percent. A deployment that runs only tasks without a repository showed 0 percent and now shows no data. This matters more since crashed tasks started to emit a metrics event on this branch.

Test: cdk/test/constructs/task-dashboard.test.ts > 'build and lint pass rates' > 'Build Pass Rate (24h) counts a task without a verdict neither as passed nor as failed' and the same test for 'Lint Pass Rate (24h)'

Bug: A nudge sent with bgagent nudge reaches a task that runs on the ECS backend instead of expiring unread

On the ECS backend a nudge was accepted and never delivered. The command bgagent nudge answered 202 and stored the message, but the Fargate container was never given the name of the nudges table, so the agent's nudge reader switched itself off and the message expired unread, without any error for the user. The two ECS task definitions now get the table name, as the AgentCore runtime and the Lambda MicroVM already did.

Gain: Nudges reach tasks that run on ECS; before, every nudge to such a task was lost while the CLI reported success. The fix adds nothing else to the deployed stack: the per-task session role already let the agent read and mark its own nudges, and for this fix the synthesized ECS template differs only by this one variable in each task definition and by the container image tag, which changes with any change to a source file (no IAM change).

Test: cdk/test/stacks/agent.test.ts > 'AgentStack with the ECS substrate gate (--context compute_type=ecs)' > 'both ECS task definitions name the nudges table, so a nudge reaches an ECS agent'; cdk/test/constructs/ecs-agent-cluster.test.ts > 'EcsAgentCluster nudges table' (4 tests)

Risk: The web firewall stores REDACTED in place of the Authorization and X-API-Key values in its request samples

The web firewall in front of the API keeps a sample of the requests it sees, with the name and value of every header, for three hours, and whoever may read WAF data in the AWS account can list them. The samples held the Authorization header (a Cognito token, accepted for up to an hour by every route that authenticates a user) and the X-API-Key header (a platform API key, valid until someone revokes it unless it was created with an expiry date) in clear, although the platform itself stores only a hash of the key. The firewall now writes REDACTED in place of these two values in what it stores; its rules still inspect the real request.

Gain: A principal with read-only access to WAF (GetSampledRequests is a read action) can no longer take a working API key or session token out of the samples. Sampling stays on, so blocked requests can still be inspected. It is one property on the existing web ACL: no new resource, no new deploy permission, and nothing for it on the WAF price list.

Test: cdk/test/constructs/task-api.test.ts > 'TaskApi construct' > 'WAF replaces the two credential headers in the request samples it keeps'

Two comments in the stack still described the concurrency cap as rejecting a task and the Linear notice as a comment plus a failure mark; they now say what the orchestrator does: it queues the task and posts a comment. Comments only.

fix(hydration): sanitize a text in time proportional to its length

Scale: Sanitizing a text takes time proportional to its length, so one long comment cannot hold up a task's start

The content sanitizer removes HTML tags from issue, pull request and comment text before an agent sees it, in two rounds (first the tags that are removed with their content, then the others). For some texts its time was more than proportional to the length (it grew with the square or the cube), so one long comment could keep the preparation of a task's context (hydration) busy past its 60-second limit. The time is now proportional to the length for every text, in the TypeScript and in the Python copy, and the result is byte for byte what it was for every text that neither round still changes on its 20th pass; the real issue and pull request text of this repository is no longer changed by the 2nd. A text that a round still changes on its 20th pass, which only a text built for that is, is no longer worked on pass after pass: what stands before its first "<" is kept and the rest is replaced by the marker [SANITIZED_NESTED_TAGS]; if no "<" is left in it, it is complete and stays as it is.

Gain: No single comment can hold up hydration or the agent any more. At 65,536 characters, the longest body GitHub accepts, the five kinds of text that were measured took between 0.06 seconds and 13 minutes per call in the orchestrator and between 0.7 seconds and an estimated 53 minutes in the agent; they now take under 2 milliseconds and under 9 milliseconds. Results are unchanged wherever the 20th pass no longer changes the text: more than 600,000 texts, among them every issue, pull request, comment and review text of this repository and 9,669 documents of the build machine, all but 62 of them of other projects, and 6.3 million generated short texts give the old result byte for byte in both languages. A text that was built to need more passes no longer costs a task the whole text, only the part from the first "<" that is left in it: a task description that is put together from a title, a description and other people's comments keeps what stands in front of that.

Test: cdk/test/handlers/shared/sanitization.test.ts > 'sanitizes %s, %d characters, within a second' (15 cases), 'strips %s nested 20 deep and cuts a text that nests them deeper at its first "<"' (2), 'keeps a task description up to the text that reaches the limit, %s' (2), 'cuts at a "<" that starts no tag when the text behind it reaches the limit', 'leaves a text that ends with the marker as it is', 'strips tags: %s' (13); agent/tests/test_sanitization.py > TestTagStrippingTime (10), TestTagStrippingPassLimit (6), TestTagStrippingPass (13), TestLetterOnlyPythonFolds (1)

chore(tooling): tighten the SAST scan, git hooks and coverage gates

Gate: The whole-repository SAST scan fails when semgrep loaded no rules and shows what semgrep reports

The scan that checks the whole repository with the rule packs of the semgrep registry passed when the registry answered with empty packs: semgrep then loads no rule, checks nothing and exits 0, and a quiet flag kept its messages out of the log. The task now shows semgrep's output, writes a report, and ends with a check that fails unless the report lists at least one loaded rule. The scan that runs on each pull request already worked this way.

Gain: The only scan that applies the registry rule packs to code a pull request did not touch (weekly, and before every push) can no longer call the repository clean without having checked it. Measured with a local stand-in for the registry that answers with empty packs: exit 0 and no output before, exit 1 with a message that says why after. With the real registry the task loads 1,157 rules and passes on a tree without findings. A test now runs the last check of both scans and holds the two to the same rule packs, which until now only a comment asked for. 7 lines added and 1 removed in the task file.

Test: cdk/test/scripts/mise-tasks.test.ts > 'security:sast fails when semgrep loaded no rule, and does not silence semgrep' and 'ask for the same rule packs'

Bug: mise run without a task name installs first and builds afterwards

The default task, which runs when mise is called without a task name, listed the install and the build as dependencies. mise starts dependencies at the same time and the build does not depend on the install, so on a fresh checkout the build started while the packages were still being installed. The task now runs the install and then the build, one after the other.

Gain: The one command the task promises (install, then build) works on a fresh checkout. Shown with the real mise on a small copy of the task: before, the build started first and the run failed; after, the build starts when the install has finished. One line changed.

Test: cdk/test/scripts/mise-tasks.test.ts > 'installs, then builds'

Gate: Git hooks run the node, gitleaks and semgrep that mise.toml pins instead of the machine's own

The git hooks start through a login shell. On macOS that shell puts the system and Homebrew directories back in front of the ones mise had added, and mise leaves them there, so the hooks ran whatever node, gitleaks and semgrep the machine had instead of the pinned versions. Every hook that runs a mise task now tells mise to put its own tools first, and the hook that regenerates the documentation mirrors runs through mise instead of calling node directly.

Gain: On the owner's Mac the commit and push hooks ran node 22.20.0 and semgrep 1.119.0 where the repository pins 22.23.4 and 1.185.0; with the change they run the pinned versions (measured through the real hook runner). The secret, masking and SAST scans at commit and push no longer depend on what Homebrew installed. Interactive shells and CI are not touched. A test fails when a new hook leaves the setting out.

Test: cdk/test/scripts/git-hooks.test.ts > 'export MISE_ACTIVATE_AGGRESSIVE=1 before the mise task they run' and 'call no 'node' of their own, which would be the one of the machine'

Gate: The cdk, agent and CLI coverage floors sit two points under what the suites measure

The coverage floors of the cdk package, the agent and the CLI had fallen far behind what the test suites measure: on this branch by 4.8 points for cdk lines, 11.5 points for the agent and 10.5 points for the CLI's lines. They are raised to two points under the measurement, the margin the coverage contract already uses for the web console and the Jira Forge app: cdk to 93 / 85 / 95 / 93 (statements, branches, functions, lines) from 91 / 82 / 94 / 91, the agent to 89 from 80, and the CLI to 91 / 85 / 92 / 91 from 83 / 85 / 89 / 83. Every copy of a floor changes together, as the drift check requires.

Gain: A drop of more than two points now fails the build in all three packages, where cdk could lose almost five points of line coverage and the agent and the CLI more than ten unnoticed. Shown by planting when the first floors were raised: 600 untested statements in the agent (82.51 percent) passed the old floor and fail the new one; 3,214 untested lines in cdk (92 percent) were above the old floors and fail the new ones. All three suites pass on the tree with the new floors: cdk 95.79 / 87.24 / 97.84 / 95.79 with 7,180 tests, the agent 91.50 with 2,666 tests, the CLI 93.55 / 87.52 / 94.41 / 93.55 with 1,431 tests.

Test: the gates themselves: 'mise run check:coverage-thresholds-sync' (one copy raised alone: exit 1), 'yarn test' in cdk and 'mise //agent:test' with the new floors, on the tree and with planted untested code

Gate: The coverage contract pins which tests pytest collects and the file its coverage settings come from

The coverage contract fixed which tests the JavaScript packages run, but not which tests the agent's pytest collects. A name pattern or a path setting could drop test modules, and an environment variable could point the coverage measurement at another settings file that leaves source files out, with every gate still green. The drift check now compares the pytest settings that decide collection with the contract, and the test task names the settings file itself.

Gain: Shown on the committed tree: a pattern that drops the four test modules of the test guards, or settings that leave 58, 403 or 0 of 2,402 tests, passed the drift check; a planted settings file let the suite pass at 89.07 percent over 5,556 statements instead of 87.12 percent over 6,996. Now each of six settings fails the drift check when it differs from the contract, and the planted file has no effect. 31 lines added and 9 removed in the check, comments included.

Test: cdk/test/scripts/check-coverage-thresholds-sync.test.ts > 'a pytest setting that decides which tests are collected: ...' (six), 'a warning filter with a backslash in its pattern, in the table of the collection settings', '--cov-config taken off the test task and off the copy of its line in the contract'

Lean (delete): The allow lists of bandit and ruff lose the entries that accepted nothing

Two allow lists held entries for exceptions that do not exist. The Python security scanner skipped five checks: three can never be reported at the level the task asks for, and two were for code that is not there. The linter exempted the emulator tests from two rules they do not break. The entries are deleted.

Gain: The Python security scanner now reports a shell=True call with a variable command, which it had been told in advance to skip, and the linter reports a hardcoded token argument or a /tmp path in an emulator test. Both gates pass on the tree exactly as before. Two more lists of the same finding are not changed here: the ignore entries of the workflow scanner, which are left to the owner, and a gitleaks stopword in a file of another change.

Test: the gates before and after, with plants: 'zizmor --offline .github', 'bandit -c pyproject.toml -r . --severity-level=high', 'ruff check --config pyproject.toml --no-cache'

docs(guides): correct the task requests of the guides and test them

Bug: Task requests in the user guide and the quick start name the coding workflow; a test sends each to the API

The first requests a new user copies from the user guide and from the quick start did not do what the guides say. The request for a GitHub issue was answered with an error (400), and five requests with a task description were accepted but ran the fallback workflow, whose agent cannot change a file and is told not to open a pull request. All six now name the coding workflow, as the CLI does for the same task, and a new test sends every request of the two guides that creates a task through the real API handler.

Gain: A user who copies the first REST call of the quick start or of the user guide, or the guide's GitHub issue, Idempotency-Key or webhook call, now starts the coding workflow the guides describe (branch, changes, pull request) instead of getting a 400 or a task that only reads. The build now fails when a curl command of the two guides that posts to /tasks or /webhooks/tasks carries a request that the API refuses, or one that leaves a repository to the default workflow, and when the test cannot read such a command with its body: it caught all seven mistakes planted to try it (broken JSON, an unknown workflow, a bad Idempotency-Key, a missing workflow in three places, an example it could no longer read). 6 request bodies changed in 2 guides, 1 test file of 115 lines added.

Test: cdk/test/contracts/guide-task-examples.test.ts > '$guide:$line the API accepts the request and leaves no repository to the fallback workflow' (one test for each of the 10 requests) and 'each one of %s is read with its body'

Lean (delete): The docs package no longer carries jest, jest-junit and a jest configuration that nothing runs

The docs package listed jest and jest-junit as dependencies and carried a 35-line jest configuration, but nothing runs jest there: its two test files run with Node's own test runner, and the configuration could not even match them. The dead-code check would have reported the unused dependency; an ignore entry told it to accept it. The two dependencies, the configuration and the ignore entry are removed.

Gain: 37 lines and two direct dependencies less in the docs package, and one accept-entry less in the dead-code check, which stays at zero findings without it. Nothing else moves: yarn.lock does not change, because cdk and cli ask for the same versions (checked with a real install on a copy), and the docs tests, the docs build and the link check pass.

Test: node_modules/.bin/knip --no-progress (the command of mise run check:deadcode) on a scratch copy: exit 1 'Unused devDependencies (1): jest docs/package.json:16:6' when only the ignore entry is removed from the committed tree, exit 0 without output after the change; mise //docs:build and mise //docs:link-check exit 0 there

Gate: The docs test task fails when one of its two test files is missing, instead of running fewer tests

The docs test task names its two test files so that a pattern matching nothing cannot pass unnoticed. But Node's test runner reports a missing file only when it finds no file at all: with one of the two renamed or deleted, the task passed with 15 tests instead of 20 and said nothing. Each file now has its own command, so a missing file fails the task.

Gain: A renamed or deleted docs test file now fails the required build with "Could not find 'scripts/markdown-lint.test.mjs'" instead of silently dropping its tests, for example the five that keep the rules of the Markdown lint switched on. The commit hook fails in the same way for a rename; it does not run for a commit that only deletes the file. Measured on a copy: exit 0 with 15 tests before, exit 1 after; with both files the task still runs all 20 tests. One line changed, two comment lines added.

Test: mise //docs:test on a scratch copy with docs/scripts/markdown-lint.test.mjs moved away: exit 0 with 15 tests before (red-3.txt), exit 1 with "Could not find 'scripts/markdown-lint.test.mjs'" after (green-3.txt)

The user guide said in two places that the --pre-approve option of bgagent submit takes the same scopes as approve --scope. Three of those scopes (this_call, tool_type_session and tool_group_session) stand for a call that is waiting for approval, and the CLI and the API refuse them at submit. The guide now lists the scopes that can be approved in advance and says that the three are rejected; it also says that tool_group_session covers only the approved call when the tool belongs to no group. Gain: the guide matches what the CLI and the API accept, so a reader no longer tries a pre-approval that is refused.

fix(agent): replace app and bearer tokens whole past an inner marker

Risk: Both secret scanners replace a GitHub App token whole when part of its signature looks like an older token

A GitHub App installation token of the current format ends in the signature of a JWT, which is random text. When that signature happened to hold a run that looks like an older GitHub token, the two secret scanners (the agent's scanner of tool output and the API's scanner of deny reasons) replaced the token only up to that run and left the rest of the signature in the text: by calculation about 1 token in 35,000 when the signature has 342 characters, and fewer when it is shorter (no real token was examined). The pattern for the token now runs on through the marker that an earlier pattern leaves inside it, so such a token is replaced as a whole, by one marker.

Gain: What the model is shown of tool output, and a deny reason as it is stored, no longer hold the rest of such a token. Measured in both scanners on the same 1,000,000 random tokens with a signature of 342 characters, each on its own, in an assignment, as a JSON or YAML value, in a sentence, as a URL parameter and behind 'Authorization: token': before, 23 tokens were not replaced as a whole and 21 of them kept 6 to 266 characters of their signature (101 at the median); after, none. On 1,600,000 generated texts the changed scanners show no character that the previous ones hid, none of the 1,299 tracked text files comes out differently, the change to this pattern makes the two scanners differ on no input on which they agreed, and the scan stays linear (5,000,000 characters in 0.41 seconds at most, 0.40 before).

Test: agent/tests/test_output_scanner.py > TestScanToolOutput::test_stateless_app_token_is_replaced_whole_past_an_inner_marker (3 rows); cdk/test/handlers/shared/deny-reason-scanner.test.ts > 'replaces a stateless GitHub App installation token whole past an inner marker: %s' (the same 3 rows)

A JWT behind Authorization: Bearer is replaced as a whole by both secret scanners, also when a part of it looks like a secret of another kind. A JWT ends in a signature of random characters. When that held a run that looks like an older GitHub token, the pattern for those tokens wrote its marker inside the JWT, the Bearer pattern stopped at that marker, and the rest of the signature stayed in the text: about 1 in 35,000 tokens with a signature of 342 characters, GitHub App tokens and other JWTs alike (measured with GitHub App tokens of that shape, in both scanners: 23 of 1,000,000 not replaced as a whole, 21 of them with 6 to 266 characters left; none after the change). In the agent's scanner this is older than this branch; the API's scanner got it on this branch, when its pattern for the older tokens lost its word boundaries and its fixed length. One new last entry in the list of each scanner takes the Bearer marker, the markers directly behind it and the rest of the token, and leaves the one Bearer marker. It runs last, so every other pattern meets the text it met before: on 1,600,000 generated texts the scanners show no character that they hid before, none of the 1,299 tracked text files comes out differently, and the scan stays linear. Gain: a bug fixed in both scanners; the entry and its comment are 11 lines in each.

chore(tooling): delete unread .npmignore files and dead scan exemptions

Lean (delete): Two secret-scan exemptions the scanned history does not need and seven ignore comments ty skips are removed

The rule file of the secret scan exempted every value that contains the text of one mock token. That token is in no file of the history the scan reads: the test that used it sits on a branch that was never merged. A second exemption in the same file could not match anything, as its own comment said. Both are deleted. Seven comments in one test file asked a type checker to ignore a line, written in a form the project's type checker does not read; they are deleted too.

Gain: One rule-wide exemption of the secret scan is gone: a made-up key that contains the old text was accepted before and is reported now. 7 lines fewer in the rule file and seven misleading comments removed. The history scan reports the same findings before and after on the same commit (none added, none hidden); the type check, the lint and the 85 tests of the test file pass as before.

Test: No new test (two deletions). Gates run before and after on the same commit: 'mise run security:secrets' (same three known fingerprints), 'uv run --locked ty check' ('All checks passed!'), ruff check and format check, 'pytest tests/test_pipeline.py' (85 passed).

Lean (delete): Three .npmignore files of packages that are never packed are deleted, with the three lines that named them

Three .npmignore files, left behind by a project generator that is no longer used, listed what to leave out of npm packages. No package of this repository is packed or published: every package is marked private, no @abca package is on the npm registry, and no workflow, task or script runs a pack or publish command. The files are deleted, together with the code-owner line and the two ignore-file lines that named them.

Gain: 51 lines removed in six files: 48 in the three deleted files and 3 in the files that named them. Nothing read them. For the one package that could be packed by hand, the CLI, the file had no effect either: its manifest lists what to include, and npm then does not apply a top-level .npmignore (a dry-run pack lists the same files with and without it).

Test: No test (a deletion of files nothing reads). Proof by search and by a dry-run pack.

The README of the CLI was titled @backgroundagent/cli, and its first instruction was npm install -g @backgroundagent/cli. The package of this repository is @abca/cli, it is private and nothing publishes it, and the npm registry has no package of either name: the instruction failed for everyone who followed it, and a name that a README tells its readers to install globally is better not left for somebody else to register. The README now says that the CLI is not published and is built and run in the monorepo, which its second instruction already showed; the contributor guide of the CLI names the real package. Gain: the first step of the README works, and no document of the repository points at a package the project does not own.

chore(tooling): fail the console lint on dropped and misused promises

Gate: The console's lint fails on a promise that is dropped or handed to code that ignores it, as in cdk and cli

The lint of the operator console said it checked promise misuse the way cdk and cli do, but two of their rules were missing: the one for a promise that nobody awaits or handles, and the one for a promise handed to code that ignores it, such as an async function used as a click handler. A request started that way could fail without the page ever showing it, and lint passed. Both rules are now on. The 14 statements they report today (11 page navigations, 2 'load more' calls and the sign-out) are marked as deliberately not awaited; none of them can fail unnoticed, so the console behaves as before.

Gain: A promise dropped in a console handler now fails the build, as it already does in cdk and cli. Checked with six mutated copies of console files (a cancel request that is not awaited, an async click handler, a promise used as a condition, a removed marker): the old configuration passes all six, the new one reports all six. Cost: 2 lines of configuration and 14 one-word edits, no change at run time.

Test: The gate itself, 'mise //web:eslint:check': exit 1 with 14 errors once the two rules are on and the statements untouched (red-1.txt), exit 0 on the final tree; six mutated copies of console files are each reported (red-2.txt). No snippet test: the rules need type information.

A click on the console's title, 'ABCA Operator Console' in the top left corner, loaded the whole page again: the browser fetched the console anew, the session was restored and every list on the page was requested again. The title was wired to the handler that the side navigation uses, which reads the link's address from the event; the component library sends the title's event without one, so the handler did nothing and left the click to the browser. The title now has a handler of its own, which goes to the overview inside the app, like every other link of the console. Gain: going back to the overview no longer reloads the application; the page changes at once and shows what it has already loaded. One test clicks the title and fails without the change. Not one of the audit's findings: it was seen while the console's handlers were read for the lint change.

chore(tooling): turn on three lint rules, test the complexity records

Gate: The CLI lint tasks name their configuration file, so one in a subfolder cannot replace the rules

ESLint looks for its configuration from the directory of each file it checks. A configuration file in a subdirectory (a copied directory or a generated scaffold can bring one along) therefore replaced the package's rules for the files below it, and the lint task stayed green. The cdk tasks already name their configuration file; the two lint tasks of the CLI now do the same, and the test that guards the flag reads the task files of cdk, the CLI and the web console.

Gain: A stray configuration file below the CLI can no longer take files out of lint. Planted beside a file with 13 findings, an empty one made the CLI lint exit 0 with no output; with the flag the same plant fails with the 13 findings. The same 155 files are linted with and without the flag, and the task stays green on the tree. Two command lines; the test fails if a lint task of any of the three packages loses the flag.

Test: cdk/test/eslint-config.test.ts > 'the eslint tasks of cli name eslint.config.mjs' (test.each over cdk, cli, web)

Gate: The lint tasks of the web console name their configuration file as well

The two lint tasks of the web console had the same gap as those of the CLI: a configuration file in a subdirectory replaced the package's rules for the files below it while the task stayed green. Both tasks now name the package's configuration file, and the same test covers them.

Gain: Planted beside a file with 3 findings, an empty configuration file made the console lint exit 0 with no output; it now fails with the 3 findings. The same 80 files are linted with and without the flag. Two command lines.

Test: cdk/test/eslint-config.test.ts > 'the eslint tasks of web name eslint.config.mjs'

Gate: A test fails when a function above the complexity ceiling grows past the value recorded beside it

Eighteen functions of cdk and the CLI are above the complexity ceiling because they are older than it. Each carries a comment that switches the check off for that function and says 'must not grow', with the value the function had. Nothing compared the two numbers: with the check off, a branch added to one of these functions passed the lint and every test. A test in each package now measures these functions with the comments ignored and fails when one is above its recorded value, or when a comment has lost its number.

Gain: Growth of the eighteen largest functions is caught by the next test run instead of by nobody. Two if statements added to the attachment validation (recorded 44) leave the lint green and fail the new test with the file, the line, the function, 'has a complexity of 46' and 'Recorded: 44'. The check costs about two seconds in cdk and one and a half in the CLI. On this branch all eighteen functions are at their record.

Test: cdk/test/eslint-config.test.ts and cli/test/eslint-config.test.ts > 'no function above the complexity ceiling has grown past the value its directive records'

Docs: The cdk and CLI guides say what the number in a complexity comment means and which test holds it

The contributor guides of cdk and the CLI said that the functions above the complexity ceiling must not grow and named a command that prints the current value; nothing checked it. Since the new test does, the guides now say that the first number in the comment above such a function is its record, that the test fails when the function grows past it and what the failure names, and that the record is lowered in the same change when the function gets smaller.

Gain: A contributor who meets the failure of the new test finds in the guide what the two numbers are and what to do about them. One bullet in each of the two guides; the example in each is a real comment of that package.

Gate: An explicit any fails the CLI lint; the upload error of submit is read as before this pull request

The CLI had the lint rule against any switched off because of four uses. One went away earlier in this pull request; the last three go now: the factory that builds AWS SDK clients declares what it hands to a client's constructor, and its test reads the client configuration without a cast. The rule is on. The error handler of the upload in bgagent submit, which the earlier change had rewritten, reads the name and the message of whatever was thrown, as it did before this pull request, but without any.

Gain: A new any in the CLI sources or tests fails the lint, and a class whose constructor cannot take the client configuration (one that wants a number or a string, for example) is refused by the compiler when it is given to the client factory. What the factory sends is unchanged: the shared user-agent vectors pass as they are. The upload handler reports every thrown value as it did before this pull request (14 kinds tried); the rewritten form had differed for four of them, and in a test run it took a real abort for a failure instead of a timeout. Two new test rows hold that.

Test: cli/test/eslint-config.test.ts > 'eslint.config.mjs reports each snippet with exactly the rules listed' (the row 'An explicit any'); cli/test/commands/submit.test.ts > 'reports an upload that fails as a timeout when fetch rejects with its own abort error' and 'reports an upload that fails with the message of a thrown object'

Gate: In cdk a catch block that throws a built-in Error without the caught error as its cause fails the lint

Nine places in cdk caught an error and threw a new one without the original, so whoever received the new error could not see the type or the stack of the real failure. ESLint's rule against that was switched off because of these nine places. Eight of them now hand the caught error on as the cause, and the rule is on for the package. The ninth is in a file this change does not touch; the lint configuration exempts that one file by name.

Gain: A new catch block that names the caught error and throws one of JavaScript's built-in errors (Error, TypeError and the like) without it as the cause fails the lint; a test row keeps the rule on, also for the files next to the exempted one. The rule does not look at the error classes of the project, nor at a catch block without a parameter. Where such an error reaches Node uncaught (an unreadable or invalid deployment profile at synthesis, a failed run of the bootstrap template generator), Node now prints the original error below the new one. Nothing a handler logs or answers and nothing the two preflight scripts print changes: they report the message, which is the same.

Test: cdk/test/eslint-config.test.ts > 'eslint.config.mjs reports each snippet with exactly the rules listed' (the row for src/handlers/shared/a.ts, 'An error thrown from a catch block without the caught one as its cause')

Gate: A control character in a regular expression fails the lint of cdk and the CLI, two patterns excepted

The lint rule against control characters in regular expressions was switched off for all of cdk and all of the CLI, because each package has one pattern that needs them: the sanitizer that strips control characters from text, and the pattern that strips terminal escape codes from the output that bgagent setup shows. The rule is now on in both packages, and each of the two patterns carries a comment on the line above it that exempts it and says why.

Gain: A control character written as a hex or unicode escape, or typed raw, in any other regular-expression literal or in a string literal given to RegExp now fails the lint in the 680 TypeScript files of the two packages; a test row in each keeps the rule on. Two package-wide switches became two one-line exemptions with their reason.

Test: cdk/test/eslint-config.test.ts and cli/test/eslint-config.test.ts > 'eslint.config.mjs reports each snippet with exactly the rules listed' (the row 'A control character in a regular expression')

Gate: Two spaces inside an import attribute are a lint finding again in cdk and the CLI

An earlier change of this pull request deleted fifteen formatting rules of ESLint itself in favour of their maintained copies in the stylistic plugin. One copy is more lenient by default: it accepts two spaces beside a comment inside an import attribute (the with { type: 'json' } of an import), which the deleted rule reported. The plugin's rule now gets the setting the deleted rule had, in cdk and in the CLI.

Gain: The check on import attributes that the earlier change dropped is back, and a test row in each package fails if the setting is lost. No existing line is affected: neither package has an import attribute today and the lint of both stays green.

Test: cdk/test/eslint-config.test.ts and cli/test/eslint-config.test.ts > 'eslint.config.mjs reports each snippet with exactly the rules listed' (the row 'Two spaces inside an import attribute')

Gate: Five functions that got smaller have their complexity record lowered, so the branches cannot return

Five of the functions above the complexity ceiling got smaller in this pull request: the handlers of the GitHub, Jira and Linear webhook processors and the actions of bgagent linear setup and bgagent submit. Their recorded values still stood at the old numbers, and the new test accepts anything up to the record, so the branches that were taken out could have come back unnoticed. The five comments now record today's value, followed by the value the function had when the ceiling was introduced.

Gain: 23 branches of headroom are closed (59 to 56, 116 to 115, 120 to 118, 115 to 99, 70 to 69; later commits of this pull request lower the last two again, to 97 and 68). At this commit one if added to the action of bgagent linear setup failed the test with 'has a complexity of 100' and 'Recorded: 99'; under the old record of 115 the same addition passed. Five comment lines.

Test: cdk/test/eslint-config.test.ts and cli/test/eslint-config.test.ts > 'no function above the complexity ceiling has grown past the value its directive records'

fix(tooling): masking gate sees tuple handlers and non-source files

Gate: The masking gate also matches a handler written except (A, B): and a try statement with an else clause

The gate that fails on an except block which swallows an error and returns an empty value did not see a handler written with a tuple of exception types and no 'as' name, nor any handler of a try statement that has an else clause, so such code passed without a reviewed reason. The rule now matches every form of handler in all four shapes of a try statement, with a fixture for each. The four handlers in the agent that it now reports keep their documented empty result, each with a suppression that names what its caller does with it.

Gain: The required masking gate reports all 39 handler shapes that were measured (24 before) and keeps its 57 earlier findings, so a new handler of the tuple or else form can no longer pass unreviewed. Four silent fallbacks in the agent carry a reason. The Python rule goes from six patterns to four.

Test: .semgrep/silent-success-masking.py > masked_tuple_except, masked_tuple_except_with_finally, masked_with_else, masked_with_else_and_finally, ok_return_in_else, ok_tuple_classify_then_reraise (run by 'semgrep test .semgrep/', the first step of 'mise run security:sast:masking')

Gate: A semgrep suppression in a workflow, Dockerfile, script or config file needs a rule id and a reason

The guard that holds every semgrep suppression comment to a rule id and a reason read only TypeScript, JavaScript and Python files. A bare comment in a workflow, a Dockerfile, a shell script or a TOML file passed it, although semgrep honours the comment there and it switches off every rule for its line. The guard now reads tracked files of every kind except Markdown (the rule file and its fixtures under .semgrep/ stay outside, as before), and the one task description that used the word in prose is reworded.

Gain: An off switch for the security scan can no longer be added unreviewed to a workflow, Dockerfile, script or configuration file: six planted bare comments that passed before are all reported. The guard reads 1123 tracked files instead of 931; the 192 additional files add about 0.15 seconds to its run.

Test: cdk/test/scripts/check-masking-suppression-placement.test.ts > 'reads the tracked files that the masking rules do not' (6 tests), 'leaves Markdown alone, where the guides have to spell the word', 'reads a Markdown file that semgrep scanned', 'reads a file that holds a NUL byte'

fix(agent): keep trace headers and baggage out of third-party requests

Risk: Agent requests to Linear and Atlassian carry no trace headers and no baggage with user id and repository

The agent image starts its server under the OpenTelemetry wrapper, which hooks into every HTTP library it finds. Through the hook for the requests library, every call the agent made to Linear and to Atlassian (reactions, comments, status changes; in a local run without the orchestrator also the GitHub API) carried the trace headers of the task and a baggage header with the id of the user who submitted the task and the repository name, and on AgentCore also the session id; user id and repository have been in the baggage since July 2026. This happened wherever the image runs outside the agent observability mode of the AWS OpenTelemetry package, which switches that hook off: on the Lambda MicroVM backend and in a local server run as the repository builds them, and on AgentCore unless the service turns that mode on itself; the ECS backend starts the agent without the wrapper and never sent them. The image now switches the hooks for requests and urllib3 off itself, with the list the AWS package uses in that mode, so these calls carry none of those headers on any backend, while calls to AWS and to the platform's tool gateway are traced as before. Measured with a local header recorder and the agent's own code, not on a deployed stack: 34 of 34 such requests carried the headers before, 0 of 34 after.

Gain: Linear and Atlassian no longer receive, with every reaction, comment and status change of a task (nine requests for a Linear task on a fresh issue, one more for each mark of an earlier run that it removes; up to five per Jira task), the id of the submitting user, the repository name, the task's trace ids and, on AgentCore, the session id. Whether they are sent no longer depends on a flag that only the runtime sets and the repository cannot see. Three tests (about 3 seconds) fail when the instruction is removed, loses one of the two names, or no longer matches the list of the pinned AWS OpenTelemetry package. One instruction in the image definition; no agent code changed.

Test: agent/tests/test_image_instrumentation.py > test_dockerfile_names_the_instrumentations_that_copy_context_into_headers, test_wrapper_loads_neither_with_the_value_of_the_dockerfile, test_dockerfile_list_is_the_one_the_distro_applies_in_agent_mode

nizar-lahlali pushed a commit that referenced this pull request Nov 18, 2026
GHSA-fc5q-39xc-vjpf (updated 2026-11-17) covers every picomatch release
through 4.0.7, the latest, so no version fixes it and security:deps
fails on every branch. The locked copies (2.3.2, 4.0.5, 4.0.7) serve
build, test and lint tooling only; no runtime dependency of cdk, cli or
web reaches picomatch, so no Lambda bundle, the CLI or the console ships
it, and the tooling matches only patterns from this repository's own
configuration. #1052 accepts the same advisory as part of its dependency
upgrade; whichever merges second keeps one entry.
@krokoko

krokoko commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor Author

Automated review: I’d fix the following before merging.

  • Session start. The new check covers failed and cancelled tasks. It still starts a new session if the first one is already running and writing the session_started event fails. In a local test with compute mocked, one failed event write caused six start calls for one task. A retry should pick up the session ID already saved on the task. Session start
  • Linear workspace credentials. Setup skips the stored workspace ID check when the URL name matches. If another workspace now uses that name, setup can overwrite the original workspace’s credentials. Removal has a related race. Someone reconnecting a workspace while an old installation is being removed can lose the new credentials. Setup should check the workspace ID even when the names match, and removal should act only on the installation it first read. Setup · Removal
  • Upload retries. If before/shot.png has passed screening and after/shot.png is still pending, the CLI can upload the first picture for both. Match each retry to its attachment ID. After a confirmation timeout, the CLI also reads the task’s status and then confirms again. That can report a completed task as an error or hide the reason screening failed. The task it already read has the answer. File matching · Confirmation
  • Gateway tool errors. I checked a failed repo_config call through the registered tool. The agent received it as a success. The Python SDK reads is_error, while the handler returns isError. Testing through the SDK would catch this. Gateway handler
  • Attachments on a shared agent server. Tasks without a repository download into the same directory. If one download fails, cleanup deletes files that another task is still using. Each task needs its own attachment directory. Download · Cleanup

@ayushtr-aws ayushtr-aws left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Verdict: request changes

The work is careful and mostly moves the platform toward fail-closed, but it ships one confirmed secret-redaction regression. Everything else below is non-blocking; several items are introduced by this PR.

I built the branch (66076b0e), deployed it to a dev stack and ran the Jira integration end to end against a real Jira Cloud site (label trigger, iterations, question comments, a deliberately red build). The core flow and the PR's Jira fixes work; the Jira findings below come from that run.

Blocking

  1. Secret redaction regression — agent/src/output_scanner.py:113-119. The new CONNECTION_STRING pattern forbids / in the password. postgres://admin:abc/def+ghiJKL@db.internal:5432/app is redacted on main and passes through unredacted on this branch (I ran scan_tool_output on both). Base64-style passwords contain /. Suggested fix: allow / in the password and anchor on the last @ before the host, keeping the "no / in the user part" rule.

Resolved since first posted: #1051, #1043 and #1044 now carry the approved label (ADR-003).

Non-blocking

Jira (from the live run)

  • The agent's answer is posted as raw markdown (introduced). cdk/src/handlers/shared/jira-status-comment.ts:100-103 emits each answer line as an unmarked text run, so backticks, **bold** and fenced blocks arrive in Jira as literal text. Suggested fix: route the lines through the existing parseMarkdownRuns and add a codeBlock node to buildAdfDocument; the same applies to renderJiraHoldQuestion.
  • A red-build iteration is reported with no reason (introduced). cdk/src/handlers/fanout-task-events.ts:1729 relabels the run as failed, but the reason is derived from error_message, which is empty on a completed run; jira-preview.ts:65 hard-codes errorTitle: null for the same case. The comment reads "Shipped a PR but stopped early — review and decide if more work is needed". Suggested fix: pass a fixed title such as "build or tests failing". Related question: a first-run COMPLETED task with build_passed === false still posts "Task completed" — is that intended?
  • With a status_on_start override, every iteration still drags an In Review card back to In Progress (pre-existing, not covered by "stop moving cards backward"). agent/src/jira_reactions.py:718-722 drops max_source_rank and the ladder cut when an override is set. Observed three times on one issue. Since pipeline.py only calls transition_pr_opened when the build passed, a red-build iteration would leave the card in In Progress. Suggested fix: keep max_source_rank for iteration tasks even with an override. The guide also contradicts itself here (docs/guides/JIRA_SETUP_GUIDE.md:404 vs :411).
  • Iteration tasks copy the status overrides from the prior task, not from the project mapping (cdk/src/handlers/jira-webhook-processor.ts:1277-1282), so changing or removing an override never reaches issues that already have a task.
  • Descriptions reach the agent as Jira wiki markup (pre-existing). The webhook payload carries the description as a string and cdk/src/handlers/shared/jira-adf.ts:64 returns strings untouched, so the agent sees ** nested, {code:bash}…{code} and [url|url|smart-link] while the guide says markdown. Wiki-style images are also dropped by extractImageUrlAttachments.
  • Re-running bgagent jira map resets onboarded_at on the mapping row (observed; cause not traced).

Control plane

  • Poll errors are swallowed with no cap (introduced). cdk/src/handlers/shared/orchestrator.ts:1151 treats every failed status read as one missed poll. A non-retryable error such as AccessDeniedException leaves the task RUNNING and holding its concurrency slot for the whole window. Suggested fix: swallow only throttling/5xx/timeouts, or cap consecutive failures as the ECS path does.
  • Epic seeding can half-write. cdk/src/handlers/shared/orchestration-store.ts:385-409: for 24 or fewer children the meta row shares one unordered BatchWriteItem with them, so under throttling the meta row can land without its children; the replay then returns alreadyExisted: true. Suggested fix: write the meta row in its own request after every child chunk has drained.

Agent runtime

  • The new force-push pattern is bypassed by a suffix. agent/policies/soft_deny.cedar:42-43 gates git push origin feat -f but allows git push origin feat -f 2>&1 | tail -5 and … -f && echo ok. Suggested fix: tokenise the command in the hook and pass a boolean to Cedar instead of globbing.
  • The fork-PR guard is partial. agent/src/repo.py:186-229 returns early unless a local branch of that name exists, so a fork PR whose head branch name also exists upstream is not refused. Suggested fix: check isCrossRepository unconditionally for PR workflows.

CLI

  • A corrupt config reads as "Not configured" (introduced). cli/src/config.ts:55-61: a truncated or unreadable config.json now produces "Run bgagent configure first", and following that overwrites the file. Suggested fix: distinguish a missing file from an unparseable one.
  • Upload confirm after a 504 hides the failure reason (introduced). cli/src/commands/submit.ts:454-474: if the task went FAILED while the first confirm timed out, the second confirm gets 409 and the user never sees the block reason.
  • linear list-projects --output json prints [] for an unreachable workspace and exits 0 (cli/src/commands/linear.ts:2722-2725).

Docs and tests

  • docs/decisions/ADR-016-pluggable-identity-and-auth.md:25 still describes the agent-side Linear token refresh that this PR deletes.
  • docs/design/API_CONTRACT.md:397 does not mention the new GET /v1/pending behaviour (expired requests hidden, 100-row cap, 60/min); hitting the page cap is only a log line, so a client cannot tell the list is incomplete.
  • Hook behaviour that depends on the pinned Claude CLI (additionalContext, updatedToolOutput) is asserted only on the dict the hook returns; a CLI bump could disable steering and redaction with the suite green.
  • agent/src/output_scanner.py and cdk/src/handlers/shared/deny-reason-scanner.ts are marked "keep in sync" but share no test vectors; a shared file under contracts/ would have caught the regression above.

Nits

  • Open CodeQL alert on cdk/src/handlers/shared/sanitization.ts:152 — resolve or dismiss with a reason.
  • cdk/src/handlers/registry-publish.ts:102,108 returns raw AWS error messages to the caller.
  • cdk/test/constructs/ecs-agent-cluster.test.ts:1029 and cdk/test/handlers/approval-metrics-publisher.test.ts:506 build a stack inside a test rather than in beforeAll.
  • cdk/src/constructs/task-orchestrator.ts:429 still cites durable SDK 1.1.3.

What checked out

  • Full local build passes (cdk: 265 suites, 7,192 tests). CI is green except integ-smoke, which is waiting for admin approval.
  • Bootstrap synth-coverage: pass. The template change is the upstream CDK bootstrap v32→v33 update plus js-yaml 5 re-serialisation; policy documents are identical and no new CloudFormation resource type is added.
  • The durable-execution SDK 2→3 and js-yaml 4→5 call sites match the new majors. cedarpy and cedar-wasm did not move.
  • The docs mirror is in sync; shared API types are in sync across cdk, cli and web.
  • Coverage floors were raised; no skipped tests; ten sampled fixes each have a test that would fail if the fix were reverted.

Scope

Four unrelated concerns (dependency upgrade, emulator pin, registry fixes, 434 audit changes) in one 503-file, 99-commit PR. No reviewer can cover it fully and a revert of one part takes the rest with it. This review did not read every file; the lockfiles, agent/src/prompts/* and a number of orchestration helpers were skimmed or skipped. Please split out at least the dependency upgrade.

bgagent added 6 commits November 18, 2026 19:15
Every direct dependency of cdk, cli, web, docs, the root and the Jira
Forge app moves to its newest release that is at least seven days old
(published on or before 2026-11-10): 65 packages. Six are majors:
@aws/durable-execution-sdk-js 3, commander 15, js-yaml 5, jsdom 31,
react-router 8 and eslint-plugin-jsdoc 65. yarn.lock goes from 1429
to 1305 locked versions. Tool pins: knip 6.45.0, prek 0.5.10, semgrep
1.185.0, osv-scanner 2.7.1, grype 0.121.3, trivy 0.76.2.

Pins that the upgrade made unnecessary are removed: 20 of 29 root
resolutions, 4 of 5 Forge overrides, @types/js-yaml and two knip
ignores. Two resolutions are new, for the glob and the minimatch of
test-exclude (GHSA-3g3m-2fjr-6pw4, GHSA-g3hv-75wg-m249).

Code the new versions needed:

- js-yaml 5: load() throws on a block that holds no document, so
  parseSkillFrontmatter uses loadAll and a count. A SKILL.md with an
  empty frontmatter block stays a record without frontmatter instead
  of becoming MALFORMED_FRONTMATTER (4 tests). The dumper option
  quotingType is now quoteStyle.
- aws-cdk 2.1148.0 ships bootstrap template version 33: the template
  is regenerated. Its policies and the bootstrap versions the app
  requires do not change.
- commander 15 is ES modules only and Jest 30 cannot require() one on
  Node 22: ts-jest compiles that one package for the cli suites (the
  coverage contract carries the same key), and a new test loads the
  real package from a plain Node process.
- eslint-plugin-import-x 4.18 sorts parent imports before sibling
  imports: import lines move in 24 files, nothing else.
- Starlight 0.42 no longer ships its virtual-module declarations:
  docs/src/env.d.ts declares the five modules the overrides use.
- osv-scanner 2.7.1 renames ignoreUntil to effectiveUntil.
- engines.node is "^22.23.4 || ^24.15.0" in the root, cdk, cli and
  docs: the versions the shared lockfile installs on.

Held back: typescript 7 (no JavaScript compiler API, which ts-jest,
typescript-eslint, astro check and ts-node need), cdk-nag 3 (removes
NagSuppressions, 73 calls) and the Cedar pair (no cedarpy release on
a 4.13 or 4.14 core).
Ten packages move to their newest release that is at least seven days
old: bedrock-agentcore 1.26.0, boto3 1.44.0, claude-agent-sdk 0.2.179,
fastapi 0.162.4, mcp 2.3.0 (a major), pygments 2.21.0, pytest 9.2.0,
ruff 0.17.4, ty 0.0.100, uvicorn 0.54.0. The image moves with them:
Claude Code CLI 2.1.319 (the one the SDK bundles), mise 2026.11.6 at
its digest in place of "latest", and the python:3.13-slim digest of
Python 3.13.18.

Code the new versions needed:

- botocore 1.44.0 changes the default retry mode from legacy to
  standard (5 attempts become 3; 10 become 4 for DynamoDB).
  aws_session.py names "legacy" on both sessions and every client, so
  the agent retries as before; AWS_RETRY_MODE still wins (9 tests).
- mcp 2 replaces httpx with httpx2 and renames the result fields.
  gateway_tools.py uses streamable_http_client over an httpx2 client
  that carries the SigV4 auth and the same timeouts. With the old
  names every tool result read as successful and empty (4 tests use
  mcp's own client and types).
- Claude Code 2.1.311 and later fetch model settings from a host the
  DNS allowlist does not name: the runner sets
  CLAUDE_CODE_MODEL_CATALOG=off next to CLAUDE_CODE_USE_BEDROCK.
- ty 0.0.100 understands frozen pydantic models: seven test lines
  that assign to one on purpose carry a ty ignore, and mcp_servers is
  passed by name.

ty and pytest are now pinned exactly: an unpinned ty is what broke the
nightly lock refresh. The pydantic-settings constraint and the
starlette warning filter go with the packages that needed them.

Held back: claude-agent-sdk 0.2.180 bundles CLI 2.1.321, whose
changelog says mods written in a session turn on without asking in
bypass mode. Every task runs in bypass mode, so that release waits
for a live task that shows how such a mod meets the Cedar hooks.
1.0.489 is the newest build the package host serves on 2026-11-17:
GitHub already lists 1.0.490, but its package answers 403. The three
suites pass on it with the upgraded dependencies (12 cdk, 7 cli and
43 agent tests).

Five statements of the README were observed again on 1.0.489 and
hold: the two agent-registry refusals, the iss claim of a Cognito
token, first-login password rotation, and the 1,000-object ceiling
of a bucket. The other rows were not probed again, so the README
keeps "Recorded on emulator 1.0.481", as its procedure allows.
trivy 0.76.2, which the dependency upgrade pins, reads the list of
packages that pip vendors; 0.70.0 did not. On the pip of the base
image (26.2.2) it reports five HIGH findings, and the image scan
fails.

- The image now installs pip 26.3, which vendors urllib3 2.8.0 and
  msgpack 1.2.4. Four of the five findings are gone (CVE-2026-97687,
  CVE-2026-97689, CVE-2026-114613, GHSA-6v7p-g79w-8964).
- The fifth, CVE-2025-47273 in setuptools 70.3.0, is accepted until
  2026-12-16. pip ships only pkg_resources from setuptools, and the
  module the advisory names is not in the image. No pip release
  vendors a newer setuptools.

The scan of the rebuilt image reports nothing, both ignore entries
are in use, and the image starts and answers its health route.
- When the agent itself changed a task's status (finished it, failed it,
  or paused it to ask for an approval), it left the task's updated_at
  time untouched, so the API kept returning the moment the task had
  started to run. A task that failed after three hours was listed under
  'Needs you' on the console's Overview as updated '3h ago', a
  repository whose last task had just finished showed its last activity
  as '3h ago', and tasks left the 'Done (24h)' and 'Failed (24h)'
  counters hours too early. The agent now sets updated_at together with
  the status, as every status change made by the rest of the platform
  already does. One status change is not covered yet: the return to
  RUNNING after an approval, because open pull request #904 rewrites
  that same statement.
  Gain: Bug fixed for every reader of updated_at: the console's
  'Updated' column, a repository's last activity, the 'Done (24h)' and
  'Failed (24h)' counters, the recent-failure flag and the API field now
  show when a task finished or paused, not when it started. Until now
  the value was wrong by the task's whole running time, up to 8 hours; a
  task waiting for an approval now shows how long it has waited. About
  15 lines of agent code, and the guide's example of a completed task
  shows the corrected value.

- The user guide said that every task record has a logs_url field with a
  direct link to its CloudWatch logs, and that it can be read from the
  task status output or from the API. Nothing ever returned that field:
  not the API, the CLI or the web console. The agent stored the link in
  the database only in the rare case where its own RUNNING write came
  before the orchestrator's, and no code read it. The guide now gives
  only the instruction that works (open the log group and filter by task
  id), and the agent no longer builds or stores the link.
  Gain: The guide stops promising a field that never arrives. 62 lines
  removed and 18 added: 20 lines of agent code and the five tests of the
  deleted link builder are gone, one small test stays to show that the
  attribute is no longer stored. No reader changes behaviour, because
  there was none.

- When the agent could not store a task's final status, or its RUNNING
  status, the log line ended with the single word ClientError, which is
  the name of every AWS error. A refused permission, throttling and an
  invalid request all looked the same, and a lost final status is what
  later makes the platform fail the task as 'Agent session lost'. The
  two log lines now carry the error code and message, like the other
  status-write log lines in the same module.
  Gain: Whoever reads the agent log after a lost status write sees the
  cause (for example AccessDeniedException or ValidationException and
  its message) instead of one opaque word. 2 lines changed.

- Files that a user attaches to a task (screenshots, logs) are
  downloaded into a .attachments folder inside the repository clone the
  agent works in. Git treated them as new, untracked work: a 'git add
  -A' or 'git add .' by the agent would put the uploads into the pull
  request, a 'git clean -fd' would delete them and a 'git stash -u'
  would put them away in the middle of the task. The folder is now
  listed in the clone's local exclude file, which is never committed, so
  these commands skip the uploads. The design document already said the
  folder was ignored; now it is.
  Gain: A user's uploads can no longer reach a pull request through a
  broad git add, and a 'git clean -fd' or a 'git stash -u' no longer
  takes them away. A clean or stash that also asks for ignored files
  still removes them ('git clean -fdx', 'git stash -a'), and 'git clean
  -fdX', which kept them before, now deletes them. The end-of-task
  safety net also stops logging 'Uncommitted changes detected' for every
  task whose only untracked files are its attachments. 7 lines added to
  the agent.

Audit findings of this area not changed here: 1 deferred, 0 not
reproduced.
- When a user denies an approval request, further attempts by the agent
  that match the same rule are refused at once for a minute, without
  asking again. Each such refusal is supposed to leave an event in the
  task's event stream. For this kind of refusal the event carried the id
  of the denied rule, a field the event writer did not accept: the error
  was swallowed and no event was written. The writer now accepts the
  rule id, so the event is written and names the rule.
  Gain: Retries refused after a human denial (for example a force push
  retried on another branch) now appear in the task's event stream,
  which is what bgagent watch shows and what is kept as the audit
  record, with the id of the denied rule. Before, they left no trace
  there, only a warning in the agent log on every such retry and an
  error line after five. Six lines of product code.

- A Cedar rule from a blueprint or the registry can read the shell
  command or the file path in a request that has none. Two examples: a
  rule with no action that tests context.command, and the usual rule
  that blocks the Bash tool, extended with a test of the command. Such a
  rule passed the check at task start, and then every tool call it
  applied to was denied as an engine error: every call of the task with
  the first example, every shell command with the second. The check at
  task start now evaluates one call of each kind of tool the engine
  tells apart (a Read, a Write, an Edit and a Bash call), through the
  routine the engine uses at run time, and treats an evaluation error
  from Cedar as a failure. The task then fails at start with Cedar's
  message, which names the missing attribute.
  Gain: A rule of this kind now fails the task at once with a clear
  error, which is what the engine's own documentation says of an invalid
  blueprint policy, instead of a task that spends its turns and budget
  on denied calls. This holds for a rule that applies to every tool
  call, to file writes, to shell commands, or to the Read, Write, Edit
  or Bash tool by name; a rule that names another tool (Glob, an MCP
  tool) is still found only when that tool is called. A task that used
  to run in spite of such a rule now fails at start as well: for example
  a read-only task whose blueprint has a rule that errors on file
  writes, which that task never evaluated. Policy text that cannot be
  parsed is now caught by this check as well. The check no longer
  repeats the engine's request names by hand and is 3 lines shorter than
  the code it replaces.

- The engine refuses to start a task whose policy it cannot use: text
  that is not Cedar, an approval timeout that is not a number, an
  unknown severity, a rule id that repeats a built-in rule of the same
  tier, and a hard rule placed among the soft rules. None of these five
  refusals had a test: each could be deleted and every test still
  passed. One parametrized test now has a row for each.
  Gain: Each of the five refusals at task start is now pinned: deleting
  any one of them fails exactly one row and no other test (shown by
  deleting each in a copy of the code). No product change; 51 lines of
  test.

- A pre-approval is checked before the one-minute memory of a recent
  denial, so that a user who denies one call and then approves the whole
  tool is not refused on the retry. This order is documented but had no
  test: the two steps could be swapped and every test still passed. A
  test now denies a call, pre-approves the tool and expects the retry to
  be allowed.
  Gain: The last unpinned pair in the order of the decision steps has a
  test: with the two steps swapped it fails (the retry is still denied)
  and no other test does. No product change; 14 lines of test.

- The object that carries the result of a policy evaluation was a
  hand-written class with its own constructor, equality, hash and text
  form. Its comment gave the reason: tests could still build it with an
  old allowed= keyword, which no product code uses. It is now a frozen
  dataclass with the same fields, defaults, keyword-only construction,
  equality and hash, and assigning to a field of a decision after it is
  built now raises an error. The tests of the old keyword are removed.
  Gain: 89 lines removed net (72 of product code, 17 of tests).
  Assigning to a field of a decision (outcome, reason, rule ids and the
  rest) between the engine that makes it and the hook that enforces it
  now raises an error; the dictionary that a cache hit carries for its
  event is still an ordinary dict. The class now has the form the design
  document gives for it.

Audit findings of this area not changed here: 2 deferred, 0 not
reproduced.
@krokoko

krokoko commented Nov 19, 2026

Copy link
Copy Markdown
Contributor Author

The two reviews: what was done with each finding

The branch is rebased onto main with the MicroVM approval lifecycle (#904). After the rebase, a read-only check of every file that both sides changed found one real interaction and a few stale texts, all corrected (below). Each finding of the two reviews was then reproduced with a failing test before it was changed, and every commit made for them was reviewed by a second agent whose brief was to refute it. Five of those reviews led to a correction of code, and the reviews of the corrections to three more changes; each correction is a commit of its own and is named with the finding it belongs to. The comment "Changes after the first reviews of this pull request" explains every commit in full.

The blocking finding

Finding Outcome
A connection string whose password holds / is no longer redacted Fixed in 061fe37, fa89344 and 19fd63c, in both scanners. Your suggestion as worded (allow / and anchor on the last @) would take https://registry.example.com:8443/@acme/pkg for a credential again, so the pattern keeps one shape as a plain URL: a host with a port whose first @ begins a path segment. Everything else behind the : is a password, as on main. The first version of the fix kept every text that begins with a port and a slash; its review showed that dates and tokens beginning with 1// have that shape, so the second commit narrowed it. Also new: a URL with an empty user (redis://:password@host) is redacted, which main did not do. In return a plain URL with a port and an @ inside a path segment (an e-mail address in the path, image@sha256:...) is redacted, as the agent's scanner did on main. The scan stays linear; two timing tests hold that.
The two scanners share no test vectors Done in the same commits: contracts/secret-scan-vectors.json holds 37 connection-string cases that both suites run. With the earlier pattern put back in either scanner alone, its suite fails.

Jira (from the live run)

Finding Outcome
The agent's answer is posted as raw Markdown Fixed in 6d04a11, 7dd356a and 5370273: inline code, bold and fenced blocks (a codeBlock node) are rendered for the answer and for the question of a held run. Two things differ from the suggestion. Bold follows Markdown's own rule, so operators and masked values the agent quotes stay as typed (x ** 2, **kwargs, ********); the existing parser took any two ** on a line as bold. Links and images in the agent's own text stay as typed. Checked against the published ADF schema, not on a live Jira site.
A red-build iteration is reported with no reason Fixed in 6d04a11: the three places that render this case call one function and name the reason, "Build or tests did not pass", the error classifier's title. A follow-up that only answered a question and changed no code keeps the completed comment with its answer (7dd356a); that case had lost its answer in this pull request.
Is "Task completed" intended for a first run with a red build? Answered, not changed. It is what the code does, and a test of this pull request pins it. On Jira it leaves the comment and the card in disagreement (the card stays In Progress); Linear and Slack show a success throughout. Giving the first run the failure frame is one expression; it is listed under "Found and not changed" for a decision.
With status_on_start, every iteration drags an In Review card back Fixed in 0218c05: an iteration keeps the check that stops a card moving backward; a task started by the trigger label still honours the override from any status. The guide states the rule and this exception.
Iterations copy the status overrides from the prior task Fixed in 0218c05 for issues outside an orchestration: the names come from the project mapping when the comment arrives. Sub-issues of an epic keep the names recorded with the epic, because the reconciler moves those cards by the recorded names.
Descriptions reach the agent as wiki markup Confirmed, not changed. A string description is passed on as typed and its images become no attachments. A converter, or a read of the issue over REST v3 at admission, is more than a fix; listed.
bgagent jira map resets onboarded_at Fixed in 0218c05; the same line in linear onboard-project and slack onboard-channel in 23acc40. The commands read the row first, so an operator needs dynamodb:GetItem on the mapping table besides PutItem.

Control plane

Finding Outcome
Poll errors are swallowed with no cap Fixed with your first suggestion, in 9e0f987 and d603d3d: a failed status read is a missed poll only when its error can clear. A read that is refused (AccessDeniedException, ValidationException, UnrecognizedClientException, InvalidSignatureException: the list main's MicroVM supervisor uses) ends the orchestration at that poll, as every failed read did before this pull request. The first answer was your second suggestion, a cap of three failed reads (51a8811); its review showed that reads throttled for a minute then failed healthy tasks, so the cap was taken out again. One limit remains in every version: a task whose row the orchestrator may not read stays RUNNING with its seat, because finalization needs the row.
Epic seeding can half-write Fixed in 51a8811: all sub-issue rows first, then the meta row in a request of its own. Not covered: sub-issues added to an epic that exists (listed).

Agent runtime

Finding Outcome
The force-push pattern is bypassed by a suffix Fixed with patterns in 7045896 and c2ce481: -f after the branch before ;, &, `
The fork-PR guard is partial Fixed in bb696b5: the agent asks GitHub for every pull request task.

CLI

Finding Outcome
A corrupt config reads as "Not configured" Fixed in 1ee9df0: the message names the file, the reason and what to do; a missing file still reads "Not configured".
Upload confirm after a 504 hides the failure reason Fixed in 1ee9df0: the CLI takes the task it read as the answer and confirms again only while the task still waits for its uploads.
linear list-projects --output json exits 0 for an unreachable workspace Fixed in 6885203: exit 1 in both output modes; what is printed is unchanged.

Docs and tests

Finding Outcome
ADR-016 still describes the agent-side refresh Fixed in 3fa0407.
API_CONTRACT does not describe the pending list Fixed in 3fa0407: the window filter, the cap of 100, the 2,000 records read, 60 calls a minute, and that nothing in the response says when the list is incomplete. A response field for that is an API change; listed.
Hook behaviour that depends on the pinned CLI is asserted on the returned dict only Not done: it needs a live Claude CLI session, which this work did not start. Listed.
The scanners share no test vectors Done, see above.

Nits

Finding Outcome
Open CodeQL alert on sanitization.ts Fixed before the review: the commit refactor(hydration): show static analysis that the tag pass is repeated makes the repeated pass visible to the analysis; the alert is closed as fixed, nothing was dismissed.
registry-publish.ts returns raw AWS error messages Left: of the three calls whose text can reach a publisher, the only identifier that is not the publisher's own is the registry's bare id (no ARN, account id or request id). A tested patch that withholds the id is ready if you want it.
Two tests build a stack inside the test Left: each stack has a configuration of its own and is built once, for that one test.
task-orchestrator.ts still cites durable SDK 1.1.3 Removed with the two esbuild options it explained (3fa0407): they are dead since SDK 1.1.6 and on 3.0.0. One effect to know: the removed banner stood in front of the bundle's "use strict", so the orchestrator now runs in strict mode like the other handlers. Both bundles load in Node 22 and 24; no test of the repository runs a Lambda bundle, so this is on the list for a deployed stack.

The automated review

Item Outcome
Session start: a failed session_started write starts more sessions Fixed in 51a8811 for AgentCore and ECS (six start calls before, one after); #904 had closed it for MicroVM.
Linear setup skips the workspace check when the URL name matches Fixed in 6885203 and 57c8384: setup and add-workspace compare the workspace a slug is registered to with the one just authorized, whatever the URL key.
Linear removal races a reconnect Fixed in fe323bd: the revoke applies only to the installation that was read. Run against a DynamoDB engine by its reviewer: without the parentheses the commit adds, the engine accepts the revoke in every set-up-again case.
Upload retries: the wrong file, and a second confirmation Fixed in 1ee9df0 (pairing by attachment id; the task that was read is the answer).
Gateway tool errors arrive as success Fixed in bb696b5: the handler returns is_error, and a test goes through the SDK's own server.
Attachments on a shared agent server Fixed in bb696b5: a directory per task.

From the rebase

What Outcome
This branch's re-read before a session start ran in front of #904's MicroVM start claim Fixed in 9e0f987: a replayed MicroVM start for a task that is already over now stops the MicroVM the first run launched (before: it ran on until its 8-hour limit). The re-read is skipped for MicroVM and is a consistent read for the other backends.
The return to RUNNING after an approval did not set updated_at Fixed in 536a1a5; this branch had left it for #904.
Stale numbers and comments (complexity records that #904's code outgrew, a docstring about the probed Claude CLI version, line references in the developer guide, a knip entry) Corrected in 536a1a5, ba6f73a, 7ddfd94, b6c89a6 and a5112dd; b8f1297 adds an emulator assertion for the updated_at of a resume.

The request to split the pull request

Not addressed in this round: the pull request is still one. The dependency upgrade is in the first commits of the branch.

@krokoko
krokoko requested a review from ayushtr-aws November 19, 2026 14:25
ayushtr-aws
ayushtr-aws previously approved these changes Nov 19, 2026

@ayushtr-aws ayushtr-aws left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Verdict: approve with comments

The round-one blocker is fixed and I found nothing else that should hold the merge. One redaction gap below should be closed before or right after merge; everything else is non-blocking. integ-smoke is still waiting for admin approval.

This round covers the 26 commits after 66076b0e (head 19fd63c6, rebased onto #904). I read them and ran the affected suites and both scanners locally. I did not redeploy or re-run the Jira flow against a live site.

Round-one blocker: fixed

postgres://admin:abc/def+ghiJKL@db.internal:5432/app is redacted again by both scanners. contracts/secret-scan-vectors.json passes 37/37 at head and 14/37 with the earlier pattern, and seven adversarial inputs of 100 to 440 KB scale linearly.

Should fix, not holding the merge

A URL password that holds an apostrophe is not redacted — agent/src/output_scanner.py:130-132.

  • DATABASE_URL=postgres://admin:aB3'xY9zQ@db.internal:5432/app becomes [REDACTED-CONNECTION_STRING] on main and is left as it is at head (scan_tool_output on both). The three password alternatives exclude ' and ".
  • This came in with 603bcfcd and was already at 66076b0e; I missed it in round one. It is the one case I found where "everything else behind the : is a password, as on main" does not hold.
  • An apostrophe is legal unencoded in URL userinfo, RDS accepts it in master passwords for every engine except Oracle, and Secrets Manager generates it by default. shell.redact_secrets has no rule for URL passwords, so nothing else catches it.
  • cdk/src/handlers/shared/deny-reason-scanner.ts:135 has the same gap. It is not a regression there, since that scanner has no connection-string rule on main, but the two patterns are kept identical.
  • Accepting a quote anywhere in the password is not the fix. It passes every test, but {"proxy":"http://localhost:8080","author":"jane@example.com"} is then replaced from the URL through the address, which is what the exclusion prevents.

Suggested: accept a quote in the password unless a closing delimiter follows it.

Q = ["'](?![\s,:;)\]}>+."'\\]|$)

[^\s@/"']+       ->  (?:[^\s@/"']|Q)+
[^\s@:"']+       ->  (?:[^\s@:"']|Q)+
[^\s@"']{1,256}  ->  (?:[^\s@"']|Q){1,256}

I tried this in both scanners:

  • test_output_scanner.py 147/147, deny-reason-scanner.test.ts 135/135, shared vectors 37/37 in both.
  • The two scanners agree on 20,000 generated URLs, and the scan stays linear.
  • 85% of 40,000 generated passwords that hold a quote are replaced (0% at head). The rest have the quote directly before one of the delimiters.
  • No additional replacement in 577 MB of files (the repository, node_modules, the agent's virtualenv), and none on nine compact JSON, HTML and JavaScript lines.

Vectors for the apostrophe and for the compact JSON line would pin both sides.

Non-blocking

Round-one items that are only partly fixed

  • Force-push gate — agent/policies/soft_deny.cedar:43-57. The two commands from round one now ask for approval. These are still allowed (run through PolicyEngine.evaluate_tool_use): git push -u -f origin feat, git push origin -f feat, git push origin +feat, git push --mirror, git -C dir push -f, (git push origin feat -f), git push origin feat "-f". In the other direction, git commit -m "docs: never use git push -f" asks for approval. A boolean such as context.git_force_push, computed in the hook from the tokenised command, would be an additional context attribute, so the existing context and the parity corpus stay as they are.
  • Failed status reads — cdk/src/handlers/shared/orchestrator.ts:970-979. A refused read now ends the orchestration and, as your reply says, the task then stays RUNNING with its seat. Two additions:
    • permanent() (shared/microvm/supervisor.ts:96-99) does not list ResourceNotFoundException, so a missing table is waited out for the whole poll window.
    • reconcile-stranded-tasks.ts covers SUBMITTED, HYDRATING and AWAITING_APPROVAL only, so nothing sweeps a RUNNING task whose orchestration has ended. A RUNNING task with a stale heartbeat would fit there, as a follow-up.
  • Session start on AgentCore and ECS — cdk/src/handlers/orchestrate-task.ts:258. The failed session_started write is fixed. A re-run of the start step for a task that is already RUNNING still starts another session, because the saved session is read back for MicroVM only. It is on your "found and not changed" list; noting it so it gets an issue.
  • Linear workspace removal — cdk/src/handlers/linear-remove-workspace.ts:375-381, 441-444. The revoke is conditioned on the installation that was read. The secret delete and the --purge row delete are not: a setup that has written its secret but not yet its row loses the secret, and one that lands between the revoke and the purge loses its row.
  • Markdown in Jira comments — cdk/src/handlers/shared/jira-feedback.ts:129-131, 174-178. The ADF was valid on about 45 inputs. Two cases still change the agent's text: a line __init__ is rendered as italic init (the whole-line _…_ rule), and src/**/*.ts and test/**/*.ts is rendered with /*.ts and test/ in bold. Still not checked on a live Jira site.

New with the fix commits

  • An iteration that changes no code on a red build always reads as completed — cdk/src/handlers/fanout-task-events.ts:1732, 1780-1782. The exemption added in 7dd356a0 tests code_changed === false alone, so "fix the failing tests" followed by no commit is posted as completed with the answer pointer, also when answer_text is empty. Suggest taking that path only when there is an answer.
  • The fork check refuses only on the literal true — agent/src/repo.py:215. Any other output with exit code 0 (empty, null) proceeds to the checkout. Suggest accepting only false and failing otherwise.
  • Attachment paths — agent/src/attachments.py:108-110, 143-144.
    • attachment_id and filename are joined to the task directory without a check that the result stays inside it. The API validates file names, so this is hardening for a payload that reaches an agent server directly.
    • The files are written 0444 and the directory of a task without a repository is not cleared, so a second download into the same task directory fails with PermissionError. I did not check whether such a task can run twice on one filesystem.
  • --output json after a 504 — cli/src/commands/submit.ts:523. A task that failed during screening is reported as text on stderr with exit code 1 and nothing on stdout. Fine for a person, a surprise for a script.

Still open from round one

  • Scope. The pull request is now 523 files and 125 commits, and it is still one. I have not read every file in either round: this approval says the blocker is closed and the fixes I checked hold, not that every change was reviewed. The split stays a preference, not a condition.
  • Hook behaviour that depends on the pinned Claude CLI is still asserted on the returned dict only, and the orchestrator bundle now runs in strict mode while no test loads a bundle. Both are on your list for a deployed stack.
  • Jira descriptions in wiki markup: confirmed and listed by you. Agreed that it is more than a fix.

Nits

  • contracts/cedar-parity/soft-deny-force-push-before-operator.json embeds the 15-pattern rule of 7045896a; the shipped rule has 14 since c2ce4816.
  • cli/src/config.ts:65: a config file that is valid JSON of the wrong shape (null, []) still ends in a raw TypeError, as on main.
  • linear onboard-project and slack onboard-channel now read the row before writing it; only the Jira guide mentions the read.
  • #1051, #1043 and #1044 have the approved label and no priority label.

What checked out

  • Every other round-one finding and every item of the automated review is fixed as described: the red-build reason, status overrides, onboarded_at, epic seeding, the fork check on every pull request task, gateway is_error (the installed SDK reads is_error), the per-task attachment directory, upload pairing by attachment id, the corrupt-config message, the Linear slug check, the list-projects exit code, ADR-016 and API_CONTRACT.md.
  • The tests of the gateway, fork, attachment and Cedar changes fail when their fix is reverted (checked in a copy).
  • Targeted suites pass locally: both scanner suites, orchestration (290), Jira and Linear (132 cdk, 186 cli, 53 agent), CLI config and submit (75), bootstrap (152). I did not run the full mise run build or the emulator tier this round.
  • Bootstrap: no new CloudFormation resource type, the six policy documents are byte-identical to main, and the template stays inside the size budget as the CDK CLI serialises it.
  • The docs mirror is in sync, shared API types are in sync across cdk, cli and web, there are no new unconditional skips, no gate is weakened and the coverage floors are raised.
  • CI is green except integ-smoke.

@isadeks isadeks left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re-review at 19fd63c6, after Ayush's review at 66076b0e.

Live test

I deployed this head to a nested Lambda MicroVM dev stack and ran:

  • The MicroVM acceptance script: 8/8 pass (normal, approve and deny after sleep, the 300/60 defaults, expiry while asleep, cancel while suspended, declined suspend, a 3-task burst).
  • A Linear issue end to end: the task started within 5 s, the start and PR comments were posted, it completed, and the ✅ reaction was added.
  • Health afterwards:
    • no concurrency seats held, and every worker terminated;
    • the orchestrator logged no errors; its one warning was the declined scenario's deliberate external suspend;
    • no errors in any of the stack's 64 functions since the deploy;
    • unauthenticated calls are still refused (401 on the task API, 403 on the registry API).

Two things the deploy diff showed that are worth knowing for existing stacks:

  • AgentCore Memory: the dependency upgrade drops Type from both MemoryStrategies. I recorded the strategy ids before the deploy. Both were unchanged and ACTIVE afterwards, so the update is in place and existing memories are kept.
  • No IAM role Description changes in this PR. The role changes are cdk-nag metadata only. Descriptions can't be updated under the least-privilege bootstrap, so that's the thing to watch on every deploy.

Not covered here: Jira (Ayush ran it end to end on an earlier head), ECS, Slack and the operator console.

Ayush's review

  • The blocker is fixed. postgres://admin:abc/def+ghiJKL@db.internal:5432/app and the other slash-in-password forms I tried are redacted. The scanner also redacts fewer harmless URLs than main: https://registry.npmjs.org:443/@aws-sdk/client-s3, http://localhost:3000/users/@me and https://medium.com:443/@author/post are redacted on main and kept here. The new contracts/secret-scan-vectors.json covers the "keep in sync" gap between the two scanners.
  • Most non-blocking items have fixes. I checked these directly:
    • Epic seeding now writes the meta row alone, after every child chunk.
    • Workspace removal now revokes only the installation it read (conditional on installed_at).
    • The fork-PR guard now refuses every fork PR.
    • Failed status reads: refused reads end the orchestration, and other failures count as missed polls.
  • Still open as far as I can see:
    • the CodeQL alert at cdk/src/handlers/shared/sanitization.ts:152;
    • raw AWS error text in cdk/src/handlers/registry-publish.ts;
    • Jira descriptions arriving as wiki markup (pre-existing).

New, non-blocking

  • The force-push gate still has bypasses. Ayush's two suffixes are gated now. I ran these through PolicyEngine.evaluate_tool_use, and all of them come back allow at this head:

    • git push origin feat -f -u
    • git push origin +feat and git push origin +HEAD:main (a forced push with no flag, straight to main)
    • git -C /workspace/repo push --force
    • git push -f (two spaces)

    Some of these are likely pre-existing, but together they support Ayush's suggestion to tokenise the command in the hook and hand Cedar a boolean, instead of adding globs.

  • A cancel during hydration now ends the durable execution as failed (orchestrate-task.ts, the new pre-start read for non-MicroVM backends). The read throws on a terminal task, the step's catch rethrows, and every retry throws again. Cleanup is correct (failTask releases nothing when its transition loses). The cost is a failed execution for an ordinary user cancel, which may count against execution-failure alarms. Ending the step without a session would let the execution finish normally. That's what the MicroVM path already does for a task that closed before its start (its catch sees the terminal task and returns null). Is the throw intended?

  • run_task now calls configure_session twice. That's safe with the per-task identity check: nothing builds a session between the two calls, and a deployed task passes the same values both times. Worth a comment, so a later change doesn't start a client in between.

Scope

I agree with Ayush that splitting out at least the dependency upgrade would make this easier to review and to revert.

isadeks
isadeks previously approved these changes Nov 19, 2026

@isadeks isadeks left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approving at 19fd63c. Live-tested on a nested Lambda MicroVM dev stack: acceptance 8/8, a Linear issue end to end, and a clean health and error scan afterwards; details are in my review above. The force-push gate and the cancel-during-hydration question are non-blocking follow-ups.

@krokoko
krokoko added this pull request to the merge queue Nov 19, 2026
@github-merge-queue
github-merge-queue Bot removed this pull request from the merge queue due to failed status checks Nov 19, 2026
The merge queue could no longer fetch github.com/microsoft/dev-tunnels v0.2.0 directly from its Git repository. Let Go resolve the pinned gh dependencies through its default module proxy and verify their checksums.
@krokoko
krokoko dismissed stale reviews from isadeks and ayushtr-aws via fe2d61c November 19, 2026 18:03
@krokoko
krokoko enabled auto-merge November 19, 2026 18:33
@krokoko
krokoko added this pull request to the merge queue Nov 19, 2026
Merged via the queue into main with commit bf52b90 Nov 19, 2026
8 of 9 checks passed
@krokoko
krokoko deleted the fix/1051-quality-audit branch November 19, 2026 19:05
nizar-lahlali pushed a commit that referenced this pull request Nov 19, 2026
Conflicts:
- agent/src/pipeline.py: main (#1052) made the repo-bound artifact rule
  use resolved_requires_repo; this branch moved the rule into
  Workflow.delivers_repo_artifact, which the push preflight shares. Kept
  the shared property and gave it main's semantics.
- cdk/src/handlers/shared/error-classifier.ts: kept main's PR_FROM_FORK
  pattern and this branch's organization-policy and archived patterns.
- agent/tests/test_repo.py: kept both new imports.
ClintEastman02 pushed a commit to ClintEastman02/sample-autonomous-cloud-coding-agents that referenced this pull request Nov 20, 2026
…s-samples#801) (aws-samples#1053)

* fix(agent): check the GitHub token can push before the agent runs (aws-samples#801)

A token can authenticate and read a repository while GitHub refuses
every write: a classic PAT with no scopes still reads public
repositories. Such a token passed clone and the whole agent run and
failed only at the final push, so the work was lost (69 turns, $1.90 in
the observed run). The orchestrator's preflight does not catch it
because the REST API's permissions.push describes the user's role on the
repository, not what the token may do.

setup_repo now runs `git push --dry-run --no-verify` to a ref that does
not exist, right after the clone and credential-helper setup. The dry run
asks GitHub for the push service through the same credential helper as
the final push, so it works for classic, fine-grained and App tokens
without parsing scopes, and sends no ref update. --no-verify keeps a
pre-push hook from the cloned repository from running.

A refusal fails the task in seconds with PushCapabilityError, whose
message starts "Token cannot push to <repo>" (the phrase the CDK error
classifier maps to "Insufficient GitHub token scopes", non-retryable)
and names the token type and the permission to add. Transient failures
and egress blocks go through the existing setup classification.
Read-only workflows (pr-review) never push and skip the check.

* chore(deps): accept the picomatch ReDoS advisory until 2026-12-16

GHSA-fc5q-39xc-vjpf (updated 2026-11-17) covers every picomatch release
through 4.0.7, the latest, so no version fixes it and security:deps
fails on every branch. The locked copies (2.3.2, 4.0.5, 4.0.7) serve
build, test and lint tooling only; no runtime dependency of cdk, cli or
web reaches picomatch, so no Lambda bundle, the CLI or the console ships
it, and the tooling matches only patterns from this repository's own
configuration. aws-samples#1052 accepts the same advisory as part of its dependency
upgrade; whichever merges second keeps one entry.

* fix(agent): harden the push preflight from review (aws-samples#801)

Review of aws-samples#1053 found cases where the first version failed a task that
worked before, or named the wrong fix:

- An empty repository: HEAD names no commit there, so pushing it failed
  before git contacted the remote. The probe is now a commit of the
  empty tree (git commit-tree), which every clone has; it writes one
  unreferenced object and leaves HEAD, the index and the tree alone.
- A ref with the probe's name already on the remote made the dry run a
  non-fast-forward refusal and blocked every task on that repository.
  The refspec is now forced; a dry run sends nothing either way.
- A 120 s timeout escaped as TimeoutExpired, classified "Build/tests
  didn't finish in time". It is now a retryable dependency_unreachable.
- A rejected credential (401) got the scope remedy and a message saying
  the token can read the repository. It is now BLOCKED[auth_failure]:
  replace the token. An archived repository and SAML SSO or IP allow
  list refusals get their own message instead of the scope remedy.
- The error quotes the stderr line that matched, not a warning git
  prints first, and each refusal emits an agent_blocked event.
- _fail_setup_command is annotated NoReturn.

Comments that misdescribed the classifier, the final push and the
pre-push hook are corrected. Tests cover each case, four of them with
real git (empty repository, existing ref, pre-push hook, nothing
changed). SECURITY.md and the user guide name the check.

* fix(agent): classify push preflight refusals by GitHub's message, not names (aws-samples#801)

The second /review_pr found that the archived and SAML checks searched
all of git's stderr, which carries the user and repository names: a
scope-less token refused for user `samlee`, or on `acme/archived-notes`,
got the SSO or archive message, and a 502 on such a repository became a
permanent refusal. Transient failures now never reach the refusal
checks, and GitHub's archive, SAML SSO and IP allow list messages are
matched as whole phrases on remote: lines only.

- The archived and organization-policy refusals no longer carry the
  "Token cannot push to" phrase, which the classifier titles
  "Insufficient GitHub token scopes" with a scope remedy. Two classifier
  patterns give them their own titles and remedies.
- PushCapabilityError carries its cause, and the agent_blocked event
  follows it: an archived repository is not reported as the token's
  fault.
- A timeout says one attempt timed out instead of claiming retries, and
  logs what git printed before it.
- git's "returned error: 429" counts as transient (the clone too).
- The quoted line hides the login of "denied to <user>"; "could not read
  username" and "Invalid username or token" count as a rejected
  credential; the fine-grained remedy names the token's repository
  access.
- Comments corrected: an invalid token fails before the check, the probe
  commit is made, not found, in each clone, and the hook and 404
  rationales. The user guide's way to tell this failure from
  preflight_failed works, the SECURITY.md row follows the pipeline
  order, and the picomatch reason names the docs dependency and the
  agent image's own copy.

Tests cover each case, through the real retry loop and real git as well
(the dry run reaches the remote; the hook test pins core.hooksPath).

* fix(agent): check the task's own token, skip artifact tasks, name the scope (aws-samples#801)

From krokoko's review of aws-samples#1053:

- Setup added gh to git's credential helpers, but git asks every helper
  (system, global, local) in turn and takes the first answer: a saved
  GitHub login on a developer machine answered first, so the push check,
  and the final push, ran as that login. An empty local
  credential.helper now clears every inherited helper, URL-scoped ones
  included, before gh is added.
- A repository-bound workflow that delivers an artifact clones for
  context and never pushes, but was checked. The rule the post-hooks
  use is now Workflow.delivers_repo_artifact, and setup skips the check
  by it; an unloadable workflow is still checked, as the post-hooks
  then open a PR.
- A classic PAT needs `public_repo` for a public repository; `repo`,
  which grants every private repository its owner can reach, only for a
  private one, and either way the owner needs write access. The
  classifier carries the agent's token-specific fix into the remedy, so
  the console no longer shows fine-grained PAT advice for an App token.
- GitHub withdrew GHSA-fc5q-39xc-vjpf, and security:deps passes without
  the picomatch entry: osv-scanner.toml is back to main's.

* fix(agent): pin the push URL, scope the credential reset, follow the PR strategy (aws-samples#801)

From krokoko's second review of aws-samples#1053:

- A url.<base>.pushInsteadOf rule rewrote the push URL (to SSH) while the
  fetch URL stayed HTTPS, so the push preflight and the final push could
  use the developer's SSH key, not the task's token. Setup now sets an
  explicit HTTPS push URL, which pushInsteadOf does not rewrite, reads
  back the effective push URL and stops when an insteadOf rule still
  rewrites it.
- The credential-helper reset cleared helpers for every host. It is now
  credential.https://github.com.helper, so a login for another host in
  the same checkout keeps working.
- Git's output is redacted before it is shortened (the timeout warning,
  the refusal excerpt, the setup failure snippet): keeping the last 500
  characters of a 519-character App token removed the prefix the
  redactor matches and left the rest in the warning.
- A writeable workflow whose ensure_pr step uses the resolve strategy
  only looks up its PR. Workflow.ensure_pr_strategy is now the rule both
  the post-hooks and setup read, and setup skips the check for resolve.
- The task record keeps 1,000 characters of the error. With a long
  owner/repo and a token of no known type the message was 1,373, so the
  sentence the classifier matches was cut and the console showed the
  generic PR and Issues remedy. The remedies now say "the repository"
  instead of repeating its name: the longest message is 992 characters.

Tests: pushInsteadOf and insteadOf with real git, the scoped reset
against a second host, the 519-character token through the timeout
path, a resolve-strategy workflow, and the longest refusal both measured
in Python and classified, cut at 1,000, in the CDK suite. The new tests
fail against 8e20a76 where they cover a defect.

---------

Co-authored-by: bgagent <bgagent@noreply.github.com>
Co-authored-by: Alain Krok <alkrok@amazon.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

4 participants