Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,9 @@
# Changelog

## 0.47.19 - 2026-11-16

- Preserve another owner's live lane during stack capture and automatic cleanup. Record the stack ownership without changing the protected lane's lease, checkout, index or refs, and report which owner is keeping it. Unproven foreign lease expiry also preserves the lane.

## 0.47.18 - 2026-11-16

- Name path-scoped stack absorb with a new commit for uncommitted primary changes, reserving capture-integration for existing unowned commits. Refuse default amend on an empty stack before changing its base, metadata or worktrees. An empty recipe whose branch has moved from the base also refuses a new-commit absorb, preserving its undeclared history.
Expand Down
9 changes: 7 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
Keep many long-lived pull requests clean, rebuildable, and publishable from one
manifest.

Current version: `0.47.18`
Current version: `0.47.19`

`syncwheel` is a small CLI and workflow model for maintainers who carry several
PR branches against an upstream repository and need those branches to stay
Expand Down Expand Up @@ -401,7 +401,12 @@ lease, base, branch, target stack, mode, and any recovery ref in Git's common
directory, never in the shared manifest. Use `--into <existing-stack>` when the
destination is already known. Otherwise, after committing, use the existing
`stack create`, `stack add`, or `stack capture-integration` workflow from a
different clean checkout. Once a stack owns every lane commit, Syncwheel anchors
different clean checkout. Capturing commits from another owner's lane with a live
lease records stack ownership and reports `captured, kept: owner <owner> live`.
The lane stays active with its lease, checkout, index and refs unchanged; an
unproven foreign lease expiry is also retained. Coordinate explicit release with
its owner instead of treating capture as permission to remove their checkout.
For an eligible lane, once a stack owns every lane commit, Syncwheel anchors
the lane tip under `refs/syncwheel/recovery/lanes/...` and pushes the same tip
to `refs/syncwheel/archive/lanes/...` on the publication remote (or the
canonical remote when the publication one is not configured) before reaping
Expand Down
2 changes: 1 addition & 1 deletion VERSION
Original file line number Diff line number Diff line change
@@ -1 +1 @@
0.47.18
0.47.19
9 changes: 7 additions & 2 deletions docs/ai-agents.md
Original file line number Diff line number Diff line change
Expand Up @@ -240,6 +240,10 @@ active-active channel must use the coordination remote.
and pushed to `refs/syncwheel/archive/lanes/...` on the publication remote,
before reaping even if its registry path is outside the current root, while an
existing dirty or unknown lane must remain visible until explicitly handled
- capturing commits does not authorize removing another owner's live lane.
Keep its active state and lease, and coordinate an explicit release with its
owner when the command reports `captured, kept`. Unproven lease expiry also
retains a foreign lane
- preview `worktree release <lane> --reason <why>` before using `--apply` for a
dead or abandoned lane; apply records the reason in the ledger and refuses an
existing dirty worktree with its recovery remedy
Expand All @@ -252,8 +256,9 @@ active-active channel must use the coordination remote.
live users and foreign locks still stop cleanup; never release another owner's
lane merely because its warning is visible
- use `--dry-run` when inspecting rebuild/push commands
- prefer `reconcile` for the normal multi-device lifecycle; use raw Git only as
inspection or fallback
- prefer `reconcile` for the normal multi-device lifecycle. Raw Git is for
inspection; there is no raw-push fallback. Stop and report a Syncwheel refusal
instead of bypassing it
- for an active-active manifest, use `handoff` before taking over from another
device or agent; never bypass the coordinated publisher with `git push`
- when a publication or revision-provider check is blocked by another stack's
Expand Down
4 changes: 2 additions & 2 deletions docs/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -1826,7 +1826,7 @@
<div class="hero-stage" id="top">
<section class="hero" aria-labelledby="hero-heading">
<div class="hero-copy">
<span class="eyebrow"><span class="ai-sigil" aria-hidden="true"></span>AI-ready Git coordination <span class="hero-version">v<!-- syncwheel-version:start -->0.47.18<!-- syncwheel-version:end --></span></span>
<span class="eyebrow"><span class="ai-sigil" aria-hidden="true"></span>AI-ready Git coordination <span class="hero-version">v<!-- syncwheel-version:start -->0.47.19<!-- syncwheel-version:end --></span></span>
<h1 id="hero-heading"><span class="title-line">Move at</span><span class="title-line">machine speed.</span><span class="title-line accent">Stay in control.</span></h1>
<p class="subhead">Syncwheel coordinates every Git lane used by humans, AI agents, CI and delivery systems—without sacrificing review, safety or recovery.</p>
<div class="actions">
Expand Down Expand Up @@ -2602,7 +2602,7 @@ <h2 class="section-title">Your first verified plan in minutes.</h2>
</main>

<footer>
<span>syncwheel v<!-- syncwheel-version:start -->0.47.18<!-- syncwheel-version:end --> · MIT · a NestDevLab project</span>
<span>syncwheel v<!-- syncwheel-version:start -->0.47.19<!-- syncwheel-version:end --> · MIT · a NestDevLab project</span>
<a class="logo-link" href="https://www.nestdev.it/" aria-label="NestDevLab">
<img src="https://www.nestdev.it/assets/logo-nestdev.png" width="22" height="22" alt="">
</a>
Expand Down
2 changes: 1 addition & 1 deletion openpack.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"schemaVersion": 2,
"name": "NestDevLab/syncwheel",
"version": "0.47.18",
"version": "0.47.19",
"provides": [
{
"type": "skills",
Expand Down
12 changes: 11 additions & 1 deletion scripts/syncwheel.py
Original file line number Diff line number Diff line change
Expand Up @@ -6892,9 +6892,11 @@ def append_governed_worktree_cleanup_event(repo_root, lane, manifest_path=None):

def reconcile_governed_worktrees(
repo_root, manifest, manifest_path=None, candidate_ids=None, repair_all_paths=False,
*, protect_foreign_lanes=False,
):
return _governed_worktrees(repo_root).reconcile_governed_worktrees(
manifest, manifest_path, candidate_ids, repair_all_paths,
protect_foreign_lanes=protect_foreign_lanes,
)


Expand Down Expand Up @@ -20058,6 +20060,7 @@ def describe(lane):
return
cleanup = reconcile_governed_worktrees(
repo_root, manifest, manifest_path, candidate_ids=candidate_ids,
protect_foreign_lanes=True,
)
elif governed_worktree_mutation_requested(args):
# Record moved lane paths and finish cleanups already started, but
Expand All @@ -20068,9 +20071,13 @@ def describe(lane):
lane['id'] for lane in governed_worktree_pending_cleanup_candidates(repo_root, manifest)
if lane.get('code') != 'archive_push_failed'
}
protect_foreign = args.func in {
command_stack_capture_integration, command_stack_classify_integration,
}
options = {'protect_foreign_lanes': True} if protect_foreign else {}
cleanup = reconcile_governed_worktrees(
repo_root, manifest, manifest_path, candidate_ids=candidate_ids,
repair_all_paths=True,
repair_all_paths=True, **options,
)
# A lane whose cleanup could not take its Git worktree lock (someone
# holds it with their own lock) is intact: the cleanup stopped before
Expand Down Expand Up @@ -20744,6 +20751,9 @@ def commit_full_sha(self, *args, **kwargs):
def rev_list(self, *args, **kwargs):
return rev_list(*args, **kwargs)

def governed_worktree_owner(self):
return governed_worktree_owner()

def append_ledger_event(self, *args, **kwargs):
return append_ledger_event(*args, **kwargs)

Expand Down
44 changes: 43 additions & 1 deletion scripts/syncwheel_worktrees.py
Original file line number Diff line number Diff line change
Expand Up @@ -108,6 +108,23 @@ def governed_worktree_lane_lease_expired(lane, now):
return bool(expires and expires <= now)


def automatic_lane_cleanup_hold(lane, actor, now):
"""Require a known owner and lease before automatic capture cleanup."""
owner = lane.get('owner')
expires = parse_coordination_timestamp(lane.get('lease_expires_at'))
if not isinstance(owner, str) or not owner.strip() or expires is None:
return 'lane owner or lease is unverified'
if owner.startswith('unknown@') and owner.endswith(':0'):
return 'lane owner is unverified'
if not isinstance(actor, str) or not actor.strip() or (
actor.startswith('unknown@') and actor.endswith(':0')
):
return 'current lane owner is unverified'
if owner != actor and expires > now:
return f'owner {owner} live'
return None


def governed_worktree_pending_remedy(manifest, lane, manifest_path=None):
reason = shlex.quote(
lane.get('cleanup_event_reason')
Expand Down Expand Up @@ -252,6 +269,7 @@ def ref_tip(self, repo_root, ref): ...
def branch_exists(self, repo_root, branch): ...
def commit_full_sha(self, repo_root, ref): ...
def rev_list(self, repo_root, rev_range): ...
def governed_worktree_owner(self): ...


class WorktreeLedger(Protocol):
Expand Down Expand Up @@ -660,6 +678,8 @@ def recover_governed_worktree_registry_from_ledger(
registry,
persist,
manifest_path=None,
*,
protect_lane=None,
):
repo_root = self.repository.root
ledger = self.governed_worktree_cleanup_ledger(manifest_path)
Expand All @@ -673,6 +693,7 @@ def recover_governed_worktree_registry_from_ledger(
lane = by_id.get(lane_id)
if (
lane is not None
and not (protect_lane and protect_lane(lane))
and generation
and governed_worktree_generation_token(lane) == generation
):
Expand All @@ -696,6 +717,8 @@ def recover_governed_worktree_registry_from_ledger(
if not isinstance(recorded, dict) or not generation:
continue
lane = by_id.get(lane_id)
if protect_lane and (protect_lane(recorded) or (lane is not None and protect_lane(lane))):
continue
if lane is None:
restored = copy.deepcopy(recorded)
registry['lanes'].append(restored)
Expand Down Expand Up @@ -1289,19 +1312,24 @@ def append_governed_worktree_cleanup_event(self, lane, manifest_path=None):

def reconcile_governed_worktrees(
self, manifest, manifest_path=None, candidate_ids=None, repair_all_paths=False,
*, protect_foreign_lanes=False,
):
repo_root = self.repository.root
with self.governed_worktree_registry_lock():
self.prune_governed_worktree_stale_locks(manifest_path)
registry, _ = self.load_governed_worktree_registry()
persist = self.governed_worktree_registry_cas_persister(registry)
protect_lane = self.automatic_cleanup_hold() if protect_foreign_lanes else None
self.recover_governed_worktree_registry_from_ledger(
registry,
persist,
manifest_path,
protect_lane=protect_lane,
)
paths_updated = False
for lane in registry['lanes']:
if protect_lane and protect_lane(lane):
continue
status = self.governed_worktree_lane_status(manifest, lane)
if (
status.get('path_moved')
Expand All @@ -1319,7 +1347,7 @@ def reconcile_governed_worktrees(
reaped = []
failures = []
for lane in list(registry['lanes']):
if lane['id'] not in selected:
if lane['id'] not in selected or (protect_lane and protect_lane(lane)):
continue
completed, detail = self.reap_governed_worktree_lane(
manifest,
Expand Down Expand Up @@ -1354,17 +1382,24 @@ def governed_worktree_commit_set(self, lane):
return set()
return set(self.repository.rev_list(repo_root, f"{lane['base']}..{lane['branch']}"))

def automatic_cleanup_hold(self):
actor = self.repository.governed_worktree_owner()
now = datetime.datetime.now(datetime.timezone.utc)
return lambda lane: automatic_lane_cleanup_hold(lane, actor, now)

def capture_governed_worktrees_for_stack(self, manifest, stack_id, manifest_path=None):
repo_root = self.repository.root
stack = require_stack(manifest, stack_id)
owned = {self.repository.commit_full_sha(repo_root, commit) for commit in stack['commits']}
with self.governed_worktree_registry_lock():
registry, _ = self.load_governed_worktree_registry()
persist = self.governed_worktree_registry_cas_persister(registry)
hold = self.automatic_cleanup_hold()
self.recover_governed_worktree_registry_from_ledger(
registry,
persist,
manifest_path,
protect_lane=hold,
)
captured = []
for lane in registry['lanes']:
Expand All @@ -1373,6 +1408,13 @@ def capture_governed_worktrees_for_stack(self, manifest, stack_id, manifest_path
commits = self.governed_worktree_commit_set(lane)
if not commits or not commits.issubset(owned):
continue
reason = hold(lane)
if reason:
print(
f"WARNING: governed worktree {lane['id']} captured, kept: {reason}",
file=sys.stderr,
)
continue
lane['state'] = 'captured_pending_cleanup'
lane['captured_at'] = iso_utc_now()
reaped, detail = self.reap_governed_worktree_lane(
Expand Down
5 changes: 4 additions & 1 deletion skills/syncwheel/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -235,7 +235,10 @@ lane. `governed_worktree_capacity` can set another `limit`; only explicit
`enforcement: "error"` enforces a hard cap. After its commits are
owned through the existing `stack create`, `stack add`, or
`stack capture-integration` flow, Syncwheel stores a local recovery ref and
reaps only a clean lane. A missing lane with an expired lease or a known-dead
reaps only an eligible clean lane. Another owner's lane with a live or unproven
lease stays active and unchanged even after its commits are captured. The
command names the owner in its kept-lane diagnostic; coordinate an explicit
release with that owner. A missing lane with an expired lease or a known-dead
local owner is eligible even if its retained registry path is outside the
configured root; a dirty, unknown, or current-directory lane stays visible and
requires explicit recovery. Check governed-worktree warnings before a mutating
Expand Down
Loading
Loading