Worktree receipt: check required local files even when Git status is clean

[ryanroundhouse]

I built a small Python/Git receipt for checking a specific handoff gap: two worktrees can be at the same commit, both show no Git status changes, and still have different local setup files.

I'm Ryan, founder of Zozo HQ. This independent review aid and post were prepared with AI assistance. It works without Zozo and is not a Zozo or Codex feature, benchmark, bug reproduction, or security sandbox.

The negative control

The included test_required_local_gap_negative_control_and_restoration creates two disposable Git worktrees at the same commit. An ignored fixture file exists in only one. Both worktrees pass the status-only observation; an explicit required-file check reports present_regular_file for one and missing for the other. Creating the file in the second worktree restores that type check, even with deliberately different bytes.

That last step matters: a file being present does not mean its configuration is correct. This check separates the questions rather than treating a clean checkout as a ready environment.

Codex's current worktree guidance scopes .worktreeinclude copying to local desktop-app-managed worktrees, not remote or self-created command-line worktrees. This helper does not parse those patterns, copy files, or test Codex's copying behavior. Independently choose the files your own task needs.

Try the fixture before inspecting a real checkout

Save the two complete code blocks below as worktree_receipt.py and test_receipt.py in the same directory outside your repository. Review them first. They use the Python standard library and Git on PATH. Run them only with trusted Python, Git and operating-system executables. The test harness uses a disposable Git configuration and clears inherited Git redirection. It is not a general sandbox.

python3 -m unittest -v test_receipt.ReceiptTests.test_required_local_gap_negative_control_and_restoration
python3 -m unittest discover -s . -p 'test*.py' -v

The tests create and remove synthetic temporary repositories; the reported validation used no customer repository, real credentials, package installation, network or model calls. The fixture launcher is POSIX-only; an unsupported platform skips these tests, which must not be counted as a pass. On November 8, 2026, the complete 48-test suite passed on Linux with Python 3.12.14 and Git 2.52.0. Native macOS, Windows and older Git versions have not been validated. Platforms missing the required descriptor-relative operations fail closed for the new file check.

Use an explicit requirement

On a trusted repository/configuration, replace the placeholder with its absolute path:

python3 worktree_receipt.py --require-local .env --require-local config/local.json /absolute/path/to/trusted/repository
python3 worktree_receipt.py --summary --require-local .env /absolute/path/to/trusted/repository

Only request a file if you independently expect it in every listed checkout. Repeated identical requirements are deduplicated. No option means no assumed local-file requirements. The original index-flag and checkout-identity observations remain separate.

• present_regular_file: observed file type only, not contents, readability, valid credentials, equal configuration, or application readiness.
• missing, symlink, nonregular, inaccessible and inspection_failed: distinct outcomes. A failed observation is not a pass or a zero count.
• not_checked: checkout missing/bare or its Git identity could not be verified.

The required-file check uses no-follow metadata operations, pins parent directories, and never opens, hashes, copies or repairs the requested file's contents. It rejects absolute/traversal/malformed requirement paths before probing. It does not follow a symlink in the requested relative path. The Git commands themselves can read tracked contents and invoke configured helpers/filters, so use trusted repositories and Git configuration only.

Exit 0 means a receipt was emitted, not that setup passed. Review every required-file state and the separate Git observations. A Git status/index failure may coexist with a completed file-type observation.

Default detailed output includes local checkout paths, branches and requested relative names. Keep it private. --summary emits fixed labels and aggregate counts, with no paths, branches, hashes, timestamps or raw output. Counts can still reveal workspace characteristics, so review them before sharing. The source's “Private review aid” description refers to handling the receipt, not restricted access to this code.

What it cannot establish

This is a non-atomic snapshot, not a complete checkout census, backup, cleanup tool or permission to delete. In the tested Git 2.52.0 --separate-git-dir layout, Git's inventory can list the administrative directory instead of the real main checkout. That row fails identity inspection; the omitted checkout stays uninspected. Compare against independently known checkout paths.

Except for the explicit type observations, it does not audit ignored files, unsaved buffers, unpushed commits, credentials or external services. It does not recurse into nested submodule indexes. Index flags are Git-observed effective flags, not direct persisted-index bits; sparse checkout can legitimately use them. No flag is cleared. Concurrent changes can invalidate the result immediately, and directory pinning does not make the whole observation atomic.

This extends the earlier review walkthrough with an executable required-file check; that post's narrower index-flag diagnostic remains unchanged. For a Zozo evaluation, the Local quickstart is the separate product path: Node 22/24/26, Git and GitHub CLI 2.94+ for GitHub; native Windows uses Claude Code rather than Codex. Local agents run as your user with your files, services stay on loopback, work stops with the launch terminal, and runtime/model access is separate. No Zozo or Codex session was executed for this receipt test.

Complete source and tests

Both blocks are the exact files from the tested receipt revision. The synthetic fixture strings in the tests are not real credentials. Test assertions cover unchanged index bytes/mtime, checkout identity, index flags, malformed paths, missing and nonregular files, symlinks, failed observations, summary privacy and the ignored-file negative control.

Copy worktree_receipt.py

#!/usr/bin/env python3
"""Private review aid for trusted repos/config; NEVER a cleanup/backup verdict."""
import argparse, datetime, errno, json, os, stat, subprocess, sys

def git(path, *args):
    env = os.environ.copy()
    # Do not inherit repository redirection from the caller.
    for k in list(env):
        if k.startswith('GIT_'):
            del env[k]
    env['GIT_OPTIONAL_LOCKS'] = '0'
    return subprocess.run(['git', '-c', 'core.fsmonitor=false', '-C', path, *args],
                          env=env, stdout=subprocess.PIPE, stderr=subprocess.PIPE,
                          check=True, timeout=30).stdout

INDEX_FLAGS = ('assume_unchanged_paths', 'skip_worktree_paths', 'either_flag_paths')

def index_flags(raw):
    """Count Git-observed flags, not raw index bits; never expose indexed names."""
    if raw and not raw.endswith(b'\0'):
        raise ValueError('incomplete index flag observation')
    assumed, skipped = set(), set()
    for entry in raw.split(b'\0')[:-1]:
        if len(entry) < 3 or entry[1:2] != b' ' or entry[:1].upper() not in (b'H', b'S', b'M', b'R', b'C', b'K', b'?', b'U'):
            raise ValueError('unexpected index flag observation')
        tag, path = entry[:1], entry[2:]
        if tag.islower():
            assumed.add(path)
        if tag.upper() == b'S':
            skipped.add(path)
    return dict(zip(INDEX_FLAGS, (len(assumed), len(skipped), len(assumed | skipped))))

LOCAL_STATES = ('present_regular_file', 'missing', 'symlink', 'nonregular',
                'inaccessible', 'inspection_failed', 'not_checked')

def validate_local(path):
    """Accept explicit portable relative names, never normalize unsafe inputs."""
    if (not isinstance(path, str) or not path or ':' in path or '\\' in path
            or any(ord(c) < 32 or ord(c) == 127 for c in path)
            or any(part in ('', '.', '..') for part in path.split('/'))):
        raise ValueError('invalid required local path')
    return path

def local_file_state(checkout, relative):
    """Metadata only. Pin parent directories; never open the requested file."""
    validate_local(relative)
    # Fail closed where descriptor-relative no-follow inspection is unavailable.
    if (not hasattr(os, 'O_NOFOLLOW') or not hasattr(os, 'O_DIRECTORY')
            or os.open not in os.supports_dir_fd or os.stat not in os.supports_dir_fd
            or os.stat not in os.supports_follow_symlinks):
        return 'inspection_failed'
    fd = None
    try:
        fd = os.open(checkout, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW)
        parts = relative.split('/')
        for i, part in enumerate(parts):
            info = os.stat(part, dir_fd=fd, follow_symlinks=False)
            if stat.S_ISLNK(info.st_mode):
                return 'symlink'
            if i == len(parts) - 1:
                return 'present_regular_file' if stat.S_ISREG(info.st_mode) else 'nonregular'
            if not stat.S_ISDIR(info.st_mode):
                return 'nonregular'
            next_fd = os.open(part, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW, dir_fd=fd)
            os.close(fd)
            fd = next_fd
        return 'inspection_failed'
    except FileNotFoundError:
        return 'missing'
    except PermissionError:
        return 'inaccessible'
    except OSError as exc:
        # Races after lstat or unsupported operations are not absence findings.
        return 'symlink' if exc.errno == errno.ELOOP else 'inspection_failed'
    finally:
        if fd is not None:
            os.close(fd)

def receipt(repo, require_local=()):
    required = tuple(dict.fromkeys(validate_local(p) for p in require_local))
    common = os.path.realpath(os.fsdecode(git(repo, 'rev-parse', '--path-format=absolute', '--git-common-dir')[:-1]))
    raw = git(repo, 'worktree', 'list', '--porcelain', '-z')
    rows = []
    for block in raw.split(b'\0\0'):
        if not block:
            continue
        fields = {}
        for field in block.split(b'\0'):
            key, _, value = field.partition(b' ')
            fields[key.decode()] = os.fsdecode(value)
        path = fields.get('worktree', '')
        row = {'path': path, 'head': fields.get('HEAD'),
               'branch': fields.get('branch'), 'detached': 'detached' in fields,
               'locked': 'locked' in fields, 'prunable': 'prunable' in fields,
               'status': 'not_observed', 'index_flags': None}
        if required:
            row['required_local_files'] = [{'path': p, 'state': 'not_checked'} for p in required]
        if 'bare' in fields:
            row['status'] = 'bare_not_checked'
        elif not os.path.isdir(path):
            row['status'] = 'missing_not_checked'
        else:
            try:
                top = os.fsdecode(git(path, 'rev-parse', '--show-toplevel')[:-1])
                if os.path.realpath(top) != os.path.realpath(path):
                    raise ValueError('worktree identity mismatch')
                actual_common = os.path.realpath(os.fsdecode(git(path, 'rev-parse', '--path-format=absolute', '--git-common-dir')[:-1]))
                actual_gitdir = os.path.realpath(os.fsdecode(git(path, 'rev-parse', '--absolute-git-dir')[:-1]))
                if actual_common != common:
                    raise ValueError('repository identity mismatch')
                # Git lists the main worktree first. Linked worktree metadata must
                # point back to this checkout, not another checkout's index/HEAD.
                if not rows:
                    if actual_gitdir != common:
                        raise ValueError('main worktree identity mismatch')
                else:
                    if actual_gitdir == common:
                        raise ValueError('linked worktree points to main repository')
                    with open(os.path.join(actual_gitdir, 'gitdir'), 'rb') as backlink:
                        linked_path = os.fsdecode(backlink.read().removesuffix(b'\n'))
                    if not os.path.isabs(linked_path):
                        linked_path = os.path.join(actual_gitdir, linked_path)
                    if os.path.realpath(linked_path) != os.path.realpath(os.path.join(path, '.git')):
                        raise ValueError('linked worktree backlink mismatch')
                if required:
                    row['required_local_files'] = [
                        {'path': p, 'state': local_file_state(path, p)} for p in required]
                changes = git(path, 'status', '--porcelain=v1', '-z',
                              '--untracked-files=all', '--ignore-submodules=none')
                flags = index_flags(git(path, 'ls-files', '--cached', '-v', '-z'))
                row['status'] = 'changes_present' if changes else 'no_status_changes_observed'
                row['index_flags'] = flags
            except (ValueError, subprocess.SubprocessError, OSError):
                row['status'] = 'inspection_failed'
        rows.append(row)
    result = {'observed_at_utc': datetime.datetime.now(datetime.timezone.utc).isoformat(),
            'warning': 'Trusted repositories and Git configuration only: Git may invoke configured helpers/filters. No cleanup commands are issued. Non-atomic inventory, not backup or permission to delete. Index flags (assume-unchanged/skip-worktree) can hide modified tracked files. Counts reflect Git-observed flags, not raw persisted index bits; nested submodule indexes are not inspected. Ignored files, unsaved buffers, unpushed commits, external services and credentials are not checked. Review/redact local paths and branch names before sharing.',
            'worktrees': rows}
    if required:
        result['warning'] = result['warning'].replace('Ignored files,', 'Other ignored files,')
        result['warning'] += ' Explicit required-local checks inspect only file-type metadata, not contents, readability, config equality or setup readiness. Required relative-path symlinks are not followed. No .worktreeinclude rules are evaluated.'
    return result

def summary(data):
    """Allowlisted aggregates only; never copy free-form repository data."""
    states = ('no_status_changes_observed', 'changes_present', 'missing_not_checked',
              'inspection_failed', 'bare_not_checked', 'not_observed')
    rows = data['worktrees']
    counts = {state: 0 for state in states}
    for row in rows:
        state = row.get('status')
        counts[state if state in states else 'not_observed'] += 1
    observed = []
    for row in rows:
        flags = row.get('index_flags')
        if not isinstance(flags, dict) or any(type(flags.get(k)) is not int or flags[k] < 0 for k in INDEX_FLAGS):
            continue
        a, s, either = (flags[k] for k in INDEX_FLAGS)
        if max(a, s) <= either <= a + s:
            observed.append(flags)
    result = {'format': 'worktree-receipt-summary-v2', 'worktree_count': len(rows),
            'status_counts': counts,
            'index_flag_observation': {
                'observed_worktrees': len(observed),
                'not_observed_worktrees': len(rows) - len(observed),
                'observed_path_counts': {k: sum(f[k] for f in observed) for k in INDEX_FLAGS} if observed else None},
            'flag_counts': {flag: sum(row.get(flag) is True for row in rows)
                            for flag in ('detached', 'locked', 'prunable')},
            'warning': 'Aggregate snapshot only. Counts still reveal workspace characteristics; review before sharing. No paths, branches, hashes, timestamps or command output are included. Not a backup, sandbox, secret detector or deletion-safety verdict. Index flags (assume-unchanged/skip-worktree) can hide modified tracked files. Counts reflect Git-observed flags, not raw persisted index bits; nested submodule indexes are not inspected. Ignored files, unsaved buffers, unpushed commits and external resources are not checked. Trusted Git configuration only; observation is non-atomic.'}

    if any('required_local_files' in row for row in rows):
        counts = dict.fromkeys(LOCAL_STATES, 0)
        for row in rows:
            entries = row.get('required_local_files', [])
            if not isinstance(entries, list):
                continue
            for entry in entries:
                state = entry.get('state') if isinstance(entry, dict) else None
                counts[state if isinstance(state, str) and state in counts else 'not_checked'] += 1
        result['warning'] = result['warning'].replace('Ignored files,', 'Other ignored files,')
        result['format'] = 'worktree-receipt-summary-v3'
        result['required_local_observation'] = {'state_counts': counts}
        result['warning'] += ' Explicit required-local counts are metadata-only observations, not content, readability or setup-readiness checks; required relative-path symlinks are not followed.'
    return result

if __name__ == '__main__':
    try:
        parser = argparse.ArgumentParser(description=__doc__)
        parser.add_argument('--summary', action='store_true',
                            help='emit only allowlisted aggregate counts; review before sharing')
        parser.add_argument('--require-local', action='append', default=[], metavar='PATH',
                            help='require a relative regular-file path in each verified checkout; repeatable, metadata only')
        parser.add_argument('repository', help='path to a trusted repository')
        args = parser.parse_args()
        data = receipt(args.repository, args.require_local)
        print(json.dumps(summary(data) if args.summary else data, indent=2, ensure_ascii=True))
    except (ValueError, subprocess.SubprocessError, OSError) as exc:
        print('Inventory failed; no cleanliness or deletion-safety conclusion. ' + type(exc).__name__, file=sys.stderr)
        sys.exit(1)

Copy test_receipt.py

import errno, os, json, pathlib, shlex, shutil, subprocess, sys, tempfile, unittest
from unittest.mock import patch
import worktree_receipt
from worktree_receipt import receipt, summary, index_flags

# Resolve once, before replacing PATH with the disposable fixture launcher.
# Python, this Git executable, /bin/sh, and the operating system must be trusted.
TRUSTED_GIT = shutil.which('git')
if TRUSTED_GIT:
    TRUSTED_GIT = os.path.realpath(TRUSTED_GIT)
GIT_LAUNCHER = '''import os, sys
git, root = sys.argv[1:3]
env = {k: v for k, v in os.environ.items() if not k.startswith('GIT_')}
env.update(HOME=os.path.join(root, 'home'),
           XDG_CONFIG_HOME=os.path.join(root, 'xdg'),
           GIT_CONFIG_NOSYSTEM='1', GIT_CONFIG_SYSTEM=os.devnull,
           GIT_CONFIG_GLOBAL=os.path.join(root, 'gitconfig'),
           GIT_ATTR_NOSYSTEM='1',
           GIT_TEMPLATE_DIR=os.path.join(root, 'empty'),
           GIT_OPTIONAL_LOCKS='0', GIT_TERMINAL_PROMPT='0')
os.execve(git, [git, *sys.argv[3:]], env)
'''

class ReceiptTests(unittest.TestCase):
    def setUp(self):
        if not TRUSTED_GIT or os.name != 'posix':
            self.skipTest('synthetic fixture isolation requires POSIX and trusted Git')
        self.tmp = tempfile.TemporaryDirectory(prefix='zozo-synthetic-')
        self.addCleanup(self.tmp.cleanup)
        self.root = pathlib.Path(self.tmp.name)
        self.original_path = os.environ.get('PATH', '')
        isolation = self.root/'git isolation'; isolation.mkdir()
        for name in ('home', 'xdg', 'empty', 'bin'):
            (isolation/name).mkdir()
        (isolation/'empty-attributes').write_text('')
        (isolation/'gitconfig').write_text(
            '[core]\n\thooksPath = '+json.dumps(str(isolation/'empty'))+
            '\n\tattributesFile = '+json.dumps(str(isolation/'empty-attributes'))+
            '\n\texcludesFile = '+json.dumps(str(isolation/'empty-attributes'))+
            '\n\tfsmonitor = false\n[commit]\n\tgpgSign = false\n'
            '[tag]\n\tgpgSign = false\n[protocol]\n\tallow = never\n')
        launcher = isolation/'bin/git'
        launcher.write_text('#!/bin/sh\nexec '+shlex.join([
            sys.executable, '-c', GIT_LAUNCHER, TRUSTED_GIT, str(isolation)])+' "$@"\n')
        launcher.chmod(0o700)
        clean_env = {k: v for k, v in os.environ.items() if not k.startswith('GIT_')}
        clean_env.update(HOME=str(isolation/'home'), XDG_CONFIG_HOME=str(isolation/'xdg'),
                         PATH=str(isolation/'bin')+os.pathsep+self.original_path)
        # The launcher reapplies isolation even when the unchanged helper removes
        # GIT_* variables, and also covers its separately executed CLI processes.
        env_patch = patch.dict(os.environ, clean_env, clear=True)
        env_patch.start(); self.addCleanup(env_patch.stop)
        self.repo = self.root/'main repo'; self.repo.mkdir()
        self.g(self.repo, 'init', '-b', 'main')
        (self.repo/'file').write_text('base\n')
        (self.repo/'.gitignore').write_text('ignored\n')
        self.g(self.repo, 'add', '.')
        self.g(self.repo, '-c', 'user.name=Fixture', '-c', 'user.email=fixture@example.invalid', 'commit', '-m', 'fixture')
    def g(self, path, *args):
        return subprocess.run(['git','-C',str(path),*args],check=True,stdout=subprocess.PIPE,stderr=subprocess.PIPE,timeout=30).stdout
    def row(self, path=None):
        return next(r for r in receipt(str(self.repo))['worktrees'] if r['path']==str(path or self.repo))

    def test_fixture_inherited_repository_overrides_cannot_mutate_another_repo(self):
        # This existing disposable repo stands in for a caller's real project.
        def snapshot():
            return {str(p.relative_to(self.repo)): (p.read_bytes(), p.stat().st_mtime_ns)
                    for p in self.repo.rglob('*') if p.is_file()}
        before = snapshot()
        variants = [
            {'GIT_DIR': str(self.repo/'.git')},
            {'GIT_DIR': str(self.repo/'.git'), 'GIT_WORK_TREE': str(self.repo),
             'GIT_COMMON_DIR': str(self.repo/'.git'),
             'GIT_INDEX_FILE': str(self.repo/'.git/index'),
             'GIT_OBJECT_DIRECTORY': str(self.repo/'.git/objects')},
        ]
        for overrides in variants:
            with self.subTest(overrides=tuple(overrides)):
                env = dict(os.environ, **overrides)
                # The child must establish its own launcher around real Git.
                env['PATH'] = str(pathlib.Path(TRUSTED_GIT).parent)+os.pathsep+self.original_path
                run = subprocess.run([
                    sys.executable, '-m', 'unittest', '-v',
                    'test_receipt.ReceiptTests.test_required_local_gap_negative_control_and_restoration'],
                    cwd=pathlib.Path(__file__).parent, env=env,
                    capture_output=True, text=True, timeout=60)
                self.assertEqual(run.returncode, 0, run.stderr)
                self.assertEqual(snapshot(), before)

    def test_fixture_inherited_configuration_and_programs_are_excluded(self):
        hostile = self.root/'disposable caller config'; hostile.mkdir()
        hooks = hostile/'hooks'; hooks.mkdir()
        template = hostile/'template'; template.mkdir()
        (template/'TEMPLATE_SENTINEL').write_text('must not be copied')
        marker = hostile/'program-executed'
        program = hostile/'program'
        program.write_text('#!/bin/sh\nprintf ran > '+shlex.quote(str(marker))+'\nexit 1\n')
        program.chmod(0o700)
        (hooks/'pre-commit').write_bytes(program.read_bytes())
        (hooks/'pre-commit').chmod(0o700)
        attributes = hostile/'attributes'; attributes.write_text('* filter=fixture\n')
        config = hostile/'gitconfig'
        config.write_text(
            '[hostile]\n\tmarker = inherited\n[core]\n\thooksPath = '+json.dumps(str(hooks))+
            '\n\tattributesFile = '+json.dumps(str(attributes))+
            '\n[init]\n\ttemplateDir = '+json.dumps(str(template))+
            '\n[commit]\n\tgpgSign = true\n[gpg]\n\tprogram = '+json.dumps(str(program))+
            '\n[filter "fixture"]\n\tclean = '+json.dumps(shlex.quote(str(program)))+
            '\n\tsmudge = '+json.dumps(shlex.quote(str(program)))+'\n\trequired = true\n')
        shutil.copyfile(config, hostile/'.gitconfig')
        env = {'HOME': str(hostile), 'XDG_CONFIG_HOME': str(hostile),
               'GIT_CONFIG_SYSTEM': str(config), 'GIT_CONFIG_GLOBAL': str(config),
               'GIT_TEMPLATE_DIR': str(template), 'GIT_CONFIG_NOSYSTEM': '0',
               'GIT_CONFIG_COUNT': '1', 'GIT_CONFIG_KEY_0': 'core.hooksPath',
               'GIT_CONFIG_VALUE_0': str(hooks)}
        with patch.dict(os.environ, env):
            repo = self.root/'isolated despite caller config'; repo.mkdir()
            self.g(repo, 'init', '-b', 'main')
            (repo/'file').write_text('unfiltered fixture bytes\n')
            self.g(repo, 'add', '.')
            self.g(repo, '-c', 'user.name=Fixture', '-c', 'user.email=fixture@example.invalid',
                   'commit', '-m', 'isolated fixture')
            self.assertFalse((repo/'.git/TEMPLATE_SENTINEL').exists())
            self.assertEqual(self.g(repo, 'show', 'HEAD:file'), b'unfiltered fixture bytes\n')
            for execute in (self.g, worktree_receipt.git):
                with self.assertRaises(subprocess.CalledProcessError):
                    execute(str(repo), 'config', '--get', 'hostile.marker')
            self.assertEqual(receipt(str(repo))['worktrees'][0]['status'], 'no_status_changes_observed')
            run = subprocess.run([sys.executable, str(pathlib.Path(__file__).with_name('worktree_receipt.py')),
                                  '--summary', str(repo)], capture_output=True, text=True, timeout=30)
            self.assertEqual(run.returncode, 0, run.stderr)
            self.assertEqual(json.loads(run.stdout)['status_counts']['no_status_changes_observed'], 1)
        self.assertFalse(marker.exists())

    def test_clean_and_no_index_write(self):
        index=self.repo/'.git/index'; before=(index.read_bytes(), index.stat().st_mtime_ns)
        self.assertEqual(self.row()['status'],'no_status_changes_observed')
        self.assertEqual(before,(index.read_bytes(),index.stat().st_mtime_ns))
    def test_modified(self):
        (self.repo/'file').write_text('changed\n'); self.assertEqual(self.row()['status'],'changes_present')
    def test_untracked(self):
        (self.repo/'new\nfile').write_text('new'); self.assertEqual(self.row()['status'],'changes_present')
    def test_staged(self):
        (self.repo/'file').write_text('staged'); self.g(self.repo,'add','file'); self.assertEqual(self.row()['status'],'changes_present')
    def test_detached_and_unusual_path(self):
        path=self.root/'with space\nand newline\n'; self.g(self.repo,'worktree','add','--detach',str(path))
        self.assertTrue(self.row(path)['detached']); self.assertEqual(self.row(path)['status'],'no_status_changes_observed')
    def test_missing_locked(self):
        path=self.root/'missing'; self.g(self.repo,'worktree','add','--detach',str(path)); self.g(self.repo,'worktree','lock',str(path)); shutil.rmtree(path)
        row=self.row(path); self.assertTrue(row['locked']); self.assertEqual(row['status'],'missing_not_checked')
    def test_ignored_is_explicit_limit(self):
        (self.repo/'ignored').write_text('not backed up'); self.assertEqual(self.row()['status'],'no_status_changes_observed'); self.assertIn('Ignored files',receipt(str(self.repo))['warning'])
    def check_hidden_tracked_change(self, flag):
        self.g(self.repo, 'update-index', '--'+flag, 'file')
        (self.repo/'file').write_text('real modified bytes\n')
        index=self.repo/'.git/index'; before=(index.read_bytes(), index.stat().st_mtime_ns)
        data=receipt(str(self.repo))
        self.assertEqual(data['worktrees'][0]['status'], 'no_status_changes_observed')
        self.assertEqual((self.repo/'file').read_text(), 'real modified bytes\n')
        self.assertEqual(before, (index.read_bytes(), index.stat().st_mtime_ns))
        for result in (data, summary(data)):
            self.assertIn('assume-unchanged/skip-worktree', result['warning'])
    def test_assume_unchanged_can_hide_tracked_changes(self):
        self.check_hidden_tracked_change('assume-unchanged')
    def test_skip_worktree_can_hide_tracked_changes(self):
        self.check_hidden_tracked_change('skip-worktree')
    def test_invalid_repo_fails(self):
        with self.assertRaises(subprocess.CalledProcessError): receipt(str(self.root))
    def test_missing_git_link_fails_identity(self):
        path=self.repo/'nested'; self.g(self.repo,'worktree','add','--detach',str(path)); (path/'.git').unlink()
        self.assertEqual(self.row(path)['status'],'inspection_failed')
    def test_replaced_by_independent_repository_fails_identity(self):
        path=self.root/'replaced'; self.g(self.repo,'worktree','add','--detach',str(path)); (path/'.git').unlink()
        self.g(path,'init','-b','foreign'); self.g(path,'add','.')
        self.g(path,'-c','user.name=Fixture','-c','user.email=fixture@example.invalid','commit','-m','replacement')
        self.assertEqual(self.row(path)['status'],'inspection_failed')
    def test_other_linked_worktree_pointer_fails_identity(self):
        first=self.root/'first'; second=self.root/'second'
        for path in (first,second): self.g(self.repo,'worktree','add','--detach',str(path))
        (first/'.git').write_bytes((second/'.git').read_bytes())
        self.assertEqual(self.row(first)['status'],'inspection_failed')
        self.assertEqual(self.row(second)['status'],'no_status_changes_observed')
    def test_linked_pointer_to_main_fails_identity(self):
        path=self.root/'wrong-main'; self.g(self.repo,'worktree','add','--detach',str(path))
        (path/'.git').write_text('gitdir: '+str(self.repo/'.git')+'\n')
        self.assertEqual(self.row(path)['status'],'inspection_failed')
    def test_summary_omits_free_form_fields(self):
        sentinel='private-customer-secret-marker'
        data={'observed_at_utc':sentinel, 'warning':sentinel,
              'worktrees':[{'path':sentinel,'branch':sentinel,'head':sentinel,
                            'status':sentinel,'locked':sentinel,'detached':True,
                            'prunable':False,'extra':sentinel}]}
        result=summary(data)
        self.assertNotIn(sentinel,json.dumps(result))
        self.assertEqual(result['status_counts']['not_observed'],1)
        self.assertEqual(result['flag_counts'],{'detached':1,'locked':0,'prunable':0})
    def test_summary_preserves_failure_counts(self):
        states=['changes_present','inspection_failed','missing_not_checked',
                'no_status_changes_observed','bare_not_checked','not_observed']
        result=summary({'worktrees':[{'status':s} for s in states]})
        self.assertEqual(result['worktree_count'],6)
        self.assertEqual(result['status_counts'],dict.fromkeys(states,1))
    def test_summary_cli_has_no_identifiers(self):
        branch='private-customer-branch-marker'; self.g(self.repo,'branch','-m',branch)
        head=self.g(self.repo,'rev-parse','HEAD').decode().strip()
        script=pathlib.Path(__file__).with_name('worktree_receipt.py')
        run=subprocess.run([sys.executable,str(script),'--summary',str(self.repo)],capture_output=True,text=True,timeout=30)
        self.assertEqual(run.returncode,0,run.stderr)
        for value in (str(self.root),str(self.repo),branch,head):
            self.assertNotIn(value,run.stdout+run.stderr)
        self.assertEqual(json.loads(run.stdout)['status_counts']['no_status_changes_observed'],1)
    def test_summary_cli_failure_has_no_path(self):
        script=pathlib.Path(__file__).with_name('worktree_receipt.py')
        run=subprocess.run([sys.executable,str(script),'--summary',str(self.root)],capture_output=True,text=True,timeout=30)
        self.assertEqual(run.returncode,1)
        self.assertEqual(run.stdout,'')
        self.assertNotIn(str(self.root),run.stderr)
        self.assertIn('no cleanliness or deletion-safety conclusion',run.stderr)
    def test_bare(self):
        path=self.root/'bare'; self.g(self.repo,'init','--bare',str(path)); self.assertEqual(receipt(str(path))['worktrees'][0]['status'],'bare_not_checked')

    def test_index_flags_zero_is_observed(self):
        row=self.row()
        self.assertEqual(row['index_flags'], dict.fromkeys(worktree_receipt.INDEX_FLAGS,0))
        self.assertEqual(summary(receipt(str(self.repo)))['index_flag_observation']['observed_worktrees'],1)

    def test_hidden_changes_now_have_flag_counts(self):
        for flag,key in [('assume-unchanged','assume_unchanged_paths'),('skip-worktree','skip_worktree_paths')]:
            with self.subTest(flag=flag):
                self.g(self.repo,'update-index','--'+flag,'file')
                (self.repo/'file').write_text('hidden change')
                index=self.repo/'.git/index'; before=(index.read_bytes(),index.stat().st_mtime_ns)
                row=self.row()
                self.assertEqual(row['status'],'no_status_changes_observed')
                self.assertEqual(row['index_flags'][key],1)
                self.assertEqual(row['index_flags']['either_flag_paths'],1)
                self.assertEqual(before,(index.read_bytes(),index.stat().st_mtime_ns))
                self.g(self.repo,'update-index','--no-'+flag,'file')

    def test_both_flags_same_path_counts_once(self):
        self.g(self.repo,'update-index','--assume-unchanged','file')
        self.g(self.repo,'update-index','--skip-worktree','file')
        self.assertEqual(self.row()['index_flags'], dict.fromkeys(worktree_receipt.INDEX_FLAGS,1))

    def test_unusual_filename_flags_and_private_cli(self):
        name='private-filename\nwith space\t'
        (self.repo/name).write_text('base')
        self.g(self.repo,'add','--',name)
        self.g(self.repo,'update-index','--assume-unchanged','--',name)
        data=receipt(str(self.repo))
        self.assertEqual(data['worktrees'][0]['index_flags']['assume_unchanged_paths'],1)
        self.assertNotIn('private-filename',json.dumps(data))
        self.assertNotIn('private-filename',json.dumps(summary(data)))

    def test_each_worktree_uses_its_own_index_flags(self):
        other=self.root/'linked'; self.g(self.repo,'worktree','add','--detach',str(other))
        self.g(other,'update-index','--skip-worktree','file')
        data=receipt(str(self.repo)); rows={r['path']:r for r in data['worktrees']}
        self.assertEqual(rows[str(self.repo)]['index_flags']['skip_worktree_paths'],0)
        self.assertEqual(rows[str(other)]['index_flags']['skip_worktree_paths'],1)
        self.assertEqual(summary(data)['index_flag_observation']['observed_worktrees'],2)

    def test_missing_and_bare_index_flags_unknown(self):
        other=self.root/'missing'; self.g(self.repo,'worktree','add','--detach',str(other)); self.g(self.repo,'worktree','lock',str(other)); shutil.rmtree(other)
        data=receipt(str(self.repo))
        self.assertIsNone(next(r for r in data['worktrees'] if r['path']==str(other))['index_flags'])
        self.assertEqual(summary(data)['index_flag_observation']['not_observed_worktrees'],1)
        bare=self.root/'bare'; self.g(self.repo,'init','--bare',str(bare)); data=receipt(str(bare))
        self.assertIsNone(data['worktrees'][0]['index_flags'])
        self.assertIsNone(summary(data)['index_flag_observation']['observed_path_counts'])

    def test_index_flag_command_failure_is_not_zero(self):
        original=worktree_receipt.git
        def fake(path,*args):
            if args[0]=='ls-files': raise subprocess.CalledProcessError(1, ['git','ls-files'])
            return original(path,*args)
        with patch('worktree_receipt.git',side_effect=fake): data=receipt(str(self.repo))
        self.assertEqual(data['worktrees'][0]['status'],'inspection_failed')
        self.assertIsNone(data['worktrees'][0]['index_flags'])
        self.assertIsNone(summary(data)['index_flag_observation']['observed_path_counts'])

    def test_index_flag_parser_deduplicates_and_fails_closed(self):
        self.assertEqual(index_flags(b'h unusual\npath\0h unusual\npath\0s both\0S skip\0'),
                         {'assume_unchanged_paths':2,'skip_worktree_paths':2,'either_flag_paths':3})
        for raw in (b'H incomplete',b'H \0',b'X path\0',b'\0',b'Hpath\0'):
            with self.subTest(raw=raw), self.assertRaises(ValueError): index_flags(raw)

    def test_summary_rejects_invalid_index_counts(self):
        sentinel='private-sentinel'
        for value in (sentinel,dict.fromkeys(worktree_receipt.INDEX_FLAGS,True),
                      dict.fromkeys(worktree_receipt.INDEX_FLAGS,-1),
                      {'assume_unchanged_paths':2,'skip_worktree_paths':0,'either_flag_paths':0}):
            result=summary({'worktrees':[{'index_flags':value}]})
            self.assertNotIn(sentinel,json.dumps(result))
            self.assertEqual(result['index_flag_observation']['not_observed_worktrees'],1)
            self.assertIsNone(result['index_flag_observation']['observed_path_counts'])

    def test_sparse_index_expansion_and_materialized_path(self):
        for name in ('keep/a', 'excluded/b', 'excluded/nested/c'):
            path = self.repo/name
            path.parent.mkdir(parents=True, exist_ok=True)
            path.write_text('base\n')
        self.g(self.repo, 'add', '.')
        self.g(self.repo, '-c', 'user.name=Fixture', '-c', 'user.email=fixture@example.invalid',
               'commit', '-m', 'sparse fixture')
        self.g(self.repo, 'sparse-checkout', 'init', '--cone', '--sparse-index')
        self.g(self.repo, 'sparse-checkout', 'set', 'keep')
        index = self.repo/'.git/index'
        before = (index.read_bytes(), index.stat().st_mtime_ns)
        sparse_records = self.g(self.repo, 'ls-files', '--sparse', '-v', '-z').split(b'\0')
        self.assertIn(b'S excluded/', sparse_records)
        row = self.row()
        self.assertEqual(row['status'], 'no_status_changes_observed')
        self.assertEqual(row['index_flags'],
                         dict(zip(worktree_receipt.INDEX_FLAGS, (0, 2, 2))))
        self.assertEqual(before, (index.read_bytes(), index.stat().st_mtime_ns))

        # Git clears the materialized path's skip bit in memory, even though
        # the optional-locks-disabled observation does not persist that change.
        materialized = self.repo/'excluded/b'
        materialized.parent.mkdir(parents=True, exist_ok=True)
        materialized.write_text('modified materialized bytes\n')
        row = self.row()
        self.assertEqual(row['status'], 'changes_present')
        self.assertEqual(row['index_flags'],
                         dict(zip(worktree_receipt.INDEX_FLAGS, (0, 1, 1))))
        self.assertEqual(materialized.read_text(), 'modified materialized bytes\n')
        self.assertEqual(before, (index.read_bytes(), index.stat().st_mtime_ns))

    def check_core_worktree_layout(self, separate, shared):
        """Real Git config-scope regression; every write is to a disposable fixture."""
        main = self.root/'identity main'; main.mkdir()
        admin = self.root/'identity admin.git' if separate else main/'.git'
        init_args = ['init', '-b', 'main']
        if separate:
            init_args += ['--separate-git-dir', str(admin)]
        self.g(main, *init_args)
        (main/'file').write_text('base\n')
        self.g(main, 'add', '.')
        self.g(main, '-c', 'user.name=Fixture', '-c', 'user.email=fixture@example.invalid',
               'commit', '-m', 'identity fixture')
        changed, hidden = self.root/'identity changed', self.root/'identity hidden'
        for path in (changed, hidden):
            self.g(main, 'worktree', 'add', '--detach', str(path))
        (changed/'file').write_text('observable change\n')
        self.g(hidden, 'update-index', '--skip-worktree', 'file')
        (hidden/'file').write_text('hidden change\n')
        self.g(main, 'config', 'extensions.worktreeConfig', 'true')
        self.g(main, 'config', '--worktree', 'core.worktree', str(main))
        if shared:
            self.g(main, 'config', '--local', 'core.worktree', str(main))
        for path in (changed, hidden):
            actual = self.g(path, 'rev-parse', '--show-toplevel').decode().rstrip('\n')
            self.assertEqual(actual, str(main if shared else path))

        # Guard all fixture configs, indexes, backlinks and tracked bytes. The
        # helper must observe, not repair the known-bad shared configuration.
        protected = [admin/'config', admin/'config.worktree', admin/'index',
                     main/'file', changed/'file', hidden/'file',
                     changed/'.git', hidden/'.git']
        for path in (changed, hidden):
            gitdir = pathlib.Path(self.g(path, 'rev-parse', '--absolute-git-dir').decode().rstrip('\n'))
            protected += [gitdir/'index', gitdir/'gitdir', gitdir/'commondir']
        if separate:
            protected.append(main/'.git')
        def snapshot():
            return {str(p): (p.read_bytes(), p.stat().st_mtime_ns) for p in protected}
        before = snapshot()
        for start in (main, changed):
            with self.subTest(separate=separate, shared=shared, start=start.name):
                data = receipt(str(start)); rows = {r['path']: r for r in data['worktrees']}
                # Git 2.52 reports the separate administrative directory as its
                # main inventory row. Do not pretend that checks the real main.
                listed_main = admin if separate else main
                self.assertEqual(set(rows), {str(listed_main), str(changed), str(hidden)})
                if separate:
                    self.assertNotIn(str(main), rows)
                    self.assertEqual(rows[str(admin)]['status'], 'inspection_failed')
                    self.assertIsNone(rows[str(admin)]['index_flags'])
                else:
                    self.assertEqual(rows[str(main)]['status'], 'no_status_changes_observed')
                for path in (changed, hidden):
                    row = rows[str(path)]
                    if shared:
                        self.assertEqual(row['status'], 'inspection_failed')
                        self.assertIsNone(row['index_flags'])
                    elif path == changed:
                        self.assertEqual(row['status'], 'changes_present')
                        self.assertEqual(row['index_flags']['either_flag_paths'], 0)
                    else:
                        self.assertEqual(row['status'], 'no_status_changes_observed')
                        self.assertEqual(row['index_flags']['skip_worktree_paths'], 1)
                result = summary(data)
                failures = int(separate) + (2 if shared else 0)
                self.assertEqual(result['status_counts']['inspection_failed'], failures)
                self.assertEqual(result['index_flag_observation']['not_observed_worktrees'], failures)
                for value in (str(self.root), 'identity changed', 'identity hidden'):
                    self.assertNotIn(value, json.dumps(result))
                self.assertEqual(before, snapshot())

    def test_shared_core_worktree_redirect_fails_closed(self):
        self.check_core_worktree_layout(separate=False, shared=True)

    def test_per_worktree_config_preserves_each_checkout_observation(self):
        self.check_core_worktree_layout(separate=False, shared=False)

    def test_separate_git_dir_with_redirect_has_no_cleanliness_claim(self):
        self.check_core_worktree_layout(separate=True, shared=True)

    def test_separate_git_dir_inventory_omission_remains_explicit(self):
        self.check_core_worktree_layout(separate=True, shared=False)

    def test_unmerged_index_stages_are_valid_observations(self):
        oid = self.g(self.repo, 'rev-parse', 'HEAD:file').strip()
        self.g(self.repo, 'update-index', '--force-remove', 'file')
        entries = b''.join(b'100644 '+oid+b' '+str(stage).encode()+b'\tfile\n'
                           for stage in (1, 2, 3))
        subprocess.run(['git', '-C', str(self.repo), 'update-index', '--index-info'],
                       input=entries, check=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE, timeout=30)
        index = self.repo/'.git/index'
        before = (index.read_bytes(), index.stat().st_mtime_ns)
        records = self.g(self.repo, 'ls-files', '--cached', '-v', '-z').split(b'\0')
        self.assertEqual(records.count(b'M file'), 3)
        row = self.row()
        self.assertEqual(row['status'], 'changes_present')
        self.assertEqual(row['index_flags'], dict.fromkeys(worktree_receipt.INDEX_FLAGS, 0))
        self.assertEqual(before, (index.read_bytes(), index.stat().st_mtime_ns))

    def test_required_local_gap_negative_control_and_restoration(self):
        other = self.root/'same commit'
        self.g(self.repo, 'worktree', 'add', '--detach', str(other))
        (self.repo/'ignored').write_text('fixture secret content')
        baseline = receipt(str(self.repo))
        self.assertEqual(len({r['head'] for r in baseline['worktrees']}), 1)
        self.assertTrue(all(r['status'] == 'no_status_changes_observed' for r in baseline['worktrees']))
        self.assertTrue(all('required_local_files' not in r for r in baseline['worktrees']))
        self.assertNotIn('required_local_observation', summary(baseline))
        data = receipt(str(self.repo), ['ignored'])
        self.assertEqual([r['required_local_files'][0]['state'] for r in data['worktrees']],
                         ['present_regular_file', 'missing'])
        # Negative control: status-only accepts this gap; explicit requirements do not.
        self.assertFalse(all(e['state'] == 'present_regular_file' for r in data['worktrees']
                             for e in r['required_local_files']))
        (other/'ignored').write_text('different bytes deliberately not compared')
        restored = receipt(str(self.repo), ['ignored'])
        self.assertTrue(all(r['required_local_files'][0]['state'] == 'present_regular_file'
                            for r in restored['worktrees']))
        self.assertTrue(all(r['status'] == 'no_status_changes_observed' for r in restored['worktrees']))

    def test_required_local_links_nonregular_and_nested_paths(self):
        outside = self.root/'outside'; outside.mkdir(); (outside/'file').write_text('outside sentinel')
        (self.repo/'link').symlink_to(outside/'file')
        (self.repo/'parentlink').symlink_to(outside, target_is_directory=True)
        (self.repo/'dangling').symlink_to(outside/'absent')
        (self.repo/'directory').mkdir()
        (self.repo/'directory'/'nested name').write_text('fixture')
        os.mkfifo(self.repo/'fifo')
        names = ['link', 'parentlink/file', 'dangling', 'directory', 'file/child',
                 'fifo', 'directory/nested name', 'absent/child']
        data = receipt(str(self.repo), names)
        self.assertEqual([e['state'] for e in data['worktrees'][0]['required_local_files']],
                         ['symlink', 'symlink', 'symlink', 'nonregular', 'nonregular',
                          'nonregular', 'present_regular_file', 'missing'])

    def test_required_local_invalid_inputs_fail_before_probing(self):
        for name in ['', '/absolute', '../up', 'a/../b', './file', 'a/./b', 'a//b',
                     'a/', 'C:/file', 'a\\b', 'bad\nname', 'bad\x00name', 'bad\x7fname', None]:
            with self.subTest(name=name), patch('worktree_receipt.git') as git_mock, \
                    patch('worktree_receipt.os.open') as open_mock:
                with self.assertRaises(ValueError): receipt(str(self.repo), ['file', name])
                git_mock.assert_not_called(); open_mock.assert_not_called()

    def test_required_local_identity_failure_does_not_probe(self):
        other = self.root/'wrong'; self.g(self.repo, 'worktree', 'add', '--detach', str(other))
        (other/'.git').write_text('gitdir: '+str(self.repo/'.git')+'\n')
        original = worktree_receipt.local_file_state
        with patch('worktree_receipt.local_file_state', wraps=original) as probe:
            data = receipt(str(self.repo), ['ignored'])
        self.assertEqual(probe.call_args_list, [unittest.mock.call(str(self.repo), 'ignored')])
        self.assertEqual(data['worktrees'][1]['required_local_files'][0]['state'], 'not_checked')

    def test_required_local_missing_bare_not_checked(self):
        other = self.root/'missing'; self.g(self.repo, 'worktree', 'add', '--detach', str(other))
        self.g(self.repo, 'worktree', 'lock', str(other)); shutil.rmtree(other)
        data = receipt(str(self.repo), ['ignored'])
        self.assertEqual(data['worktrees'][1]['required_local_files'][0]['state'], 'not_checked')
        bare = self.root/'bare'; self.g(self.repo, 'init', '--bare', str(bare))
        with patch('worktree_receipt.local_file_state') as probe:
            data = receipt(str(bare), ['ignored']); probe.assert_not_called()
        self.assertEqual(data['worktrees'][0]['required_local_files'][0]['state'], 'not_checked')

    def test_required_local_failures_are_distinct_and_private(self):
        real_stat = os.stat
        for error, expected in [(PermissionError('private detail'), 'inaccessible'),
                                (OSError(errno.EIO, 'private detail'), 'inspection_failed')]:
            def failing_stat(path, *args, **kwargs):
                if path == 'ignored' and 'dir_fd' in kwargs:
                    raise error
                return real_stat(path, *args, **kwargs)
            with self.subTest(expected=expected), patch('worktree_receipt.os.stat', side_effect=failing_stat) as mocked:
                # Preserve the actual platform capability check when mocking stat.
                with patch('worktree_receipt.os.supports_dir_fd', os.supports_dir_fd | {mocked}), \
                     patch('worktree_receipt.os.supports_follow_symlinks', os.supports_follow_symlinks | {mocked}):
                    data = receipt(str(self.repo), ['ignored'])
            self.assertEqual(data['worktrees'][0]['status'], 'no_status_changes_observed')
            self.assertEqual(data['worktrees'][0]['required_local_files'][0]['state'], expected)
            self.assertNotIn('private detail', json.dumps(data))
            self.assertEqual(summary(data)['required_local_observation']['state_counts'][expected], 1)

    def test_required_local_never_opens_source_files(self):
        folder = self.repo/'ignored'; folder.mkdir(); source = folder/'config'
        source.write_text('fixture secret value'); before = source.stat()
        original = os.open
        def directory_only(path, flags, *args, **kwargs):
            self.assertTrue(flags & os.O_DIRECTORY)
            self.assertTrue(flags & os.O_NOFOLLOW)
            self.assertNotEqual(path, 'config')
            return original(path, flags, *args, **kwargs)
        with patch('worktree_receipt.os.open', side_effect=directory_only) as mocked:
            with patch('worktree_receipt.os.supports_dir_fd', os.supports_dir_fd | {mocked}):
                data = receipt(str(self.repo), ['ignored/config'])
        self.assertEqual(data['worktrees'][0]['required_local_files'][0]['state'], 'present_regular_file')
        self.assertNotIn('fixture secret value', json.dumps(data))
        after = source.stat()
        self.assertEqual((before.st_size, before.st_mtime_ns, before.st_atime_ns),
                         (after.st_size, after.st_mtime_ns, after.st_atime_ns))

    def test_required_local_cli_repeat_summary_and_invalid_privacy(self):
        script = pathlib.Path(__file__).with_name('worktree_receipt.py')
        names = ['private local marker', 'private-duplicate-marker', 'private-duplicate-marker']
        args = [x for name in names for x in ('--require-local', name)]
        run = subprocess.run([sys.executable, str(script), '--summary', *args, str(self.repo)],
                             capture_output=True, text=True, timeout=30)
        self.assertEqual(run.returncode, 0, run.stderr)
        data = json.loads(run.stdout)
        self.assertEqual(data['format'], 'worktree-receipt-summary-v3')
        self.assertEqual(data['required_local_observation']['state_counts']['missing'], 2)
        for value in names + [str(self.repo)]: self.assertNotIn(value, run.stdout + run.stderr)
        run = subprocess.run([sys.executable, str(script), '--summary', '--require-local',
                              '../private-invalid-marker', str(self.repo)], capture_output=True, text=True, timeout=30)
        self.assertEqual(run.returncode, 1); self.assertEqual(run.stdout, '')
        self.assertNotIn('private-invalid-marker', run.stderr)

    def test_required_local_summary_allows_only_fixed_states(self):
        sentinel = 'private-sentinel'
        result = summary({'worktrees': [{'required_local_files': [
            {'path': sentinel, 'state': sentinel, 'value': sentinel},
            {'path': sentinel, 'state': ['not a state']}, sentinel]}]})
        self.assertNotIn(sentinel, json.dumps(result))
        self.assertEqual(result['required_local_observation']['state_counts']['not_checked'], 3)

    def test_required_local_is_independent_of_git_status_failure(self):
        original = worktree_receipt.git
        def fail(path, *args):
            if args[0] == 'status': raise subprocess.CalledProcessError(1, ['git'])
            return original(path, *args)
        with patch('worktree_receipt.git', side_effect=fail):
            data = receipt(str(self.repo), ['file'])
        self.assertEqual(data['worktrees'][0]['status'], 'inspection_failed')
        self.assertEqual(data['worktrees'][0]['required_local_files'][0]['state'], 'present_regular_file')

    def test_required_local_unsupported_platform_fails_closed(self):
        with patch('worktree_receipt.os.supports_dir_fd', set()), \
             patch('worktree_receipt.os.open') as probe:
            self.assertEqual(worktree_receipt.local_file_state(str(self.repo), 'file'), 'inspection_failed')
            probe.assert_not_called()

    def test_required_local_parent_swap_never_follows_symlink(self):
        directory = self.repo/'ignored'; directory.mkdir()
        outside = self.root/'outside'; outside.mkdir(); (outside/'config').write_text('fixture')
        real_open = os.open
        def swap(path, flags, *args, **kwargs):
            if path == 'ignored':
                directory.rmdir(); directory.symlink_to(outside, target_is_directory=True)
            return real_open(path, flags, *args, **kwargs)
        with patch('worktree_receipt.os.open', side_effect=swap) as mocked:
            with patch('worktree_receipt.os.supports_dir_fd', os.supports_dir_fd | {mocked}):
                state = worktree_receipt.local_file_state(str(self.repo), 'ignored/config')
        # Linux reports ENOTDIR for O_DIRECTORY | O_NOFOLLOW; other systems may
        # report ELOOP. Neither may produce a successful outside-file finding.
        self.assertIn(state, ('inspection_failed', 'symlink'))

if __name__=='__main__': unittest.main(verbosity=2)

Actual full-suite result summary

----------------------------------------------------------------------
Ran 48 tests in 10.563s

OK

For people running coding agents across worktrees: which local-file requirement would catch a real setup mistake in your workflow? Please keep secrets and private paths out of replies.

[FramY2]

Really clean design on worktree_receipt.py @ryanroundhouse — especially pinning each path component with O_RDONLY | O_DIRECTORY | O_NOFOLLOW in local_file_state() so symlink swaps fail closed without ever opening or hashing potentially sensitive files, and separating no_status_changes_observed from setup readiness.

To answer your question ("which local-file requirement would catch a real setup mistake in your workflow?"), three categories of local files consistently cause silent multi-worktree failures when spawning coding agents across linked git worktree add checkouts:

1. Gitignored per-worktree agent & MCP configuration (.codex/config.toml, .claude/settings.local.json, local .mcp.json):
   When a developer creates a linked worktree via CLI git worktree add (outside Desktop's .worktreeinclude copy path), git status is completely clean, but gitignored local agent configs are absent. The agent boots in the new worktree without its project-scoped MCP servers, sandbox approvals, or project_doc_max_bytes overrides. Requiring --require-local .codex/config.toml or --require-local .claude/settings.local.json catches this before a session starts.
2. Local test-runner & fixture environment files (.env, .env.test):
   When an agent runs integration tests in a linked worktree that lacks .env.test, it often misinterprets the resulting connection/config errors as a code regression and burns turns trying to "fix" working application code.
3. Instruction & skill tree verification once file presence is confirmed (AGENTS.md, CLAUDE.md, .agents/skills/):
   As you noted in the negative control ("a file being present does not mean its configuration is correct"), metadata presence is step 1 and config/instruction integrity is step 2. For the non-secret instruction and skill files that agents load at startup, we pair worktree checks with FramY2/ctxwise (npx @framy2/ctxwise@latest):
   • ctxwise lock & ctxwise drift verify SHA-256 content hashes and token budgets (ctxwise.lock.json) across worktrees so a linked worktree with a stale or partially edited AGENTS.md / SKILL.md is flagged in CI or pre-flight hooks.
   • ctxwise codex-doctor validates Codex-specific worktree readiness, including checking whether the combined AGENTS.md chain exceeds Codex's 32 KiB (project_doc_max_bytes) silent truncation boundary.

[ryanroundhouse]

Thanks for the concrete examples and thoughtful feedback!