carson 3.27.1 → 3.29.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1551ba09ad6dd7d0d2f0341f75e764d41334085b8e27015d7dc4d4e09007a25a
-  data.tar.gz: 9abc7ea81d920afd602f444c534731e8b5b3cf2b8762da40a9ef411d9d984845
+  metadata.gz: 9d026cfc1581b568aaa9459ab21faf0d4f52d1026995b5ce62f21dca0072853a
+  data.tar.gz: '08bdaaebab6ccaf1dac6768057f55acf3833ddbe903001b2ca3934551f280bae'
 SHA512:
-  metadata.gz: 402d821608dcb4b5a448b3c6a1d9b7cf3de3415b6ab87323e035623f118d0a91e91ce50405bb25d4d608324682eff6ccdddfd7e4c13319b8e339dcc46e699dd0
-  data.tar.gz: 184128f03321ef5e59c6168a1fcea4c9a223f7d040aaeafa61661de7c0fad77fbd79549d143021c90db25cb7217d53c29eb18da46882744eaf0d85a705604eb8
+  metadata.gz: 68d7fd88800a7a2756466ae88e3be1baae2df66b25d285cd54b676b6506d1ee86c69a110bf4f040c8259fc9dc8aa623120b0150b4a73c3081460c080940bfb2b
+  data.tar.gz: 35403e45bad7632031bbc9c56a8aece6e7b3dc7eafa1c36c4f183bc7c6271beb1b39d4b35985373cb9be0baee3b8cc58491920bb2f63dcf852fb20c4198c33ed

data/.github/workflows/carson_policy.yml

@@ -27,13 +27,13 @@ jobs:
 
     steps:
       - name: Checkout host repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           path: host
           fetch-depth: 0
 
       - name: Checkout Carson runtime
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           repository: wanghailei/carson
           ref: ${{ inputs.carson_ref }}
@@ -42,7 +42,7 @@ jobs:
       - name: Setup Ruby
         uses: ruby/setup-ruby@v1
         with:
-          ruby-version: "4.0"
+          ruby-version: "3.4"
 
       - name: Validate expected version
         run: |

data/API.md

@@ -25,14 +25,14 @@ carson <command> [subcommand] [arguments]
 | Command | Purpose |
 |---|---|
 | `carson audit` | Evaluate governance status and generate report output. |
-| `carson deliver [--commit MESSAGE]` | Run Carson-owned branch delivery for the current checkout. Plain `deliver` transports existing commits only; `--commit` creates one all-dirty delivery commit first, then Carson pushes, creates or refreshes the PR, waits for merge readiness, merges when clear, and syncs local `main`. |
+| `carson deliver [--commit MESSAGE]` | Run Carson-owned branch delivery for the current checkout. Plain `deliver` transports existing commits only; `--commit` creates one all-dirty delivery commit first. Before push, Carson verifies the branch is fresh against the configured remote `main`; behind or unknown freshness blocks delivery without creating or refreshing a PR. If freshness is good, Carson pushes, creates or refreshes the PR, watches the delivery for a bounded settle window, merges when clear, syncs local `main`, and reports merge proof for the delivered branch. Non-integrated exits report `Merge deferred` or `Merge blocked` with explicit handoff commands. |
 | `carson recover --check NAME [--json]` | Run the exceptional governed recovery path when one governance-owned required check is already red on the default branch. Carson proves the named baseline failure, keeps every other gate intact, merges through the recovery path, and records a machine-readable audit event. |
 | `carson sync` | Fast-forward local `main` from configured remote when tree is clean. |
 | `carson prune` | Remove stale local branches whose upstream refs no longer exist. |
-| `carson housekeep [--json] [--dry-run]` | Attempt to sync the current repo, then reap dead worktrees, reconcile integrated delivery worktree records from the ledger, and prune stale branches. Safe cleanup still runs when sync is blocked. |
+| `carson housekeep [--json] [--dry-run]` | Attempt to sync the current repo, then reap worktrees with strong abandonment evidence, reconcile integrated delivery worktree records from the ledger, and prune stale branches. Safe cleanup still runs when sync is blocked. |
 | `carson template check` | Detect drift between managed templates and host `.github/*` files. |
 | `carson template apply` | Write canonical managed template content into host `.github/*` files. |
-| `carson status [--json]` | Show repository delivery state, including the next queued delivery and blocked-delivery summaries. Default output is Markdown/text; `--json` is the explicit machine contract. |
+| `carson status [--json]` | Show repository delivery state, including the next queued delivery and blocked-delivery summaries. For the current branch, status also reports Carson's last observed PR state and merge proof when the branch has a Carson delivery record. Default output is Markdown/text; `--json` is the explicit machine contract. |
 | `carson abandon <pr_number\|pr_url\|branch> [--json]` | Close abandoned delivery work and clean up its PR, worktree, and branch when safe. |
 | `carson worktree create <name>` | Create an isolated worktree and branch for a new stream of work. |
 | `carson worktree list [--json]` | Show every registered worktree with PR state and Carson's cleanup recommendation. |
@@ -50,23 +50,50 @@ All batch commands operate across every governed repository registered in `gover
 | `carson prune --all` | Remove stale branches across all governed repos. |
 | `carson status --all [--json]` | Portfolio-wide delivery overview per governed repository. |
 | `carson template check --all` | Read-only template drift detection across all governed repos. |
-| `carson housekeep --all [--loop SECONDS]` | Attempt sync, then reap dead worktrees, reconcile integrated delivery worktree records from the ledger, and prune across all governed repos. Safe cleanup still runs when sync is blocked. |
+| `carson housekeep --all [--loop SECONDS]` | Attempt sync, then reap worktrees with strong abandonment evidence, reconcile integrated delivery worktree records from the ledger, and prune across all governed repos. Safe cleanup still runs when sync is blocked. |
 
-`--loop SECONDS` runs the housekeep cycle continuously, sleeping SECONDS between cycles. It requires `--all`, accepts only positive integers, and exits cleanly on `Ctrl-C` with a cycle count summary.
+`--loop SECONDS` runs the housekeep cycle continuously, sleeping SECONDS between cycles. It requires `--all`, accepts only positive integers, and exits cleanly on `Ctrl-C` or `SIGTERM` with a cycle count summary.
 
 ### Govern commands
 
 | Command | Purpose |
 |---|---|
-| `carson govern [--dry-run] [--json] [--loop SECONDS]` | Portfolio-level delivery oversight: assess active deliveries, integrate ready branches, dispatch revisions, and escalate blocked work. |
+| `carson govern [--dry-run] [--json] [--loop SECONDS]` | Portfolio-level delivery oversight: assess active deliveries, integrate ready branches, dispatch revisions, and escalate blocked work. Live integrated rows include merge proof. |
 
-`--loop SECONDS` runs the govern cycle continuously, sleeping SECONDS between cycles. The loop isolates errors per cycle — a single failing cycle does not stop the daemon. `Ctrl-C` cleanly exits with a cycle count summary. SECONDS must be a positive integer.
+`--loop SECONDS` runs the govern cycle continuously, sleeping SECONDS between cycles. The loop isolates errors per cycle — a single failing cycle does not stop the daemon. `Ctrl-C` or `SIGTERM` cleanly exits with a cycle count summary. SECONDS must be a positive integer.
 
 Governed integration is fixed to `squash`. Non-squash `govern.merge.method` values are rejected by config validation.
 
 After a live integration attempt, govern reports the actual outcome. Failed merges stay held at gate instead of being reported as integrated.
 
-After CI and review pass, Carson still checks GitHub mergeability. Conflicting PRs stay held at gate with an explicit merge-conflict summary, while `BEHIND` PRs remain eligible under Carson's current squash policy.
+After CI and review pass, Carson still checks GitHub mergeability. Conflicting PRs exit as `Merge blocked` with an explicit merge-conflict summary. `BEHIND` is treated as freshness failure: Carson blocks and requires a branch refresh before it will continue.
+
+In `--json` mode, `deliver` still suppresses human output. Every JSON result now includes `watch_window_seconds`, `waited_seconds`, and `merge_attempted`; integrated exits also include a `merge_proof` object; deferred and blocked exits also include a `handoff` object with `reason`, `expectation`, and ordered `next_steps`.
+
+`status --json` extends the `branch` object with:
+
+```json
+{
+  "pull_request": {
+    "number": 299,
+    "url": "https://github.com/example/repo/pull/299",
+    "state": "MERGED",
+    "draft": false,
+    "merged_at": "2026-03-16T09:00:00Z",
+    "summary": "PR #299 is merged."
+  },
+  "merge_proof": {
+    "applicable": true,
+    "proven": true,
+    "basis": "content_identical",
+    "summary": "proven on main — 6 changed files already match main.",
+    "main_branch": "main",
+    "changed_files_count": 6
+  }
+}
+```
+
+On `main`, `branch.merge_proof` is still present with `basis: "not_applicable"`. On non-main branches with no Carson delivery record, `branch.pull_request` and `branch.merge_proof` are `null`. `status --all` remains summary-only in v1 and does not include per-repo merge proof.
 
 After a successful govern merge, Carson runs the same cleanup path as `housekeep`: sync, reap safe worktrees, then prune.
 

data/MANUAL.md

@@ -66,12 +66,12 @@ on:
 
 jobs:
   governance:
-    uses: wanghailei/carson/.github/workflows/carson_policy.yml@v3.27.1
+    uses: wanghailei/carson/.github/workflows/carson_policy.yml@v3.29.0
     secrets:
       CARSON_READ_TOKEN: ${{ secrets.CARSON_READ_TOKEN }}
     with:
-      carson_ref: "v3.27.1"
-      carson_version: "3.27.1"
+      carson_ref: "v3.29.0"
+      carson_version: "3.29.0"
       rubocop_version: "1.81.0"
 ```
 
@@ -157,16 +157,16 @@ On the governed main working tree, Carson blocks raw `git add` / `git commit` an
 
 **2. Work** — make changes, test them, and either commit normally or let Carson create the delivery commit.
 
-**3. Hand the branch to Carson** — `deliver` is the synchronous happy path. Carson pushes the branch, creates or refreshes the PR, waits for the CI and review signals it can observe, merges when the path is clear, and syncs local `main`. Plain `carson deliver` transports existing commits and blocks if the worktree is dirty. `carson deliver --commit "..."` creates one all-dirty agent-authored commit first, then continues the same delivery flow. Managed template drift is still corrected in a separate Carson-managed commit before push.
+**3. Hand the branch to Carson** — `deliver` is the synchronous happy path. Before any push, Carson verifies the branch is fresh against the configured remote `main`. If freshness is behind or unknown, delivery stops immediately and no PR is created or refreshed. If freshness is good, Carson pushes the branch, creates or refreshes the PR, watches the delivery for a bounded settle window, merges when the path is clear, syncs local `main`, and then reports merge proof for the delivered branch. If the window expires without integration, Carson exits with an explicit `Merge deferred` or `Merge blocked` handoff that states whether merge was attempted and what to run next. Plain `carson deliver` transports existing commits and blocks if the worktree is dirty. `carson deliver --commit "..."` creates one all-dirty agent-authored commit first, then continues the same delivery flow. Managed template drift is still corrected in a separate Carson-managed commit before push.
 
 ```bash
 carson deliver
 # or, if the worktree is still dirty:
 carson deliver --commit "fix: describe this delivery"
-# Output: merged into main, or held at gate with the next command
+# Output: merged into main, or an explicit deferred/blocked handoff
 ```
 
-**4. Inspect or wait when needed** — when `deliver` cannot merge immediately, `status` shows the current branch, the next queued delivery, and any blocked-delivery summaries for the repository. Keep `govern` running when you want unattended portfolio reassessment and revision dispatch across governed repositories:
+**4. Inspect or wait when needed** — when `deliver` cannot merge immediately, Carson tells you whether the PR was deferred or blocked, whether merge was attempted, and which command to run next. `status` still shows the current branch, the next queued delivery, and blocked-delivery summaries for the repository. When the current branch has a Carson delivery record, `status` also shows Carson's last observed PR state and merge proof. Keep `govern` running when you want unattended portfolio reassessment and revision dispatch across governed repositories:
 
 ```bash
 carson status
@@ -193,7 +193,7 @@ carson worktree list
 carson housekeep
 ```
 
-`housekeep` still performs safe reaping and branch pruning when `sync` cannot complete. A blocked sync no longer prevents cleanup work that has its own safety evidence.
+`housekeep` still performs safe reaping and branch pruning when `sync` cannot complete. A blocked sync no longer prevents cleanup work that has its own safety evidence. Absorbed-into-main detection is informational; Carson only auto-reaps when it also has stronger abandonment evidence such as a missing directory, merged PR, or closed abandoned PR.
 
 `housekeep` also reconciles integrated delivery worktree records from the ledger. If the recorded worktree is already gone, Carson clears the stale ledger path. If the worktree still points at the integrated head and is safe to remove, Carson reaps it and clears the ledger path in the same pass.
 
@@ -209,11 +209,13 @@ carson abandon feature/stale-work
 
 `abandon` closes the PR when it is still open, removes the matching worktree when safe, deletes the local and remote branch refs when allowed, and marks the delivery as failed in Carson's ledger.
 
-**Safety guards** — `worktree remove` blocks when:
+`abandon` is an intentional discard: committed-but-unpushed branch work does not block abandonment. Typing `carson abandon` is explicit consent to discard committed work on that branch.
+
+**Safety guards** — `abandon` blocks when:
 - Shell CWD is inside the worktree (prevents session crash).
-- Branch has unpushed commits with content that differs from main (prevents data loss).
+- Worktree has uncommitted changes (prevents accidental loss of unsaved work).
 
-After squash or rebase merge, the content matches main — removal proceeds without `--force`.
+Committed-but-unpushed work is treated as intentional discard — `abandon` proceeds. The `worktree remove` command retains its own unpushed-commit guard and `--force` override for manual cleanup outside the abandon flow.
 
 **Stale worktree recovery** — if a worktree directory is destroyed externally (for example by a raw GitHub merge/delete flow), `worktree remove`, `worktree list`, `housekeep`, and `prune` handle the stale entry gracefully: they clean up the git registration and delete the branch without error when Carson has enough evidence. Use Carson's delivery and cleanup commands instead of raw `gh pr merge --delete-branch` so the worktree directory stays intact for orderly cleanup.
 
@@ -299,7 +301,7 @@ carson housekeep --all --loop 300   # housekeep every 5 minutes
 
 `refresh --all` checks each repo for safety before operating: repos with active worktrees or uncommitted changes are skipped with clear reasons. Other batch commands attempt each repo and report failures without stopping.
 
-`housekeep --all --loop SECONDS` runs the full housekeep cycle continuously, sleeping SECONDS between passes. It requires `--all`, accepts only positive integers, and exits cleanly on `Ctrl-C` with a cycle count summary.
+`housekeep --all --loop SECONDS` runs the full housekeep cycle continuously, sleeping SECONDS between passes. It requires `--all`, accepts only positive integers, and exits cleanly on `Ctrl-C` or `SIGTERM` with a cycle count summary.
 
 **Periodic maintenance:**
 
@@ -319,15 +321,15 @@ carson govern --loop 300 --dry-run    # observe mode, no integration or revision
 
 The loop is built-in and cross-platform — no cron, launchd, or Task Scheduler required. Run it in a terminal, tmux, screen, or as a system service.
 
-Each cycle runs independently: if one cycle fails (network error, GitHub API timeout), the error is logged and the next cycle proceeds normally. Press `Ctrl-C` to stop — Carson exits cleanly with a cycle count summary.
+Each cycle runs independently: if one cycle fails (network error, GitHub API timeout), the error is logged and the next cycle proceeds normally. Press `Ctrl-C` or send `SIGTERM` to stop — Carson exits cleanly with a cycle count summary.
 
 ### Govern and Coding Agents
 
 `carson govern` dispatches coding agents (Codex or Claude) when an active delivery is blocked by CI, review, or policy feedback. The agent receives the failure context and attempts a revision. If the agent succeeds, the delivery re-enters the governance pipeline. If it fails repeatedly or times out, the delivery is escalated for human attention.
 
-After a live merge attempt, govern reports the actual outcome. Failed merges stay held at gate instead of being reported as integrated.
+After a live merge attempt, govern reports the actual outcome. Failed merges stay held at gate instead of being reported as integrated. Successful integrations also report merge proof for the landed branch.
 
-After CI and review pass, Carson still checks GitHub mergeability. Conflicting PRs stay held at gate with an explicit merge-conflict summary, while `BEHIND` PRs remain eligible under Carson's current squash policy.
+After CI and review pass, Carson still checks GitHub mergeability. Conflicting PRs exit as `Merge blocked` with an explicit merge-conflict summary. `BEHIND` is treated as a freshness failure, not a harmless squash detail: Carson blocks and requires a branch refresh before it will continue.
 
 After a successful govern merge, Carson runs the same cleanup path as `carson housekeep`: sync, reap safe worktrees, then prune.
 
@@ -359,6 +361,7 @@ These define what Carson *is*. They are not configurable.
 - **Active review** — undisposed reviewer findings block merge; feedback must be acknowledged.
 - **Self-diagnosing output** — every warning and error names what went wrong, why, and what to do next.
 - **Transparent governance** — Carson prepares everything for merge but never makes decisions without telling you.
+- **Structural-edit discipline** — coding agents must not use Python or other blind text-rewrite scripts to edit Carson's Ruby source. Ruby files are edited with scoped patches or Ruby-aware tools so structural `end` boundaries are not truncated by cross-language text munging.
 
 ### Configurable defaults
 

data/README.md

@@ -26,7 +26,7 @@ Carson lives on your workstation and in CI, never inside the repositories it gov
   ~/.carson/                     ← Carson lives here, never inside your repos
        │
        ├─ hooks ──────────────►  commit gates and command guards
-       ├─ worktree flow ──────►  create → work → deliver → clean up
+       ├─ worktree flow ──────►  create → work → deliver → housekeep
        └─ portfolio layer ────►  status --all | refresh --all | govern
 ```
 
@@ -35,6 +35,7 @@ The outsider boundary still matters: Carson governs repositories without becomin
 ## Principles
 
 - **Worktree-first** — substantive work happens in worktrees, not on `main`.
+- **Single landing path** — completed work rejoins shared truth through remote `main` via PR-based delivery.
 - **Carson-owned operations** — Carson owns worktree and delivery operations in governed repositories. Raw `git worktree add/remove`, raw `git pull --rebase`, and raw `gh pr create/merge` are blocked, and `git add` / `git commit` are blocked on the main working tree until you create a Carson worktree.
 - **Self-diagnosing output** — every block should say what happened and the exact next command.
 - **Outsider boundary** — Carson governs repositories without becoming a host-repository runtime dependency.
@@ -50,18 +51,24 @@ carson onboard your/repo/path
 carson worktree create your-worktree
 cd your/repo/path/.claude/worktrees/your-worktree
 
-# work and test, then either commit yourself or let Carson create the delivery commit
-carson deliver --commit "fix: describe this delivery"
+# work and test, then commit and hand the branch to Carson
+git add -A
+git commit -m "fix: describe this delivery"
+carson deliver
 
-# inspect cleanup recommendations once the work is landed
-carson worktree list
+# or let Carson create one all-dirty delivery commit:
+# carson deliver --commit "fix: describe this delivery"
+
+# once the delivery is integrated, clean up from the repo root
+cd your/repo/path
+carson housekeep
 ```
 
-`carson deliver` owns the normal branch-delivery path: it pushes the branch, creates or refreshes the PR, waits for the review and CI gates Carson can observe, merges when clear, and syncs local `main`. If CI or review is still pending after Carson's configured wait windows, `deliver` returns a gated state instead of merging. Use plain `carson deliver` when the branch is already committed. Use `carson deliver --commit "..."` when the worktree is dirty and Carson should create one all-dirty delivery commit first.
+`carson deliver` runs Carson-owned branch delivery. Before any push, Carson verifies that the branch is fresh against the configured remote `main`. If freshness is behind or unknown, delivery stops with an explicit block and no PR side effect. Plain `deliver` transports existing commits only; `carson deliver --commit "..."` creates one all-dirty delivery commit first, then continues the same flow. If the branch is fresh, Carson pushes it, creates or refreshes the PR, watches the delivery for a bounded settle window, merges when clear, and syncs local `main`. If the settle window expires without integration, Carson exits with an explicit `Merge deferred` or `Merge blocked` handoff instead of leaving the PR mysteriously open. Deferred and blocked exits say whether Carson attempted merge and list the next commands in order.
 
 When one Carson-governed required check is already red on the default branch and the current PR is the repair, use `carson recover --check "..."`. Recovery is the explicit exceptional path: Carson proves the baseline failure, keeps every other gate intact, records an audit event, and never teaches operators to step outside Carson first.
 
-`carson worktree list` is the visibility surface for cleanup: it shows every registered worktree, the branch, PR state, whether the content is already on `main`, and Carson's keep or reap recommendation. When work needs to be abandoned instead of landed, use `carson abandon <pr-number|pr-url|branch>` to close the PR and clean up the branch/worktree safely.
+`carson worktree list` is the visibility surface for cleanup: it shows every registered worktree, the branch, PR state, whether the content is already on `main`, and Carson's keep or reap recommendation. Content matching `main` is diagnostic, not standalone proof that a worktree is abandoned. `carson housekeep` is the main cleanup pass: sync main, reap worktrees with strong abandonment evidence (for example a missing directory, merged PR, or closed abandoned PR), and prune stale branches. When work needs to be abandoned instead of landed, use `carson abandon <pr-number|pr-url|branch>` to close the PR and clean up the branch/worktree safely.
 
 ## Portfolio Layer
 
@@ -73,7 +80,7 @@ carson refresh --all
 carson govern --dry-run
 ```
 
-`carson govern` is the portfolio layer. It reassesses active deliveries across governed repositories, dispatches revision work for blocked branches, and surfaces what needs human judgement. Governed integration is squash-only and happens one repository at a time.
+`carson govern` is the portfolio layer. It assesses active deliveries across governed repositories, integrates ready branches, dispatches revisions for blocked work, and escalates what still needs human judgement. Governed integration is squash-only and happens one repository at a time.
 
 ## Where to Read Next
 

data/RELEASE.md

@@ -5,6 +5,31 @@ Release-note scope rule:
 - `RELEASE.md` records only version deltas, breaking changes, and migration actions.
 - Operational usage guides live in `MANUAL.md` and `API.md`.
 
+## 3.29.0
+
+### What changed
+
+- **Govern and housekeep loops are clearer and safer to run unattended** — `carson govern --loop` now prints per-delivery progress hints and a sleep announcement with the next-cycle timestamp, and both `govern --loop` and `housekeep --all --loop` now stop cleanly on `SIGTERM` as well as `Ctrl-C`.
+- **Govern and worktree creation no longer mutate the user's main worktree behind their back** — govern now fetches instead of syncing/pruning after merges, worktree creation branches from the remote tracking ref instead of pulling on main, and revision dispatch now defers when the target worktree is busy or dirty.
+- **Abandon guidance now matches the actual safety contract** — `carson abandon` no longer suggests an unsupported `--force`, and committed-but-unpushed branch work no longer blocks abandonment; only dirty worktree changes do.
+- **CI and release workflows are hardened for the Node 24 transition** — GitHub Actions checkouts now use `actions/checkout@v6`, Carson includes a dedicated forced-Node-24 probe for the RubyGems credentials action before changing the release path, and the standalone review smoke script now seeds its temporary `main` branch without tripping the shared main-branch commit guard.
+
+### No migration required
+
+- Existing workflows continue to work unchanged.
+
+## 3.28.0
+
+### What changed
+
+- **Merge proof is now a first-class delivery surface** — Carson now proves whether a delivered branch's content is already on `main`, even after squash or rewritten history. `carson status` reports the current branch's last observed PR state and merge proof when Carson is tracking that branch, while `carson deliver` and live `carson govern` integrations report the same proof immediately after landing.
+- **Delivery state now preserves PR telemetry and proof for machine consumers** — the JSON ledger stores the last observed PR state, draft flag, merged timestamp, and merge-proof payload so Carson can report stable `pull_request` and `merge_proof` objects without re-querying GitHub on every status read.
+- **Delivery and worktree safety are harder to break** — sync now refuses to proceed from a detached main worktree, worktree lifecycle guards catch more partial-state failures, and govern/deliver reporting stays consistent when mergeability, freshness, and follow-up paths change underneath the branch.
+
+### No migration required
+
+- Existing workflows continue to work unchanged. Machine consumers may now see additive `merge_proof` and current-branch `pull_request` data in Carson JSON output.
+
 ## 3.27.1
 
 ### What changed

data/VERSION

@@ -1 +1 @@
-3.27.1
+3.29.0

data/lib/carson/delivery.rb

@@ -8,13 +8,16 @@ module Carson
 
 		attr_reader :repo_path, :repository, :branch, :head, :worktree_path, :status,
 			:pull_request_number, :pull_request_url, :revisions, :cause, :summary,
-			:created_at, :updated_at, :integrated_at, :superseded_at
+			:created_at, :updated_at, :integrated_at, :superseded_at,
+			:pull_request_state, :pull_request_draft, :pull_request_merged_at, :merge_proof
 
 		def initialize(
 			repo_path:, branch:, head:, worktree_path:, status:,
 			pull_request_number:, pull_request_url:, cause:, summary:,
 			created_at:, updated_at:, integrated_at:, superseded_at:,
-			revisions: [], repository: nil
+			revisions: [], repository: nil,
+			pull_request_state: nil, pull_request_draft: nil, pull_request_merged_at: nil,
+			merge_proof: nil
 		)
 			@repo_path = repo_path
 			@repository = repository
@@ -31,6 +34,10 @@ module Carson
 			@updated_at = updated_at
 			@integrated_at = integrated_at
 			@superseded_at = superseded_at
+			@pull_request_state = pull_request_state
+			@pull_request_draft = pull_request_draft
+			@pull_request_merged_at = pull_request_merged_at
+			@merge_proof = merge_proof
 		end
 
 		def key

data/lib/carson/ledger.rb

@@ -18,7 +18,10 @@ module Carson
 		attr_reader :path
 
 		# Creates or refreshes a delivery for the same branch head.
-		def upsert_delivery( repository:, branch_name:, head:, worktree_path:, pr_number:, pr_url:, status:, summary:, cause: )
+		def upsert_delivery(
+			repository:, branch_name:, head:, worktree_path:, pr_number:, pr_url:, status:, summary:, cause:,
+			pull_request_state: nil, pull_request_draft: nil, pull_request_merged_at: nil, merge_proof: nil
+		)
 			timestamp = now_utc
 
 			with_state do |state|
@@ -45,6 +48,10 @@ module Carson
 					"status" => status,
 					"pr_number" => pr_number,
 					"pr_url" => pr_url,
+					"pull_request_state" => pull_request_state,
+					"pull_request_draft" => pull_request_draft,
+					"pull_request_merged_at" => pull_request_merged_at,
+					"merge_proof" => serialise_merge_proof( merge_proof: merge_proof ),
 					"cause" => cause,
 					"summary" => summary,
 					"created_at" => created_at,
@@ -74,6 +81,22 @@ module Carson
 			build_delivery( key: key, data: data )
 		end
 
+		# Looks up the newest delivery for a branch across active and terminal states.
+		def latest_delivery( repo_path:, branch_name: )
+			state = load_state
+			repo_paths = repo_identity_paths( repo_path: repo_path )
+
+			candidates = state[ "deliveries" ].select do |_key, data|
+				repo_paths.include?( data[ "repo_path" ] ) &&
+					data[ "branch_name" ] == branch_name
+			end
+
+			return nil if candidates.empty?
+
+			key, data = candidates.max_by { |k, d| [ d[ "updated_at" ].to_s, delivery_sequence( data: d ), k ] }
+			build_delivery( key: key, data: data )
+		end
+
 		# Lists active deliveries for a repository in creation order.
 		def active_deliveries( repo_path: )
 			state = load_state
@@ -106,6 +129,10 @@ module Carson
 			status: UNSET,
 			pr_number: UNSET,
 			pr_url: UNSET,
+			pull_request_state: UNSET,
+			pull_request_draft: UNSET,
+			pull_request_merged_at: UNSET,
+			merge_proof: UNSET,
 			cause: UNSET,
 			summary: UNSET,
 			worktree_path: UNSET,
@@ -118,6 +145,10 @@ module Carson
 				data[ "status" ] = status unless status.equal?( UNSET )
 				data[ "pr_number" ] = pr_number unless pr_number.equal?( UNSET )
 				data[ "pr_url" ] = pr_url unless pr_url.equal?( UNSET )
+				data[ "pull_request_state" ] = pull_request_state unless pull_request_state.equal?( UNSET )
+				data[ "pull_request_draft" ] = pull_request_draft unless pull_request_draft.equal?( UNSET )
+				data[ "pull_request_merged_at" ] = pull_request_merged_at unless pull_request_merged_at.equal?( UNSET )
+				data[ "merge_proof" ] = serialise_merge_proof( merge_proof: merge_proof ) unless merge_proof.equal?( UNSET )
 				data[ "cause" ] = cause unless cause.equal?( UNSET )
 				data[ "summary" ] = summary unless summary.equal?( UNSET )
 				data[ "worktree_path" ] = worktree_path unless worktree_path.equal?( UNSET )
@@ -214,6 +245,10 @@ module Carson
 				status: data.fetch( "status" ),
 				pull_request_number: data[ "pr_number" ],
 				pull_request_url: data[ "pr_url" ],
+				pull_request_state: data[ "pull_request_state" ],
+				pull_request_draft: data[ "pull_request_draft" ],
+				pull_request_merged_at: data[ "pull_request_merged_at" ],
+				merge_proof: deserialise_merge_proof( merge_proof: data[ "merge_proof" ] ),
 				revisions: revisions,
 				cause: data[ "cause" ],
 				summary: data[ "summary" ],
@@ -239,6 +274,11 @@ module Carson
 		end
 
 		def migrate_legacy_state_if_needed!
+			# Skip lock acquisition entirely when no legacy SQLite file exists.
+			# Read-only file checks are safe without the lock; the migration
+			# itself is idempotent so a narrow race is harmless.
+			return unless state_path_requires_migration?
+
 			with_state_lock do |lock_file|
 				lock_file.flock( File::LOCK_EX )
 				source_path = legacy_sqlite_source_path
@@ -321,6 +361,10 @@ module Carson
 					"status" => row.fetch( "status" ),
 					"pr_number" => row.fetch( "pr_number" ),
 					"pr_url" => row.fetch( "pr_url" ),
+					"pull_request_state" => nil,
+					"pull_request_draft" => nil,
+					"pull_request_merged_at" => nil,
+					"merge_proof" => nil,
 					"cause" => row.fetch( "cause" ),
 					"summary" => row.fetch( "summary" ),
 					"created_at" => row.fetch( "created_at" ),
@@ -367,6 +411,7 @@ module Carson
 			sequence_counts = Hash.new( 0 )
 			deliveries.each_value do |data|
 				data[ "revisions" ] = Array( data[ "revisions" ] )
+				data[ "merge_proof" ] = serialise_merge_proof( merge_proof: data[ "merge_proof" ] ) if data.key?( "merge_proof" )
 				sequence = integer_or_nil( value: data[ "sequence" ] )
 				sequence_counts[ sequence ] += 1 unless sequence.nil? || sequence <= 0
 			end
@@ -511,6 +556,32 @@ module Carson
 			nil
 		end
 
+		def serialise_merge_proof( merge_proof: )
+			return nil unless merge_proof.is_a?( Hash )
+
+			{
+				"applicable" => merge_proof[ :applicable ].nil? ? merge_proof[ "applicable" ] : merge_proof[ :applicable ],
+				"proven" => merge_proof[ :proven ].nil? ? merge_proof[ "proven" ] : merge_proof[ :proven ],
+				"basis" => merge_proof[ :basis ] || merge_proof[ "basis" ],
+				"summary" => merge_proof[ :summary ] || merge_proof[ "summary" ],
+				"main_branch" => merge_proof[ :main_branch ] || merge_proof[ "main_branch" ],
+				"changed_files_count" => ( merge_proof[ :changed_files_count ] || merge_proof[ "changed_files_count" ] || 0 ).to_i
+			}
+		end
+
+		def deserialise_merge_proof( merge_proof: )
+			return nil unless merge_proof.is_a?( Hash )
+
+			{
+				applicable: merge_proof[ "applicable" ],
+				proven: merge_proof[ "proven" ],
+				basis: merge_proof[ "basis" ],
+				summary: merge_proof[ "summary" ],
+				main_branch: merge_proof[ "main_branch" ],
+				changed_files_count: merge_proof.fetch( "changed_files_count", 0 ).to_i
+			}
+		end
+
 		def now_utc
 			Time.now.utc.iso8601( 6 )
 		end

data/lib/carson/runtime/abandon.rb

@@ -44,7 +44,7 @@ module Carson
 
 				if worktree
 					remove_exit = with_captured_output do
-						worktree_remove!( worktree_path: worktree.path, json_output: false )
+						worktree_remove!( worktree_path: worktree.path, skip_unpushed: true, json_output: false )
 					end
 					unless remove_exit == EXIT_OK
 						result[ :error ] = "worktree cleanup failed for #{worktree.path}"
@@ -131,29 +131,32 @@ module Carson
 				nil
 			end
 
+			# Abandon is an intentional discard: committed-but-unpushed work
+			# does not block abandonment. Only uncommitted (dirty) worktree
+			# changes block, because those may be accidental.
 			def abandon_preflight_issue( branch:, worktree: )
 				if config.protected_branches.include?( branch )
 					return { exit_code: EXIT_BLOCK, error: "cannot abandon protected branch #{branch}", recovery: "choose a feature branch instead" }
 				end
 
 				if worktree
-					check = Worktree.remove_check( path: worktree.path, runtime: self, force: false )
+					check = Worktree.remove_check( path: worktree.path, runtime: self, force: false, skip_unpushed: true )
 					return nil if check.fetch( :status ) == :ok
 
+					recovery = check.fetch( :recovery )
+					if check.fetch( :error ) == "worktree has uncommitted changes"
+						recovery = "commit or discard the changes, then retry carson abandon #{branch}"
+					end
+
 					return {
 						exit_code: check.fetch( :exit_code ),
 						error: check.fetch( :error ),
-						recovery: check.fetch( :recovery )
+						recovery: recovery
 					}
 				end
 
 				return { exit_code: EXIT_BLOCK, error: "current branch is #{branch}", recovery: "switch to main or a different branch, then retry" } if current_branch == branch
-				return nil unless local_branch_exists?( branch: branch )
-
-				unpushed = Worktree.branch_unpushed_issue( branch: branch, worktree_path: repo_root, runtime: self )
-				return nil if unpushed.nil?
-
-				{ exit_code: EXIT_BLOCK, error: unpushed.fetch( :error ), recovery: unpushed.fetch( :recovery ) }
+				nil
 			end
 
 			def close_pull_request!( number:, result: )