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.22 - 2026-11-16

- Register persistent stack replay desks and provide a reviewed CLI release path. Preserve the desk tip, index and working changes in verified local recovery refs before removing its checkout, with explicit selection for legacy desks. Stack archive names the desk release or pending-release remedy.

## 0.47.21 - 2026-11-16

- Keep status without fetch, check with --no-fetch, and worktree list observational on control metadata. Skip implicit startup maintenance, authorization nonce creation or cleanup, and persistent patch-ID cache writes while preserving manifest selection checks and explicit fetch behavior.
Expand Down
10 changes: 9 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.21`
Current version: `0.47.22`

`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 @@ -477,6 +477,14 @@ lanes that need attention and `--json` adds a count per health code. It is
read-only. When more than three lanes need attention, other commands print one
summary line with those counts instead of one warning per lane.

Persistent stack replay desks created by Syncwheel also appear in `worktree
list`; JSON output lists them under `desks`. Use `stack release-desk STACK`
to preview their recovery and removal before archiving a stack. The apply
requires the reviewed plan digest and confirmation that writers have stopped.
It retains the tip, index and working changes in local recovery refs before
removing the checkout. See [desk release](docs/stack-archive.md#release-a-replay-desk)
for the command sequence and the explicit path selection for older desks.

`status` without `--fetch`, `check --no-fetch`, and `worktree list` preserve
control metadata, including authorization records, persistent caches and
startup state. They do not start update maintenance or clean up stale authorization records. Delivery
Expand Down
2 changes: 1 addition & 1 deletion VERSION
Original file line number Diff line number Diff line change
@@ -1 +1 @@
0.47.21
0.47.22
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.21<!-- 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.22<!-- 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.21<!-- syncwheel-version:end --> · MIT · a NestDevLab project</span>
<span>syncwheel v<!-- syncwheel-version:start -->0.47.22<!-- 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
38 changes: 38 additions & 0 deletions docs/stack-archive.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,3 +47,41 @@ completed request is idempotent and cannot archive a newly recreated stack.
Inspect `syncwheel ledger show` for the receipt. To resume, inspect the retained
commits and create a new native stack with the reviewed endpoints; archival does
not automatically restore or apply deferred content.

## Release a replay desk

A source branch checked out in a persistent replay desk must be released before
archiving its stack. Desks created by `stack rebuild --replay-mode desk` are
registered separately from writer lanes and appear in `worktree list --json`
under `desks`. A pre-existing checkout reused during replay is not automatically
registered as a Syncwheel desk.

Stop the desk's editors, builds and other writers, then preview and apply the
same request with the returned digest:

```bash
syncwheel stack release-desk feature --reason "Release completed review checkout"
syncwheel stack release-desk feature --reason "Release completed review checkout" \
--plan-digest DIGEST --confirm-writers-stopped --apply
```

For a desk created before registration was available, verify its ownership and
add `--legacy-worktree PATH` to both commands. This explicitly selects one
checkout; a matching pathname alone does not establish ownership. The primary,
governed writer lanes and ambiguous checkouts are not eligible for this path.
Keep the same `--personal` or `--manifest` selection that identified the stack.

The preview binds the selected stack, checkout identity, source tip, index and
files. Apply rechecks those inputs, saves the tip and separate index, staged and
working state in local recovery refs, and verifies recovery before removing the
checkout and Git registration. The source branch remains available. Retain the
returned `recoveryRefs`; these are local recovery evidence, not a remote backup.

`--confirm-writers-stopped` is an operator attestation. A Git worktree lock does
not stop a process that already has a file open. Detected changes preserve the
desk or its reported quarantine instead of completing removal. Unsupported
states or data must be resolved without discarding them before release. If a
removal is interrupted, follow the printed recovery instruction for that exact
plan; a replacement checkout at the same path is not the original desk.

After a successful release, retry the original `stack archive` preview.
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.21",
"version": "0.47.22",
"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 @@ -33,6 +33,7 @@ py-modules = [
"syncwheel_coordination",
"syncwheel_journal_workflow",
"syncwheel_replay",
"syncwheel_desks",
"syncwheel_worktrees",
"syncwheel_coordination_state",
"syncwheel_publication_intents",
Expand Down
133 changes: 123 additions & 10 deletions scripts/syncwheel.py
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,7 @@
)

import syncwheel_manifest_store as _manifest_storage
from syncwheel_desks import DeskLifecycle
from syncwheel_manifest_store import (
ManifestStore,
CONTROL_MANIFEST_EXPLICIT_RECOVERY_IDENTITY_VERSION,
Expand Down Expand Up @@ -508,6 +509,7 @@
MANAGED_PUSH_SECRET_ENV = 'SYNCWHEEL_PUSH_AUTH_SECRET'
MANAGED_PUSH_AUTH_TTL_SECONDS = 60
_READONLY_DIAGNOSTICS = ContextVar('readonly_diagnostics', default=False)
_EXPLICIT_REF_AUTHORIZATION = ContextVar('explicit_ref_authorization', default=False)
SYNCWHEEL_OWNS_REF_MOVES = False
SYNCWHEEL_REF_AUTH_REPO = None
SYNCWHEEL_REF_AUTH_TTL_SECONDS = 30
Expand Down Expand Up @@ -604,7 +606,11 @@ def managed_process_env(extra=None, authorize=True):
for name in AMBIENT_GIT_LOCATION_ENV:
process_env.pop(name, None)
diagnostics = _READONLY_DIAGNOSTICS.get()
if not diagnostics and authorize and SYNCWHEEL_OWNS_REF_MOVES and SYNCWHEEL_REF_AUTH_REPO:
explicit_authorization = _EXPLICIT_REF_AUTHORIZATION.get()
if explicit_authorization:
process_env.pop(MANAGED_REF_MOVE_AUTH_ENV, None)
if (not diagnostics and not explicit_authorization and authorize
and SYNCWHEEL_OWNS_REF_MOVES and SYNCWHEEL_REF_AUTH_REPO):
process_env[MANAGED_REF_MOVE_AUTH_ENV] = authorize_ref_move(SYNCWHEEL_REF_AUTH_REPO)
if extra:
process_env.update(extra)
Expand Down Expand Up @@ -11913,16 +11919,20 @@ def command_worktree_list(args):
lane for lane in diagnostics['lanes']
if not args.problems or lane.get('code')
]
desks = _desk_lifecycle(repo_root).desks()
if args.json:
print(json.dumps({
'registryPath': diagnostics['registry_path'],
'lanes': lanes,
'desks': desks if not args.problems else [],
'counts': governed_worktree_problem_counts(diagnostics['lanes']),
}, indent=2, sort_keys=True))
return 0
if not lanes:
for desk in desks if not args.problems else ():
print(f"{desk['stack']} kind=replay-desk branch={desk['branch']}")
print(f" path: {desk['path']}")
if not lanes and (not desks or args.problems):
print('no governed worktree lanes' + (' need attention' if args.problems else ''))
return 0
for lane in lanes:
label = lane.get('id') or lane.get('branch') or lane.get('path')
print(
Expand Down Expand Up @@ -12073,6 +12083,10 @@ def command_worktree_open(args):
}
run(['git', 'worktree', 'add', '-b', branch, str(path), base], cwd=repo_root)
try:
admin = governed_worktree_admin_dir_for_path(repo_root, path)
if not admin:
raise SyncwheelError('cannot prove the new governed worktree Git administration')
lane['admin_dir'] = str(admin)
if base_ref and can_materialize:
created = git(
repo_root, 'update-ref', '--no-deref', stack_branch_ref, base,
Expand Down Expand Up @@ -15483,6 +15497,35 @@ def verify_stack_archive_proof(repo_root, proof, stack=None):
)


def command_stack_release_desk(args):
repo_root, manifest_path = resolve_command_manifest_selection(args)
manifest_path = Path(os.path.abspath(manifest_path))
require_stack_sync_metadata_paths(repo_root, manifest_path)
manifest, _ = _manifest_storage.load_manifest(repo_root, manifest_path)
if not manifest:
raise SyncwheelError(f'manifest not found: {manifest_path}')
require_delivery_manifest(manifest)
stack = require_stack(manifest, args.stack)

def require_no_writer():
current, _ = _manifest_storage.load_manifest(repo_root, manifest_path)
if not current or manifest_digest(current) != manifest_digest(manifest):
raise SyncwheelError('selected manifest changed during desk release')
roots = {repo_root, primary_authority_manifest_path(repo_root).parent.parent}
for root in roots:
_, coordination = coordination_profile(root)
if stack['id'] in (coordination.get('locks') or {}) or local_lease_is_active(coordination):
raise SyncwheelError('desk release refuses an active worktree lock or coordination lease')

require_no_writer()
try:
result = _desk_lifecycle(repo_root).release(args, manifest, manifest_path, stack, require_no_writer)
except OSError as error:
raise SyncwheelError(f'desk release could not complete: {error}') from error
print(json.dumps(result, indent=2, sort_keys=True))
return 0


def command_stack_archive(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 @@ -20448,15 +20491,22 @@ def main():
command_hooks_ref_guard,
}
global SYNCWHEEL_OWNS_REF_MOVES, SYNCWHEEL_REF_AUTH_REPO
readonly_diagnostics = args.func == command_worktree_list or (
args.func in {command_status, command_check} and not args.fetch
desk_release = args.func == command_stack_release_desk
readonly_diagnostics = (
args.func == command_worktree_list
or (args.func in {command_status, command_check} and not args.fetch)
or (desk_release and not args.apply)
)
try:
if readonly_diagnostics:
diagnostic_scope = _READONLY_DIAGNOSTICS.set(True)
if desk_release:
args.repo = args.repo or os.environ.get(ENV_REPO)
if readonly_diagnostics or desk_release:
diagnostic_scope = _READONLY_DIAGNOSTICS.set(readonly_diagnostics)
authorization_scope = _EXPLICIT_REF_AUTHORIZATION.set(desk_release and args.apply)
try:
return args.func(args)
finally:
_EXPLICIT_REF_AUTHORIZATION.reset(authorization_scope)
_READONLY_DIAGNOSTICS.reset(diagnostic_scope)
if args.func in {command_repo_tracking_set, command_repo_tracking_status}:
args.repo = args.repo or os.environ.get(ENV_REPO)
Expand Down Expand Up @@ -20537,7 +20587,7 @@ def main():
print(f'error: {exc}', file=sys.stderr)
return 2
finally:
if not readonly_diagnostics:
if not readonly_diagnostics and not desk_release:
if SYNCWHEEL_REF_AUTH_REPO:
clear_ref_authorizations(SYNCWHEEL_REF_AUTH_REPO)
SYNCWHEEL_REF_AUTH_REPO = None
Expand Down Expand Up @@ -20670,6 +20720,7 @@ def command_handlers():
'command_stack_absorb': command_stack_absorb,
'command_stack_add': command_stack_add,
'command_stack_archive': command_stack_archive,
'command_stack_release_desk': command_stack_release_desk,
'command_stack_capture_integration': command_stack_capture_integration,
'command_stack_classify_integration': command_stack_classify_integration,
'command_stack_close': command_stack_close,
Expand Down Expand Up @@ -21417,15 +21468,43 @@ def get_current_branch(self, *args, **kwargs):
def get_worktrees(self, *args, **kwargs):
return get_worktrees(*args, **kwargs)

def capture_ref_transaction(self, operations):
def binary_git(self, path, *args, input_data=None, index=None, recovery_identity=False):
env = {'GIT_OPTIONAL_LOCKS': '0'}
if index is not None:
env['GIT_INDEX_FILE'] = str(index)
if recovery_identity:
for role in ('AUTHOR', 'COMMITTER'):
env.update({f'GIT_{role}_NAME': 'Syncwheel',
f'GIT_{role}_EMAIL': 'syncwheel@example.invalid',
f'GIT_{role}_DATE': '2000-01-01T00:00:00+00:00'})
result = subprocess.run(
['git', '-c', 'commit.gpgsign=false', *args], cwd=path, input=input_data,
env=managed_process_env(env, authorize=False), capture_output=True,
)
if result.returncode:
raise SyncwheelError(result.stderr.decode(errors='replace').strip() or 'desk snapshot Git command failed')
return result.stdout

def write_desk_intent(self, path, payload):
common = git_common_dir(self.root)
require_private_tracking_path(common, path)
atomic_write_private_json(path, payload, indent=2)
fsync_directory_path(path.parent)
fsync_directory_path(path.parent.parent)

def publish_desk_recovery_refs(self, operations):
with ref_move_authorization(self.root) as nonce:
self.capture_ref_transaction(operations, {MANAGED_REF_MOVE_AUTH_ENV: nonce})

def capture_ref_transaction(self, operations, authorization=None):
commands = ['start']
for operation in operations:
commands.extend(('option no-deref', operation))
# Old-OID checks on some Git versions accept symbolic references to
# that same OID. Inspect ref kinds after Git has acquired its locks.
with tempfile.TemporaryFile(mode='w+t') as errors, subprocess.Popen(
['git', 'update-ref', '--stdin'],
cwd=self.root, env=managed_process_env(),
cwd=self.root, env=managed_process_env(authorization),
stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=errors, text=True,
) as process:
def close_transaction():
Expand Down Expand Up @@ -21545,6 +21624,36 @@ def load_ledger_events(self, *args, **kwargs):
return _manifest_storage.load_ledger_events(*args, **kwargs)

class _StackProjections:
def register_created_desk(self, repo_root, manifest_path, stack, path):
return _desk_lifecycle(repo_root).register_created(manifest_path, stack, path)

def archive_desk_remedy(self, repo_root, manifest_path, stack, worktree):
primary = primary_authority_manifest_path(repo_root).parent.parent
selected = manifest_path or primary / '.syncwheel/manifest.json'
desks = _desk_lifecycle(repo_root)
pending = desks.pending_release(selected, stack)
args = ['syncwheel', 'stack', 'release-desk', stack['id']]
if pending:
args.extend(('--reason', pending['reason']))
if pending['legacy']:
args.extend(('--legacy-worktree', pending['path']))
args.extend(('--confirm-writers-stopped', '--plan-digest', pending['planDigest'], '--apply'))
elif worktree:
worktree = Path(worktree).resolve()
if worktree == primary:
return 'preserve the primary checkout and move the stack authoring work to a separate desk'
registry, _ = _governed_worktrees(repo_root).load_governed_worktree_registry()
desks.require_no_lane(registry, stack, worktree, governed_worktree_admin_dir_for_path(repo_root, worktree))
args.extend(('--reason', 'Release the stack desk'))
if not any(item['path'] == str(Path(worktree).resolve()) and item['stack'] == stack['id']
and item['manifest'] == str(selected.resolve()) for item in desks.desks()):
args.extend(('--legacy-worktree', str(worktree)))
else:
return None
args.extend(manifest_path_remedy_options(repo_root, selected))
action = 'confirm that writers are stopped and resume' if pending else 'inspect ownership and preview'
return f'{action} with {shlex.join(args)}'

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

Expand Down Expand Up @@ -21577,6 +21686,10 @@ def command_stack_close(self, *args, **kwargs):
return command_stack_close(*args, **kwargs)


def _desk_lifecycle(repo_root):
return DeskLifecycle(_StackRepository(repo_root), _governed_worktrees(repo_root))


def _stack_lifecycle(repo_root):
return StackLifecycle(
_StackRepository(repo_root), _StackControl(), _StackLedger(),
Expand Down
13 changes: 13 additions & 0 deletions scripts/syncwheel_cli.py
Original file line number Diff line number Diff line change
Expand Up @@ -1004,6 +1004,18 @@ def build_parser(commands, version):
stack_merge_pr_p.add_argument('-j', '--json', action='store_true')
stack_merge_pr_p.set_defaults(func=commands['command_stack_merge_pr'])

stack_release_desk_p = stack_sub.add_parser(
'release-desk', parents=[common], help='preserve and release a stack replay desk',
)
stack_release_desk_p.add_argument('stack')
stack_release_desk_p.add_argument('--legacy-worktree')
stack_release_desk_p.add_argument('--reason', required=True)
stack_release_desk_p.add_argument('--confirm-writers-stopped', action='store_true')
stack_release_desk_p.add_argument('--plan-digest')
stack_release_desk_p.add_argument('-a', '--apply', action='store_true')
stack_release_desk_p.add_argument('-j', '--json', action='store_true')
stack_release_desk_p.set_defaults(func=commands['command_stack_release_desk'])

stack_archive_p = stack_sub.add_parser(
'archive', parents=[common], help='retain source history and defer a stack without delivery claims',
)
Expand Down Expand Up @@ -1162,6 +1174,7 @@ def register(
commands['command_worktree_unlock'],
), mutates='always')
register((commands['command_worktree_open'],), mutates='always', remedy=True)
register((commands['command_stack_release_desk'],), mutates='apply')
register((commands['command_stack_set'],), mutates='stack-set', manifest_mutates='stack-set')
register((commands['command_stack_close'], commands['command_stack_sync']), mutates='always',
manifest_mutates='always', primary_scope='metadata')
Expand Down
Loading
Loading