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.25 - 2026-11-17

- Add a previewed worktree retire-copy command for dirty lane files already present in one declared stack commit. Verify each changed layer, preserve recovery patches and untracked files before cleanup, and keep the lane HEAD and registration. Push and release point to the preview when dirty copies block them.

## 0.47.24 - 2026-11-17

- Let stack sync report a verified, consistent adoption as a read-only no-op with the next rebuild or push previews. Keep explicit adoption guidance for stale source history. Explain why absorb cannot edit pinned history and preserve its patch while naming an existing draft as the destination.
Expand Down
6 changes: 5 additions & 1 deletion 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.24`
Current version: `0.47.25`

`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 @@ -109,6 +109,10 @@ git worktree lock --reason "Keep validated source for inspection" <captured-work
syncwheel stack push feature-a --retain-captured-worktrees "Keep validation evidence"
```

If dirty lane files are already present in one declared stack commit, preview
`worktree retire-copy LANE --reason REASON`. It proves and backs up the copy before
cleaning only those paths; see [retiring a declared lane copy](docs/worktree-retire-copy.md).

A retained captured copy must have completed native capture and remain locked.
A clean, registered active lane at the exact declared tip can also be published
with or without the retention option. Both forms preserve the active lane.
Expand Down
2 changes: 1 addition & 1 deletion VERSION
Original file line number Diff line number Diff line change
@@ -1 +1 @@
0.47.24
0.47.25
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.24<!-- 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.25<!-- 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.24<!-- syncwheel-version:end --> · MIT · a NestDevLab project</span>
<span>syncwheel v<!-- syncwheel-version:start -->0.47.25<!-- 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
59 changes: 59 additions & 0 deletions docs/worktree-retire-copy.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
# Retire a declared lane copy

A lane can retain dirty or untracked copies of files that are already committed
and declared in its target stack. Publication and release still refuse a dirty
source: matching filenames alone do not prove that its work is preserved.

Preview the exact lane and inspect the selected commit and every path:

```bash
syncwheel worktree retire-copy review-copy --reason "Files already declared"
```

The preview identifies one commit from the target stack's declared history.
Use `--commit COMMIT` to select a particular declared commit when needed. A
commit outside that history is not a valid preservation proof. Keep the same
`--personal` or `--manifest` selection on every command.

Each changed staged entry and each changed working entry must independently
match that commit's raw contents and Git mode. A matching working file cannot
hide a different staged blob. Deletions must agree with the comparison commit;
files cannot be collected from different commits to manufacture a match.
Unsupported data or metadata is refused without cleaning the lane.
Apply requires Linux no-replace rename support. The checkout, Git index, and
recovery directory must share a filesystem; unsupported layouts are refused.

Stop the lane's writers, then apply the exact reviewed digest:

```bash
syncwheel worktree retire-copy review-copy --reason "Files already declared" \
--plan-digest DIGEST --confirm-writers-stopped --apply
```

Confirmation is an operator assertion that writers have stopped. It does not
override ownership, leases, locks, changed inputs, or missing proof. The command
checks the selected manifest, lane generation, checkout and Git administration,
HEAD, index, and paths again before modifying them.

Recovery is saved outside the checkout before cleanup. The private recovery
location contains separate staged and unstaged binary patches, the original
index, and a tar archive of the verified untracked files. The command verifies
the recovery data before replacing a path. Keep the receipt and recovery files
until their owner has accepted disposal.

Only proven paths return to the frozen lane HEAD. The command does not move
HEAD, rewrite a branch, remove the worktree, release its lease, or remove a Git
retention lock. If the lane is no longer needed, preview its separate release:

```bash
syncwheel worktree release review-copy --reason "Declared copy retired"
```

Review that result before adding `--apply`. If the lane tip differs from the
stack publication tip, release the redundant lane before retrying stack push.
Other release and publication guards still apply.

If cleanup is interrupted, retain the recovery location and retry the same
apply invocation and digest. Recovery must recognize only the exact original
or already-cleaned state. A replacement file, changed index or identity, or an
unrelated lock stops the retry; it is never permission to discard the new work.
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.24",
"version": "0.47.25",
"provides": [
{
"type": "skills",
Expand Down
1 change: 1 addition & 0 deletions pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,7 @@ py-modules = [
"syncwheel_replay",
"syncwheel_desks",
"syncwheel_worktrees",
"syncwheel_retire_copy",
"syncwheel_coordination_state",
"syncwheel_publication_intents",
"syncwheel_publication",
Expand Down
137 changes: 135 additions & 2 deletions scripts/syncwheel.py
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,13 @@

import syncwheel_manifest_store as _manifest_storage
from syncwheel_desks import DeskLifecycle
from syncwheel_retire_copy import (
RetireCopy,
observed_file as retire_copy_observed_file,
remedy as retire_copy_remedy,
require_no_visible_lane_users,
stat_key as retire_copy_stat_key,
)
from syncwheel_manifest_store import (
ManifestStore,
CONTROL_MANIFEST_EXPLICIT_RECOVERY_IDENTITY_VERSION,
Expand Down Expand Up @@ -5249,7 +5256,9 @@ def governed_lane_remedy(manifest, lane, *, commit_first=False):
if not commands:
commands = primary_checkout_remedy_commands(manifest)
prefix = 'commit the lane changes, then ' if commit_first else ''
return prefix + 'Use: ' + '; '.join(commands)
duplicate = (f"If all changes are already declared, preview: {retire_copy_remedy(lane['id'])}. "
if commit_first and lane.get('target') else '')
return duplicate + prefix + 'Use: ' + '; '.join(commands)


def personal_manifest_path(repo_root, name):
Expand Down Expand Up @@ -12243,6 +12252,124 @@ def command_worktree_open(args):
return 0


def command_worktree_retire_copy(args):
repo_root, manifest_path = resolve_command_manifest_selection(args)
manifest_path = Path(os.path.abspath(manifest_path))
lane_id = safe_ref_segment(args.lane)
reason = args.reason.strip()
if not reason:
raise SyncwheelError('worktree retire-copy requires a nonempty --reason')
if args.apply and not args.confirm_writers_stopped:
raise SyncwheelError('worktree retire-copy --apply requires --confirm-writers-stopped')
if not args.apply and (args.plan_digest or args.confirm_writers_stopped):
raise SyncwheelError('--plan-digest and --confirm-writers-stopped require --apply')
common = git_common_dir(repo_root)
primary_root = Path(get_worktrees(repo_root)[0]['path']).resolve()
selection = ['--repo', str(primary_root), '--manifest', str(manifest_path)]
worktrees = _governed_worktrees(repo_root)
git_env = {'GIT_OPTIONAL_LOCKS': '0', 'GIT_NO_REPLACE_OBJECTS': '1'}
def identify():
if ('GIT_REPLACE_REF_BASE' in os.environ
or git(repo_root, 'for-each-ref', '--format=%(refname)', 'refs/replace').stdout.strip()):
raise SyncwheelError('retire-copy refuses Git replacement refs')
if 'GIT_GRAFT_FILE' in os.environ or os.path.lexists(common / 'info' / 'grafts'):
raise SyncwheelError('retire-copy refuses Git grafts')
if manifest_path.resolve() != manifest_path:
raise SyncwheelError('retire-copy requires an exact manifest path without redirects')
manifest = read_primary_authority_manifest(manifest_path)
if not manifest or manifest.get('repository_mode') != 'delivery':
raise SyncwheelError('worktree retire-copy requires a delivery manifest')
registry, _ = worktrees.load_governed_worktree_registry()
matches = [lane for lane in registry['lanes'] if lane['id'] == lane_id]
if len(matches) != 1:
raise SyncwheelError(f'unknown or ambiguous governed worktree lane: {lane_id}')
lane = matches[0]
if (
lane['state'] != 'active' or not lane.get('generation_token')
or not lane.get('target') or lane.get('pending_reason')
or any(key.startswith('cleanup_') for key in lane)
or parse_coordination_timestamp(lane.get('lease_expires_at', '')) is None
):
raise SyncwheelError('retire-copy requires an active lane with an exact generation, lease, and target stack')
if lane.get('owner') != governed_worktree_owner() or lane['owner'].startswith('unknown@'):
raise SyncwheelError('retire-copy requires the current, known lane owner')
stack = require_stack(manifest, lane['target'])
path = Path(lane['path'])
root = governed_worktree_root(repo_root, manifest)
if (
not path.is_absolute() or path.resolve() != path or not path.is_dir()
or path == root or not path.is_relative_to(root) or path == primary_root
or common.is_relative_to(path)
):
raise SyncwheelError('retire-copy requires the original governed linked worktree')
admin = worktrees.governed_worktree_admin_dir_for_path(path)
worktree = worktrees.governed_worktree_record_for_path(path)
if (not admin or str(admin) != lane.get('admin_dir') or not worktree
or worktree.get('branch') != lane['branch'] or worktree.get('prunable')
or worktree.get('locked') == governed_worktree_cleanup_lock_reason(lane)
or not worktrees.governed_worktree_registration_matches(
lane, path, admin, worktree.get('locked')
)
or admin != Path(git(path, 'rev-parse', '--absolute-git-dir').stdout.strip())
or os.path.lexists(admin / 'locked') and (admin / 'locked').is_symlink()):
raise SyncwheelError('retire-copy could not verify the original Git worktree registration')
dotgit, _ = retire_copy_observed_file(path / '.git')
if not dotgit or not stat.S_ISREG(dotgit['stat'][2]):
raise SyncwheelError('retire-copy requires a regular linked-worktree .git file')
if any(
stack['id'] in (coordination.get('locks') or {}) or local_lease_is_active(coordination)
for _, coordination in (coordination_profile(checkout)
for checkout in {repo_root, primary_root, path})
) or os.path.lexists(coordination_publication_lock_path(repo_root)):
raise SyncwheelError('retire-copy refuses an active worktree lock or coordination lease')
if Path.cwd().resolve().is_relative_to(path):
raise SyncwheelError('run retire-copy from outside the lane after stopping its writers')
require_no_visible_lane_users(path)
source_ref = f"refs/heads/{lane['branch']}"
source = ref_tip(repo_root, source_ref)
if (not source or source != worktree.get('HEAD') or source != ref_tip(path, 'HEAD')
or git(repo_root, 'symbolic-ref', '--quiet', source_ref, check=False).returncode != 1):
raise SyncwheelError('retire-copy requires the exact direct lane source ref and HEAD')
stack_tip = ref_tip(repo_root, f"refs/heads/{stack['branch']}")
if not stack_tip:
raise SyncwheelError('retire-copy requires a materialized target stack')
history = declared_stack_history(repo_root, stack)
requested = (
git(repo_root, 'rev-parse', '--verify', '--end-of-options',
f'{args.commit}^{{commit}}', env=git_env).stdout.strip() if args.commit else None
)
if not history or requested and requested not in history:
raise SyncwheelError('retire-copy comparison must be a commit declared by the lane target stack')
return {
'lane': lane, 'path': str(path), 'root': str(root),
'rootIdentity': retire_copy_stat_key(root.lstat()),
'checkoutIdentity': retire_copy_stat_key(path.lstat()),
'admin': str(admin), 'adminIdentity': retire_copy_stat_key(admin.lstat()),
'dotGit': dotgit, 'head': source, 'sourceRef': source_ref,
'retentionLock': worktree.get('locked'), 'manifest': str(manifest_path),
'manifestDigest': manifest_digest(manifest), 'stack': stack['id'], 'stackTip': stack_tip,
'declaredHistory': history, 'requestedCommit': requested,
}

operation = RetireCopy(env=managed_process_env(authorize=False), common=common,
lane_id=lane_id, reason=reason, requested_commit=args.commit,
selection=selection, identity=identify,
lock_metadata=governed_worktree_lock_metadata,
stale_lock_reason=governed_worktree_stale_lock_reason)
try:
if args.apply:
require_private_tracking_path(common, governed_worktree_lock_path(repo_root))
with worktrees.governed_worktree_registry_lock():
result = operation.apply(args.plan_digest)
else:
plan, token = operation.plan()
result = operation.output(plan, token)
except OSError as exc:
raise SyncwheelError(f'retire-copy could not complete: {exc}') from exc
print(json.dumps(result, indent=2, sort_keys=True))
return 0


def command_worktree_release(args):
repo_root = resolve_repo_root(args.repo)
manifest, manifest_path = require_manifest(repo_root, args.repo, args.manifest, args.personal)
Expand Down Expand Up @@ -12496,7 +12623,8 @@ def refuse(reason):
status = git(path, 'status', '--porcelain=v1', '--untracked-files=all',
'--ignore-submodules=none', check=False)
if status.returncode or status.stdout.strip():
refuse('tracked or untracked source changes remain')
refuse('tracked or untracked source changes remain; if already declared, preview: '
+ retire_copy_remedy(lane['id']))
tip = ref_tip(repo_root, lane['branch'])
if not target_tip or not tip or ref_tip(path, 'HEAD') != tip or (not capture and tip != target_tip):
refuse('the captured HEAD and stack publication HEAD must match exactly')
Expand Down Expand Up @@ -20615,9 +20743,13 @@ def main():
}
global SYNCWHEEL_OWNS_REF_MOVES, SYNCWHEEL_REF_AUTH_REPO
desk_release = args.func == command_stack_release_desk
retire_copy = args.func == command_worktree_retire_copy
adopted_metadata = False
# Retire-copy owns its explicit, locally journaled writes. Standard
# startup reconciliation, hooks, and implicit ref authorizations stay off.
readonly_diagnostics = (
args.func == command_worktree_list
or retire_copy
or (args.func in {command_status, command_check} and not args.fetch)
or (desk_release and not args.apply)
)
Expand Down Expand Up @@ -20879,6 +21011,7 @@ def command_handlers():
'command_worktree_lock': command_worktree_lock,
'command_worktree_open': command_worktree_open,
'command_worktree_release': command_worktree_release,
'command_worktree_retire_copy': command_worktree_retire_copy,
'command_worktree_unlock': command_worktree_unlock,
}

Expand Down
13 changes: 13 additions & 0 deletions scripts/syncwheel_cli.py
Original file line number Diff line number Diff line change
Expand Up @@ -532,6 +532,18 @@ def build_parser(commands, version):
worktree_release_p.add_argument('-j', '--json', action='store_true')
worktree_release_p.set_defaults(func=commands['command_worktree_release'])

retire_copy_p = worktree_sub.add_parser(
'retire-copy', parents=[common], help='preview cleanup of a proven duplicate lane copy',
)
retire_copy_p.add_argument('lane')
retire_copy_p.add_argument('--commit', metavar='REV', help='select one declared comparison commit')
retire_copy_p.add_argument('--reason', required=True, help='record why this duplicate is being retired')
retire_copy_p.add_argument('-a', '--apply', action='store_true')
retire_copy_p.add_argument('--plan-digest')
retire_copy_p.add_argument('--confirm-writers-stopped', action='store_true')
retire_copy_p.add_argument('-j', '--json', action='store_true', help='output JSON (the default)')
retire_copy_p.set_defaults(func=commands['command_worktree_retire_copy'])

worktree_lock_p = worktree_sub.add_parser('lock', parents=[common])
worktree_lock_p.add_argument('stack')
worktree_lock_p.set_defaults(func=commands['command_worktree_lock'])
Expand Down Expand Up @@ -1226,6 +1238,7 @@ def register(
commands['command_worktree_release'],
commands['command_gc'],
), mutates='apply', manifest_mutates='apply')
register((commands['command_worktree_retire_copy'],), mutates='apply')
register((
commands['command_coordination_claims_backfill'],
commands['command_coordination_provenance_supersede'],
Expand Down
Loading
Loading