Skip to content

feat(agentcore): optionally merge the intent branch into a unit lane before each stage - #764

Open
thenom wants to merge 3 commits into
aws-samples:mainfrom
thenom:feat/lane-sync-before-stage-759
Open

thenom wants to merge 3 commits into
aws-samples:mainfrom
thenom:feat/lane-sync-before-stage-759

Conversation

@thenom

@thenom thenom commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Closes #759

Problem

A unit lane keeps the intent branch head it was cut from until merge-back or reconciliation, and the agent never runs git. A lane still in flight can't see units merged into the intent branch after it started, or a change merged into the intent branch directly, and nothing in the platform can bring them in.

Solution

An opt-in lane sync policy, none (the default, which leaves behaviour unchanged) or before-stage, set in the same three tiers as stage skipping and PR strategy:

  • Platform default in SSM (<prefix>/lane-sync-policy), managed in Admin settings (Source control). The new Terraform variable lane_sync_policy seeds it when the parameter is created. If the parameter can't be read, intents get none and a warning is logged.
  • Per-space override on the Project vertex (lane_sync_policy: default, none or before-stage), set in Space settings (General).
  • Snapshotted at intent create onto META (laneSyncPolicy). The orchestrator forwards it in the existing run-stage-start payload, so no orchestrator steps are added or reordered, and a setting change never affects an intent already running.

The sync itself:

  • lambda/agentcore/lane-sync.js: syncLaneWithIntent reuses mergeBranchNoFf with the branch roles reversed, the same merge as reconcileLane. Per repo it fetches, resets the local unit branch onto its remote, merges origin/<intent branch> with --no-ff and pushes the unit branch.
    • A repo already up to date is a no-op.
    • A repo with uncommitted or unpushed work is skipped, because the reset would drop it.
    • A conflict is aborted and the lane left as it was; merge-back or reconciliation resolves it later, as today.
    • It never throws.
  • commands/run-stage.js calls it after the source self-heal and before the CLI starts, only for a fresh stage of a unit lane (not a resumed conversation, which keeps the tree it parked on).
  • Events v2.lane.synced, v2.lane.sync_conflict and v2.lane.sync_failed (action agent.workspace). Nothing is recorded when the lane is already up to date. The merge commit uses the reconcile kind.
  • Docs: docs/concepts/execution.md, docs/using-the-platform/platform-settings.md and docs/using-the-platform/projects.md.

Known limits: the sync happens at stage start only, so a change merged mid-stage arrives at the lane's next fresh stage. A conflicting lane carries on stale until merge-back. Each sync adds a merge commit to the unit branch, the same shape reconciliation already makes.

This and #766 both add a block to run-stage.js before the CLI starts, so whichever merges second needs a small rebase.

User experience

A Lane sync card in Admin settings (Source control) sets the platform default, and Space settings (General) can override it per space. With sync on, a lane's timeline shows "lane synced" (or a conflict) when the intent branch had moved, and the lane's next stage starts from the current intent branch.

Testing

  • lane-sync.test.js (real git: up to date, merged, conflict aborted, dirty and unpushed repos skipped) and lane-sync-broker.test.js; run-stage.test.js "lane sync" (policy off, fresh lane stage, resumed stage, non-lane runs); lane-sync-policy.test.js (resolution across the tiers); settings, projects and intents handler tests (platform setting, space override, snapshot at create, unreadable parameter); the orchestrator forwards the snapshot; the frontend card, space setting and service.
  • Rebased on main a0c36835: npm run lint (warnings only, at baseline), npm run format:check, npx tsc -b --noEmit in frontend/, and the agentcore, agents, intents, projects, shared and v2-orchestrator vitest projects plus the affected frontend suites (2,110 backend and 335 frontend tests). One projects test timed out under load in the full run and passes on its own, as on clean main.
  • Terraform: fmt -check and validate.
  • Deployed with the setting on to a test environment.

@github-actions github-actions Bot added area/agents AgentCore runtime: CLI drivers, MCP tools, workspace and Git operations area/infra Terraform, installer and deployment size/M < 1000 changed lines (lockfiles excluded) labels Nov 13, 2026
github-actions Bot added a commit that referenced this pull request Nov 13, 2026
@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

Automatically computed PR review signals (deterministic)

Complexity and branch coverage help focus review on functions and their tests; these signals are advisory.

Complexity and test coverage

14 changed JS/TS files analyzed · 5 flagged functions.
Coverage unavailable; test protection cannot be compared.

File / function Complexity Δ Branch coverage Δ Uncovered branches Depending files
🟠 lambda/v2-orchestrator/index.js:3377 — runStage / <anonymous> — → 22 — — — — 0
🟠 lambda/agentcore/lane-sync.js:67 — syncLaneWithIntent — → 21 — — — — 1
🟠 lambda/projects/index.js:1298 — handler 241 → 250 +9 — — — 0
🟠 lambda/agents/index.js:600 — handler 369 → 377 +8 — — — 0
🟠 lambda/agentcore/commands/run-stage.js:1846 — runStageAttempt 902 → 909 +7 — — — 1

🟢 Improving · 🟠 Needs attention · 🔴 High risk · 🟣 Highest risk

— = unavailable · n/a = not applicable · * = incomplete tests


Isobar repository map

PR impact map

This fixed repository map locates changed files and their possible reach through static links.
Red marks changed files; green marks static links, not proven runtime impact or a risk grade.

Isobar by r3al1tym.

Signals
  • A: lambda/agents/index.js — modified file · 6 static name-match targets.
  • B: lambda/agentcore/lane-sync.js — added file · 21 file-level import-link targets.
  • Total static reach: 67 unchanged production files; 135 unchanged test files.
  • Static reach unavailable for 5 changed files.
  • Revision: c7693ee; updated 2026-11-18 17:32 UTC.
Legend
  • ○ modified · ◇ added · × deleted. Blue markers: tests; gray markers: documentation.
  • Solid green: import-linked name matches. Dotted green: broader file-level import fallback.

Full report artifacts

github-actions Bot added a commit that referenced this pull request Nov 13, 2026
@JWThewes

Copy link
Copy Markdown
Contributor

Thanks for this one. Could we add a Space setting for this? I mean it might be cool to select that on a per Space level and not for the whole instance?

…before each stage

A unit lane keeps the intent head it was cut from until merge-back or
reconciliation, and the agent never runs git. A lane still in flight
therefore can't see units merged since it started, or a fix merged into the
intent branch directly.

With lane_sync_policy = "before-stage" (default "none", unchanged), run-stage
merges origin/<intent branch> into the unit branch before each fresh lane
stage, with the same no-ff merge reconciliation uses, and pushes it:

- A repo already up to date is a no-op; one with uncommitted or unpushed
  work is skipped; a conflict is aborted and the lane left as it was, for
  merge-back or reconciliation to resolve as before. It never throws.
- A resumed conversation keeps the tree it parked on.
- v2.lane.synced, v2.lane.sync_conflict and v2.lane.sync_failed record what
  happened; nothing is recorded when the lane is up to date.

No orchestrator steps are added: the work is inside run-stage.
…verride

Move lane_sync_policy from a runtime environment variable to the same
three-tier shape as stage skipping and PR strategy:

- Platform default in SSM (<prefix>/lane-sync-policy), managed in Admin
  settings. The lane_sync_policy Terraform variable seeds it when the
  parameter is created.
- Per-space override on the Project vertex (lane_sync_policy:
  default | none | before-stage), set in Space settings.
- The effective value is resolved at intent create and snapshotted onto
  META (laneSyncPolicy); the orchestrator forwards it in the existing
  run-stage-start payload, so no orchestrator steps change and a setting
  change never affects an intent already running.
@thenom
thenom force-pushed the feat/lane-sync-before-stage-759 branch from ea5da46 to c7693ee Compare November 18, 2026 17:13
@github-actions github-actions Bot added area/frontend React application in frontend/ area/backend Lambda APIs, lambda/shared, v2-orchestrator size/L < 3000 changed lines (lockfiles excluded) and removed size/M < 1000 changed lines (lockfiles excluded) labels Nov 18, 2026
github-actions Bot added a commit that referenced this pull request Nov 18, 2026
github-actions Bot added a commit that referenced this pull request Nov 18, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area/agents AgentCore runtime: CLI drivers, MCP tools, workspace and Git operations area/backend Lambda APIs, lambda/shared, v2-orchestrator area/frontend React application in frontend/ area/infra Terraform, installer and deployment size/L < 3000 changed lines (lockfiles excluded)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Feature]: Merge the intent branch into a unit lane before each stage, so a lane sees work merged since it started

2 participants