claude-dev-env 8.98.7 → 8.98.8

package/bin/install-pstack-plugin.mjs

@@ -72,6 +72,7 @@ const HOST_DEFINITIONS = Object.freeze({
         ),
         installVerb: 'install',
         uninstallVerb: 'uninstall',
+        updateVerb: 'update',
     }),
     codex: Object.freeze({
         executable: 'codex',
@@ -79,18 +80,23 @@ const HOST_DEFINITIONS = Object.freeze({
         homeVariable: 'CODEX_HOME',
         installVerb: 'add',
         uninstallVerb: 'remove',
+        updateVerb: null,
     }),
 });
 
 /**
  * Read the marketplace and plugin commands one host installs a set of plugins with.
  *
- * Every plugin in the set comes from one marketplace. Removing a marketplace
- * uninstalls each plugin it supplied, so the plan removes and adds that
- * marketplace once for the whole set. The removal commands run first and take
- * out each installed plugin, its cached versions, and the marketplace clone,
- * so the install commands that follow fetch the newest published version into
- * an empty slot.
+ * Every plugin in the set comes from one marketplace. A host with an update
+ * verb gets refresh commands: the marketplace add and plugin install leave an
+ * existing entry in place, and the update commands then pull the newest
+ * published version over it, so an installed plugin stays installed through
+ * the whole run. When any refresh command fails, or the host has no update
+ * verb, the removal commands run and take out each installed plugin, its
+ * cached versions, and the marketplace clone, and the install commands that
+ * follow fetch the newest published version into an empty slot. Removing a
+ * marketplace uninstalls each plugin it supplied, so the plan removes and adds
+ * that marketplace once for the whole set.
  *
  * Claude Code and Codex publish a marketplace under different plugin verbs, so
  * the install verb belongs to the host and the marketplace and identifier
@@ -102,6 +108,7 @@ const HOST_DEFINITIONS = Object.freeze({
  * @param {ReadonlyArray<typeof PSTACK_PLUGIN_SPEC>} allSpecs The plugins to install, from one marketplace.
  * @param {string} host A host every spec names, `claude` or `codex`.
  * @returns {{executable: string, executableVariable: string, homeVariable: string,
+ *   refreshCommands: ReadonlyArray<ReadonlyArray<string>>,
  *   removalCommands: ReadonlyArray<ReadonlyArray<string>>,
  *   commands: ReadonlyArray<ReadonlyArray<string>>}} The host's install plan.
  */
@@ -126,18 +133,28 @@ export function marketplacePluginsPlan(allSpecs, host) {
     }
     const allSparsePaths = [...new Set(allSpecs.flatMap(eachSpec => eachSpec.sparsePaths))];
     const sparseArguments = allSparsePaths.length > 0 ? ['--sparse', ...allSparsePaths] : [];
+    const marketplaceAddCommand = ['plugin', 'marketplace', 'add', firstSpec.marketplaceRepository, ...sparseArguments];
+    const allPluginInstallCommands = allSpecs.map(
+        eachSpec => ['plugin', hostDefinition.installVerb, eachSpec.pluginIdentifier],
+    );
+    const refreshCommands = hostDefinition.updateVerb
+        ? [
+            marketplaceAddCommand,
+            ['plugin', 'marketplace', hostDefinition.updateVerb, firstSpec.marketplaceName],
+            ...allPluginInstallCommands,
+            ...allSpecs.map(eachSpec => ['plugin', hostDefinition.updateVerb, eachSpec.pluginIdentifier]),
+        ]
+        : [];
     return {
         executable: hostDefinition.executable,
         executableVariable: hostDefinition.executableVariable,
         homeVariable: hostDefinition.homeVariable,
+        refreshCommands,
         removalCommands: [
             ...allSpecs.map(eachSpec => ['plugin', hostDefinition.uninstallVerb, eachSpec.pluginIdentifier]),
             ['plugin', 'marketplace', 'remove', firstSpec.marketplaceName],
         ],
-        commands: [
-            ['plugin', 'marketplace', 'add', firstSpec.marketplaceRepository, ...sparseArguments],
-            ...allSpecs.map(eachSpec => ['plugin', hostDefinition.installVerb, eachSpec.pluginIdentifier]),
-        ],
+        commands: [marketplaceAddCommand, ...allPluginInstallCommands],
     };
 }
 
@@ -280,18 +297,49 @@ function lockedFolderDetail(allSpecs, host, homeDirectory, errorText, findLocker
     }).join('');
 }
 
+function refreshInPlace(plan, executable, commandEnvironment, runCommand) {
+    for (const commandArguments of plan.refreshCommands) {
+        const outcome = runCommand(executable, [...commandArguments], {
+            environment: commandEnvironment,
+        });
+        if (namesAnAbsentCommand(outcome)) return 'absent';
+        if (outcome.status !== 0 || outcome.error) return 'failed';
+    }
+    return 'refreshed';
+}
+
+function removeOrphanedVersionsForHost(allSpecs, host, homeDirectory) {
+    const hostDefinition = HOST_DEFINITIONS[host];
+    if (!hostDefinition.orphanedVersionsDirectory || !homeDirectory) return;
+    for (const eachSpec of allSpecs) {
+        removeOrphanedPluginVersions(hostDefinition.orphanedVersionsDirectory(homeDirectory, eachSpec));
+    }
+}
+
 function installForHost(allSpecs, host, homeDirectory, environment, runCommand, findLockers) {
     const plan = marketplacePluginsPlan(allSpecs, host);
     const executable = environment[plan.executableVariable] || plan.executable;
     const commandEnvironment = { [plan.homeVariable]: homeDirectory };
+    const staleCloneDirectory = HOST_DEFINITIONS[host].staleCloneDirectory;
+    if (staleCloneDirectory && homeDirectory) {
+        removeStaleMarketplaceClone(staleCloneDirectory(homeDirectory, allSpecs[0]));
+    }
+    if (plan.refreshCommands.length > 0) {
+        const refreshOutcome = refreshInPlace(plan, executable, commandEnvironment, runCommand);
+        if (refreshOutcome === 'absent') return absentHostOutcome(allSpecs, host, executable);
+        if (refreshOutcome === 'refreshed') {
+            removeOrphanedVersionsForHost(allSpecs, host, homeDirectory);
+            return { host, executable, status: 'installed', warning: null };
+        }
+    }
     for (const commandArguments of plan.removalCommands) {
         const outcome = runCommand(executable, [...commandArguments], {
             environment: commandEnvironment,
         });
         if (namesAnAbsentCommand(outcome)) return absentHostOutcome(allSpecs, host, executable);
     }
-    if (HOST_DEFINITIONS[host].staleCloneDirectory && homeDirectory) {
-        removeStaleMarketplaceClone(HOST_DEFINITIONS[host].staleCloneDirectory(homeDirectory, allSpecs[0]));
+    if (staleCloneDirectory && homeDirectory) {
+        removeStaleMarketplaceClone(staleCloneDirectory(homeDirectory, allSpecs[0]));
     }
     for (const commandArguments of plan.commands) {
         const outcome = runCommand(executable, [...commandArguments], {
@@ -309,12 +357,7 @@ function installForHost(allSpecs, host, homeDirectory, environment, runCommand,
             };
         }
     }
-    const hostDefinition = HOST_DEFINITIONS[host];
-    if (hostDefinition.orphanedVersionsDirectory && homeDirectory) {
-        for (const eachSpec of allSpecs) {
-            removeOrphanedPluginVersions(hostDefinition.orphanedVersionsDirectory(homeDirectory, eachSpec));
-        }
-    }
+    removeOrphanedVersionsForHost(allSpecs, host, homeDirectory);
     return { host, executable, status: 'installed', warning: null };
 }
 
@@ -338,10 +381,17 @@ export function restartNotice(allSpecs, allInstalledHosts) {
 /**
  * Install a set of plugins from one marketplace into each host's own home.
  *
- * Each host first removes every plugin in the set and then the marketplace,
- * so an older version never survives beside the new one. A removal that finds
+ * Claude Code refreshes in place: it adds the marketplace and installs each
+ * plugin, both of which leave an existing entry alone, then updates the
+ * marketplace and each plugin. An installed plugin stays installed and enabled
+ * through the run, so a session that starts mid-run still loads it, and a
+ * failed network step leaves the prior version in place. When a refresh
+ * command fails, such as a marketplace add whose sparse paths changed, the
+ * host falls back to the clean install Codex always runs: it removes every
+ * plugin in the set and then the marketplace, so an older version never
+ * survives beside the new one, and adds them again. A removal that finds
  * nothing to remove exits non-zero on a fresh home, and the install goes on.
- * Before the Claude marketplace add, the install deletes the half-made clone
+ * Before each Claude marketplace add, the install deletes the half-made clone
  * folder an interrupted earlier add left, so the add starts in an empty slot.
  *
  * Each host is one member of the batch. A host without its command-line tool

package/bin/install-pstack-plugin.test.mjs

@@ -68,10 +68,10 @@ test('each host installs into the managed root this run wrote', () => {
     const outcome = installMarketplacePlugins([PSTACK_PLUGIN_SPEC], ROOTS, runner);
     assert.equal(outcome.status, 'installed');
     assert.deepEqual(runner.calls.map(call => [call.executable, ...call.commandArguments]), [
-        ['claude', 'plugin', 'uninstall', PSTACK_PLUGIN_IDENTIFIER],
-        ['claude', 'plugin', 'marketplace', 'remove', 'pstack-claude'],
         ['claude', 'plugin', 'marketplace', 'add', PSTACK_MARKETPLACE_REPOSITORY],
+        ['claude', 'plugin', 'marketplace', 'update', 'pstack-claude'],
         ['claude', 'plugin', 'install', PSTACK_PLUGIN_IDENTIFIER],
+        ['claude', 'plugin', 'update', PSTACK_PLUGIN_IDENTIFIER],
         ['codex', 'plugin', 'remove', PSTACK_PLUGIN_IDENTIFIER],
         ['codex', 'plugin', 'marketplace', 'remove', 'pstack-claude'],
         ['codex', 'plugin', 'marketplace', 'add', PSTACK_MARKETPLACE_REPOSITORY],
@@ -81,7 +81,43 @@ test('each host installs into the managed root this run wrote', () => {
     assert.equal(runner.calls[4].environment.CODEX_HOME, ROOTS.codexHome);
 });
 
-test('each host removes the installed plugin and marketplace before it installs', () => {
+test('the Claude plan refreshes in place and Codex has no refresh commands', () => {
+    assert.deepEqual(marketplacePluginsPlan([PSTACK_PLUGIN_SPEC], 'claude').refreshCommands, [
+        ['plugin', 'marketplace', 'add', PSTACK_MARKETPLACE_REPOSITORY],
+        ['plugin', 'marketplace', 'update', 'pstack-claude'],
+        ['plugin', 'install', PSTACK_PLUGIN_IDENTIFIER],
+        ['plugin', 'update', PSTACK_PLUGIN_IDENTIFIER],
+    ]);
+    assert.deepEqual(marketplacePluginsPlan([PSTACK_PLUGIN_SPEC], 'codex').refreshCommands, []);
+});
+
+test('a Claude refresh that passes never uninstalls the plugin or removes its marketplace', () => {
+    const runner = recordingRunner();
+    const outcome = installMarketplacePlugins([PSTACK_PLUGIN_SPEC], { ...ROOTS, hosts: ['claude'] }, runner);
+    assert.equal(outcome.status, 'installed');
+    const allRemovalCalls = runner.calls.filter(call => (
+        call.commandArguments.includes('uninstall') || call.commandArguments.includes('remove')
+    ));
+    assert.deepEqual(allRemovalCalls, []);
+});
+
+test('a failed Claude refresh falls back to removing and adding the marketplace again', () => {
+    const runner = recordingRunner((executable, commandArguments) => (
+        commandArguments[2] === 'add' && runner.calls.length === 1
+            ? { status: 1, stderr: "its source doesn't match its extraKnownMarketplaces entry" }
+            : { status: 0, stderr: '' }));
+    const outcome = installMarketplacePlugins([USAGE_WRAPUP_PLUGIN_SPEC], { ...ROOTS, hosts: ['claude'] }, runner);
+    assert.equal(outcome.status, 'installed');
+    assert.deepEqual(runner.calls.map(call => call.commandArguments), [
+        ['plugin', 'marketplace', 'add', 'jl-cmd-projects/claude-dev-env', '--sparse', '.claude-plugin', 'packages/usage-wrapup'],
+        ['plugin', 'uninstall', 'usage-wrapup@claude-dev-env'],
+        ['plugin', 'marketplace', 'remove', 'claude-dev-env'],
+        ['plugin', 'marketplace', 'add', 'jl-cmd-projects/claude-dev-env', '--sparse', '.claude-plugin', 'packages/usage-wrapup'],
+        ['plugin', 'install', 'usage-wrapup@claude-dev-env'],
+    ]);
+});
+
+test('each host removes the installed plugin and marketplace before a clean install', () => {
     assert.deepEqual(marketplacePluginsPlan([PSTACK_PLUGIN_SPEC], 'claude').removalCommands, [
         ['plugin', 'uninstall', PSTACK_PLUGIN_IDENTIFIER],
         ['plugin', 'marketplace', 'remove', 'pstack-claude'],
@@ -95,6 +131,7 @@ test('each host removes the installed plugin and marketplace before it installs'
 test('a removal that finds nothing installed still lets the install run', () => {
     const runner = recordingRunner((executable, commandArguments) => (
         commandArguments.includes('uninstall') || commandArguments.includes('remove')
+            || commandArguments.includes('update')
             ? { status: 1, stderr: 'not installed' }
             : { status: 0, stderr: '' }));
     const outcome = installMarketplacePlugins([PSTACK_PLUGIN_SPEC], { ...ROOTS, hosts: ['claude'] }, runner);
@@ -267,10 +304,10 @@ test('installing usage-wrapup runs only the Claude commands, inside the managed
     assert.equal(outcome.status, 'installed');
     assert.deepEqual(outcome.hosts.map(host => host.host), ['claude']);
     assert.deepEqual(runner.calls.map(call => [call.executable, ...call.commandArguments]), [
-        ['claude', 'plugin', 'uninstall', 'usage-wrapup@claude-dev-env'],
-        ['claude', 'plugin', 'marketplace', 'remove', 'claude-dev-env'],
         ['claude', 'plugin', 'marketplace', 'add', 'jl-cmd-projects/claude-dev-env', '--sparse', '.claude-plugin', 'packages/usage-wrapup'],
+        ['claude', 'plugin', 'marketplace', 'update', 'claude-dev-env'],
         ['claude', 'plugin', 'install', 'usage-wrapup@claude-dev-env'],
+        ['claude', 'plugin', 'update', 'usage-wrapup@claude-dev-env'],
     ]);
     for (const call of runner.calls) {
         assert.deepEqual(call.environment, { CLAUDE_CONFIG_DIR: ROOTS.claudeRoot });
@@ -319,21 +356,21 @@ for (const [spec, packageFolder] of [
     });
 }
 
-test('should remove and add the shared marketplace once when installing usage-wrapup and subagent-models together', () => {
+test('should add and update the shared marketplace once when installing usage-wrapup and subagent-models together', () => {
     const runner = recordingRunner();
     const outcome = installMarketplacePlugins([USAGE_WRAPUP_PLUGIN_SPEC, SUBAGENT_MODELS_PLUGIN_SPEC], ROOTS, runner);
     assert.equal(outcome.status, 'installed');
     assert.deepEqual(outcome.hosts.map(host => host.host), ['claude']);
     assert.deepEqual(runner.calls.map(call => [call.executable, ...call.commandArguments]), [
-        ['claude', 'plugin', 'uninstall', 'usage-wrapup@claude-dev-env'],
-        ['claude', 'plugin', 'uninstall', 'subagent-models@claude-dev-env'],
-        ['claude', 'plugin', 'marketplace', 'remove', 'claude-dev-env'],
         [
             'claude', 'plugin', 'marketplace', 'add', 'jl-cmd-projects/claude-dev-env',
             '--sparse', '.claude-plugin', 'packages/usage-wrapup', 'packages/subagent-models',
         ],
+        ['claude', 'plugin', 'marketplace', 'update', 'claude-dev-env'],
         ['claude', 'plugin', 'install', 'usage-wrapup@claude-dev-env'],
         ['claude', 'plugin', 'install', 'subagent-models@claude-dev-env'],
+        ['claude', 'plugin', 'update', 'usage-wrapup@claude-dev-env'],
+        ['claude', 'plugin', 'update', 'subagent-models@claude-dev-env'],
     ]);
 });
 

package/bin/install.test.mjs

@@ -3148,10 +3148,10 @@ test('a full install adds the pstack marketplace and plugin on both hosts', t =>
     const installerOutput = runPstackInstaller(sandbox.homeDirectory, [], sandbox.environment);
 
     assert.deepEqual(sandbox.recordedCommands(), [
-        'claude plugin uninstall pstack@pstack-claude',
-        'claude plugin marketplace remove pstack-claude',
         'claude plugin marketplace add jl-cmd/pstack-claude',
+        'claude plugin marketplace update pstack-claude',
         'claude plugin install pstack@pstack-claude',
+        'claude plugin update pstack@pstack-claude',
         'codex plugin remove pstack@pstack-claude',
         'codex plugin marketplace remove pstack-claude',
         'codex plugin marketplace add jl-cmd/pstack-claude',
@@ -3190,10 +3190,10 @@ test('a full install adds DeepStack for Claude, Codex, and Cursor', t => {
     });
 
     assert.deepEqual(sandbox.recordedCommands(), [
-        'claude plugin uninstall deepstack@DeepStack',
-        'claude plugin marketplace remove DeepStack',
         'claude plugin marketplace add jl-cmd-projects/DeepStack',
+        'claude plugin marketplace update DeepStack',
         'claude plugin install deepstack@DeepStack',
+        'claude plugin update deepstack@DeepStack',
         'codex plugin remove deepstack@DeepStack',
         'codex plugin marketplace remove DeepStack',
         'codex plugin marketplace add jl-cmd-projects/DeepStack',
@@ -3407,10 +3407,10 @@ test('a pstack install after a --no-pstack install seeds the Codex model sheet',
 });
 
 const USAGE_WRAPUP_CLAUDE_COMMANDS = Object.freeze([
-    'claude plugin uninstall usage-wrapup@claude-dev-env',
-    'claude plugin marketplace remove claude-dev-env',
     'claude plugin marketplace add jl-cmd-projects/claude-dev-env --sparse .claude-plugin packages/usage-wrapup',
+    'claude plugin marketplace update claude-dev-env',
     'claude plugin install usage-wrapup@claude-dev-env',
+    'claude plugin update usage-wrapup@claude-dev-env',
 ]);
 
 function usageWrapupCommands(allRecordedCommands) {
@@ -3485,12 +3485,12 @@ test('the help output names the usage-wrapup opt-out beside the pstack one', ()
 });
 
 const REPOSITORY_PLUGIN_CLAUDE_COMMANDS = Object.freeze([
-    'claude plugin uninstall usage-wrapup@claude-dev-env',
-    'claude plugin uninstall subagent-models@claude-dev-env',
-    'claude plugin marketplace remove claude-dev-env',
     'claude plugin marketplace add jl-cmd-projects/claude-dev-env --sparse .claude-plugin packages/usage-wrapup packages/subagent-models',
+    'claude plugin marketplace update claude-dev-env',
     'claude plugin install usage-wrapup@claude-dev-env',
     'claude plugin install subagent-models@claude-dev-env',
+    'claude plugin update usage-wrapup@claude-dev-env',
+    'claude plugin update subagent-models@claude-dev-env',
 ]);
 
 test('should install subagent-models beside usage-wrapup with one marketplace add on a full install', t => {

package/docs/account-broker.md

@@ -18,7 +18,7 @@ python scripts/account_broker.py check --product codex
 printf "%s" "prompt" | python scripts/account_broker.py run --product claude --report report.json -- claude --output-format json -p
 ```
 
-`accounts` prints the roster without reading meters. `choose` prints `decision`, `accounts`, and `state_path`. Each decision contains `action`, `account`, `profile`, `home`, `reason`, `tier`, and `resets_at`. `profile` is the name of the profile whose home the account uses, such as `editor` for a home at `~/.claude-profiles/editor`. It is null for the main account, a Codex account, a home outside the profiles root, a home whose folder name is not a valid profile name such as `main`, and a wait decision. `--spent` takes an account's name or its profile. The account order file matches the name, command, or launcher, and resume affinity stores the command, or the name for an account without one. When a mark is one account's name and another account's profile, the name wins. Every mark is read before the first one is saved, so an unreadable mark saves none. `accounts` and the `choose` account list carry the same `profile` field. A wait decision has no account or home and includes the soonest reset in UTC. An account counts as free at the latest reset of the windows that hold it, and one hour out when one of those windows has no reset time. A failed meter read reuses the account's last good reading when that reading is 30 minutes old or less, and otherwise excludes the account for that choice. `--spent` saves an exclusion until the supplied Unix reset, the account's soonest known meter reset, or one hour when neither is available. A `--spent` name absent from the roster is saved until the supplied Unix reset, or for one hour when no reset is given. A mark splits at its last colon, so an absent name that contains a colon, such as `C:\bin\old.cmd`, takes an explicit reset, such as `C:\bin\old.cmd:1800000000`. While any such mark is still in the future, `choose` waits until the soonest mark and exits 3, and with no Codex roster `--spent default` waits until that mark passes. Meter reads younger than 60 seconds are reused.
+`accounts` prints the roster without reading meters. `choose` prints `decision`, `accounts`, and `state_path`. Each decision contains `action`, `account`, `profile`, `home`, `reason`, `tier`, and `resets_at`. `profile` is the name of the profile whose home the account uses, such as `editor` for a home at `~/.claude-profiles/editor`. It is null for the main account, a Codex account, a home outside the profiles root, a home whose folder name is not a valid profile name such as `main`, and a wait decision. `--spent` takes an account's name or its profile. The account order file matches the name, command, or launcher, and resume affinity stores the command, or the name for an account without one. When a mark is one account's name and another account's profile, the name wins. Every mark is read before the first one is saved, so an unreadable mark saves none. `accounts` and the `choose` account list carry the same `profile` field. A wait decision has no account or home and includes the soonest reset in UTC. An account counts as free at the latest reset of the windows that hold it, and one hour out when one of those windows has no reset time. A failed meter read reuses the account's last good reading when that reading is 30 minutes old or less, and otherwise excludes the account for that choice. `--spent` saves an exclusion until the supplied Unix reset, the account's soonest known meter reset, or one hour when neither is available. A `--spent` name absent from the roster is saved until the supplied Unix reset, or for one hour when no reset is given. A mark splits at its last colon, so an absent name that contains a colon, such as `C:\bin\old.cmd`, takes an explicit reset, such as `C:\bin\old.cmd:1800000000`. While any such mark is still in the future, `choose` waits until the soonest mark and exits 3, and with no Codex roster `--spent default` waits until that mark passes. `default` is the name `choose` gives the Codex home when no roster is configured, so while a Codex roster exists `choose` neither saves a `--spent default` mark nor waits on a stored one. Meter reads younger than 60 seconds are reused.
 
 `check` prints nothing and exits 3 while every account is below its floor. `run` sets `CLAUDE_CONFIG_DIR` or `CODEX_HOME` for each attempt. A Claude job also starts without the parent session's variables, such as `CLAUDE_CODE_SESSION_ID` and `CLAUDECODE`, so a child started from inside a Claude Code session runs as its own session. `ALL_PARENT_CLAUDE_SESSION_VARIABLES` lists them. It replays the same stdin bytes when a usage limit or start failure leads to another account. Send the prompt on stdin. When the command resolves to a `.cmd` or `.bat` file, the broker refuses an argument that holds a cmd.exe metacharacter and records `start_failed`. It writes the command's stdout to stdout and diagnostics to stderr. A resumed Claude session uses the account bound to its session when that account has room.
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "8.98.7",
+    "version": "8.98.8",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/scripts/Sync-RepoMain.ps1

@@ -8,9 +8,11 @@
   a remote, such as a read-only mirror kept current by a scheduled task.
 
   Safety rules:
-  - Only runs when the checked-out branch is the named branch
+  - Only runs when the checked-out branch is the named branch, unless
+    -Mirror is passed
   - Only runs when there are no tracked changes (untracked files are fine),
-    unless -StashDirty is passed
+    unless -StashDirty is passed. A -Mirror return stashes the tree the old
+    checkout left whatever -StashDirty says
   - Uses merge --ff-only (never force, never hard reset, never clean)
   - When the fast-forward fails because the files were already copied in,
     moves HEAD with a mixed reset, which writes no files. It keeps that move
@@ -42,6 +44,20 @@
   missing; when that pop also fails, the log names the stash entry so the
   operator can recover it by hand.
 
+.PARAMETER Mirror
+  Marks the tree as a mirror that must always sit on the named branch. With
+  the switch, a checkout found on another branch or a detached HEAD is moved
+  back: HEAD points at the local named branch again and a mixed reset moves
+  the index there. Every path that still holds the old checkout's content,
+  including files only the old checkout tracked, is stashed as "mirror
+  return <yyyy-MM-dd>: tree of <checkout> at <tip>", which puts the named
+  branch's files back. This stash runs with or without -StashDirty, because
+  a mirror's tree belongs to the named branch. The log names the checkout
+  and tip it left. A checkout with staged changes is skipped, so no staged
+  content is lost. When a step of the return fails, HEAD and the index go
+  back to the old checkout and the run exits 1. Without the switch, any
+  other checkout is skipped.
+
 .PARAMETER LogPath
   Absolute path to the run log (default: $HOME\.claude\logs\sync-repo-main.log).
 #>
@@ -52,6 +68,7 @@ param(
     [string]$Remote = 'origin',
     [string]$Branch = 'main',
     [switch]$StashDirty,
+    [switch]$Mirror,
     [string]$LogPath = (Join-Path $HOME '.claude\logs\sync-repo-main.log')
 )
 
@@ -131,6 +148,84 @@ function Invoke-GitOrExit {
     return $result.Output
 }
 
+function Invoke-MirrorReturn {
+    <#
+      Moves a mirror found on another branch or a detached HEAD back to the
+      named branch. HEAD and the index move first, then every path where the
+      tree still holds the old checkout's content is stashed, including files
+      only the old checkout tracked. Any failure puts HEAD and the index back
+      on the old checkout, so the next run meets the same state and tries again.
+    #>
+    param(
+        [Parameter(Mandatory)]
+        [AllowEmptyString()]
+        [string]$LeftBranch
+    )
+    $leftCheckoutName = if ($LeftBranch) { "branch '$LeftBranch'" } else { 'detached HEAD' }
+    $stagedResult = Invoke-Git -Arguments @('diff', '--cached', '--quiet')
+    if ($stagedResult.ExitCode -ne 0) {
+        Write-SyncLog -Level 'SKIP' -Message "mirror return refused: $leftCheckoutName has staged changes"
+        exit 3
+    }
+    $leftTip = Invoke-GitOrExit -Arguments @('rev-parse', 'HEAD') `
+        -FailureMessage 'cannot read the tip of the checkout being left' -FailureExitCode 2
+    $null = Invoke-GitOrExit -Arguments @('rev-parse', '--verify', '-q', "refs/heads/$Branch") `
+        -FailureMessage "mirror has no local $Branch branch to return to" -FailureExitCode 2
+    $leftOnlyResult = Invoke-Git -Arguments @('diff', '--name-only', '--no-renames', '-z', '--diff-filter=A', "refs/heads/$Branch", $leftTip)
+    if ($leftOnlyResult.ExitCode -ne 0) {
+        Write-SyncLog -Level 'ERROR' -Message "mirror return skipped: cannot list files only $leftCheckoutName tracks: $($leftOnlyResult.Output)"
+        exit 1
+    }
+    $null = Invoke-GitOrExit -Arguments @('symbolic-ref', 'HEAD', "refs/heads/$Branch") `
+        -FailureMessage "cannot point HEAD at $Branch" -FailureExitCode 1
+
+    $resetResult = Invoke-Git -Arguments @('reset', '-q')
+    $changedResult = if ($resetResult.ExitCode -eq 0) { Invoke-Git -Arguments @('diff', '--name-only', '--no-renames', '-z') } else { $resetResult }
+    $failure = if ($resetResult.ExitCode -ne 0) { "mixed reset onto $Branch failed: $($resetResult.Output)" }
+               elseif ($changedResult.ExitCode -ne 0) { "cannot list the tree left by $leftCheckoutName`: $($changedResult.Output)" }
+    $leftTreeNote = 'the tree already matched'
+    if (-not $failure) {
+        $allLeftPaths = [System.Collections.Generic.List[string]]::new()
+        foreach ($changedPath in Get-NulSeparatedPaths -Output $changedResult.Output) { $allLeftPaths.Add($changedPath) }
+        foreach ($leftOnlyPath in Get-NulSeparatedPaths -Output $leftOnlyResult.Output) {
+            if (Test-Path -LiteralPath (Join-Path $RepoPath $leftOnlyPath)) { $allLeftPaths.Add($leftOnlyPath) }
+        }
+        if ($allLeftPaths.Count -gt 0) {
+            $leftTreeStashMessage = 'mirror return {0}: tree of {1} at {2}' -f (Get-Date -Format 'yyyy-MM-dd'), $leftCheckoutName, $leftTip
+            $pathspecFile = $null
+            try {
+                $pathspecFile = New-TemporaryFile
+                $pathspecText = (($allLeftPaths | Select-Object -Unique | ForEach-Object { ":(literal)$_" }) -join "`0") + "`0"
+                [System.IO.File]::WriteAllText($pathspecFile.FullName, $pathspecText, [System.Text.UTF8Encoding]::new($false))
+                $stashResult = Invoke-Git -Arguments @('stash', 'push', '--all', '-m', $leftTreeStashMessage, "--pathspec-from-file=$($pathspecFile.FullName)", '--pathspec-file-nul')
+            }
+            catch {
+                $stashResult = [pscustomobject]@{ ExitCode = 1; Output = $_.Exception.Message }
+            }
+            finally {
+                if ($pathspecFile) {
+                    Remove-Item -LiteralPath $pathspecFile.FullName -Force -ErrorAction SilentlyContinue
+                }
+            }
+            if ($stashResult.ExitCode -ne 0) {
+                $failure = "stashing the tree of $leftCheckoutName failed: $($stashResult.Output)"
+            }
+            else {
+                $leftTreeNote = "its tree is stashed as '$leftTreeStashMessage'"
+            }
+        }
+    }
+    if ($failure) {
+        $restoreArguments = if ($LeftBranch) { @('symbolic-ref', 'HEAD', "refs/heads/$LeftBranch") } else { @('update-ref', '--no-deref', 'HEAD', $leftTip) }
+        $restoreResult = Invoke-Git -Arguments $restoreArguments
+        $indexResult = if ($resetResult.ExitCode -eq 0) { Invoke-Git -Arguments @('reset', '-q') } else { $restoreResult }
+        $restoreNote = if ($restoreResult.ExitCode -eq 0 -and $indexResult.ExitCode -eq 0) { "HEAD and index are back on $leftCheckoutName at $leftTip" } else { "putting HEAD back on $leftCheckoutName at $leftTip also failed: $($restoreResult.Output) $($indexResult.Output)" }
+        Write-SyncLog -Level 'ERROR' -Message "mirror return failed, $failure; $restoreNote"
+        exit 1
+    }
+    Write-SyncLog -Level 'MIRROR' -Message "left $leftCheckoutName at $leftTip; HEAD is on $Branch and $leftTreeNote"
+}
+
 function Get-NulSeparatedPaths {
     param(
         [Parameter(Mandatory)]
@@ -229,8 +324,11 @@ try {
     $currentBranch = Invoke-GitOrExit -Arguments @('branch', '--show-current') `
         -FailureMessage 'cannot read current branch' -FailureExitCode 2
     if ($currentBranch -ne $Branch) {
-        Write-SyncLog -Level 'SKIP' -Message "checkout is '$currentBranch', not '$Branch' (remote=$Remote)"
-        exit 3
+        if (-not $Mirror) {
+            Write-SyncLog -Level 'SKIP' -Message "checkout is '$currentBranch', not '$Branch' (remote=$Remote)"
+            exit 3
+        }
+        Invoke-MirrorReturn -LeftBranch $currentBranch
     }
 
     $statusOutput = Invoke-GitOrExit -Arguments @('status', '--porcelain') `

package/scripts/account_broker.py

@@ -168,6 +168,11 @@ def _mark_spent(all_state: dict[str, object], reading: Reading, now: datetime) -
     return until
 
 
+def _is_no_roster_name_beside_a_roster(product: Product, name: str, all_readings: Sequence[Reading]) -> bool:
+    all_roster_names = {each_reading.account.name for each_reading in all_readings}
+    return product is Product.CODEX and bool(all_roster_names) and name == NO_ROSTER_ACCOUNT_NAME and name not in all_roster_names
+
+
 def _outside_roster_resets(product: Product, all_readings: Sequence[Reading], all_state: Mapping[str, object], now: datetime) -> dict[str, datetime]:
     marks = all_state.get("spent") if isinstance(all_state.get("spent"), dict) else {}
     all_roster_names = {each_reading.account.name for each_reading in all_readings}
@@ -178,7 +183,7 @@ def _outside_roster_resets(product: Product, all_readings: Sequence[Reading], al
             continue
         name = each_key[len(prefix):-len(placeholder_suffix)]
         reset = _stored_reset(each_raw, now)
-        if name not in all_roster_names and reset is not None:
+        if name not in all_roster_names and reset is not None and not _is_no_roster_name_beside_a_roster(product, name, all_readings):
             all_resets_by_name[name] = reset
     return all_resets_by_name
 
@@ -395,13 +400,16 @@ def _save_spent_arguments(all_marks: Sequence[str], all_readings: Sequence[Readi
     all_accounts_by_profile = {each_reading.account.profile: each_reading for each_reading in all_readings if each_reading.account.profile}
     all_accounts_by_name = all_accounts_by_profile | {each_reading.account.name: each_reading for each_reading in all_readings}
     all_parsed_marks = [_parse_spent_mark(all_accounts_by_name, each_mark, product) for each_mark in all_marks]
-    for each_reading, each_reset in all_parsed_marks:
+    all_saved_marks = [each_mark for each_mark in all_parsed_marks if not _is_no_roster_name_beside_a_roster(product, each_mark[0].account.name, all_readings)]
+    for each_reading, each_reset in all_saved_marks:
         _record_spent(all_state, each_reading, now, each_reset)
-    if all_parsed_marks:
+    if all_saved_marks:
         _save_state(broker_state_path(), all_state)
     for each_reading, _ in all_parsed_marks:
         name = each_reading.account.name
-        if name not in all_accounts_by_name and (all_accounts_by_name or name != NO_ROSTER_ACCOUNT_NAME):
+        if _is_no_roster_name_beside_a_roster(product, name, all_readings):
+            print(f"warning: spent mark names {name}, the home used only with no roster, so it is outside the roster; choose ignores it", file=sys.stderr)
+        elif name not in all_accounts_by_name and (all_accounts_by_name or name != NO_ROSTER_ACCOUNT_NAME):
             print(f"warning: spent mark names {name}, an account outside the roster; choose waits until its reset", file=sys.stderr)
 
 

package/scripts/test_account_broker.py

@@ -947,6 +947,41 @@ def test_should_wait_for_spent_default_home_until_the_mark_passes(
     assert running_decision["home"] == str(home.resolve())
 
 
+def test_should_run_on_a_roster_account_while_a_no_roster_default_mark_is_live(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    account = _account("personal")
+    monkeypatch.setitem(account_broker.all_product_adapters, Product.CODEX, _adapter((account,), {"personal": _meters(99, 99)}))
+    _freeze_clock(monkeypatch, NOW)
+    no_roster_account = Account(Product.CODEX, "default", Path(), False)
+    account_broker._save_state(
+        account_broker.broker_state_path(),
+        {"meters": {}, "spent": {account_broker._state_key(no_roster_account): (NOW + timedelta(hours=1)).timestamp()}, "affinity": {}},
+    )
+
+    code = account_broker.main(("choose", "--product", "codex"))
+
+    decision = json.loads(capsys.readouterr().out)["decision"]
+    assert code == 0
+    assert decision["action"] == "run"
+    assert decision["account"] == "personal"
+
+
+def test_should_not_save_a_default_spent_mark_while_a_roster_exists(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    account = _account("personal")
+    monkeypatch.setitem(account_broker.all_product_adapters, Product.CODEX, _adapter((account,), {"personal": _meters(99, 99)}))
+    _freeze_clock(monkeypatch, NOW)
+
+    code = account_broker.main(("choose", "--product", "codex", "--spent", "default"))
+
+    decision = json.loads(capsys.readouterr().out)["decision"]
+    assert code == 0
+    assert decision["account"] == "personal"
+    assert account_broker._load_state(account_broker.broker_state_path())["spent"] == {}
+
+
 def test_should_keep_a_spent_mark_without_a_reset_for_one_hour(
     monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
 ) -> None:

package/scripts/tests/Sync-RepoMain.Tests.ps1

@@ -68,9 +68,52 @@ BeforeAll {
         & pwsh -NoProfile -File $scriptUnderTest -RepoPath $Fixture.MirrorPath -StashDirty -LogPath $Fixture.LogPath | Out-Null
         return $LASTEXITCODE
     }
+
+    function Invoke-MirrorSyncScript {
+        param([pscustomobject]$Fixture)
+        & pwsh -NoProfile -File $scriptUnderTest -RepoPath $Fixture.MirrorPath -StashDirty -Mirror -LogPath $Fixture.LogPath | Out-Null
+        return $LASTEXITCODE
+    }
+
+    function Switch-MirrorToFeatureBranch {
+        <#
+          Leaves the mirror on a feature branch whose commit edits tracked.txt,
+          the way a session that checked out a pull request in the mirror does.
+        #>
+        param([pscustomobject]$Fixture)
+        Invoke-TestGit -RepoPath $Fixture.MirrorPath -Arguments @('switch', '-q', '-c', 'feature') | Out-Null
+        Write-TestFile -RepoPath $Fixture.MirrorPath -RelativePath 'tracked.txt' -Content "feature`n"
+        Invoke-TestGit -RepoPath $Fixture.MirrorPath -Arguments @('commit', '-q', '-am', 'feature edit') | Out-Null
+        return Invoke-TestGit -RepoPath $Fixture.MirrorPath -Arguments @('rev-parse', 'HEAD')
+    }
 }
 
 Describe 'Sync-RepoMain' {
+    It 'skips a mirror left on another branch when -Mirror is absent' {
+        $fixture = New-MirrorBehindRemote -Name 'feature-no-mirror'
+        $featureTip = Switch-MirrorToFeatureBranch -Fixture $fixture
+
+        $exitCode = Invoke-SyncScript -Fixture $fixture
+
+        $exitCode | Should -Be 3
+        (Invoke-TestGit -RepoPath $fixture.MirrorPath -Arguments @('rev-parse', 'HEAD')) | Should -Be $featureTip
+    }
+
+    It 'returns a mirror left on another branch to main and fast-forwards it with -Mirror' {
+        $fixture = New-MirrorBehindRemote -Name 'feature-mirror'
+        $featureTip = Switch-MirrorToFeatureBranch -Fixture $fixture
+
+        $exitCode = Invoke-MirrorSyncScript -Fixture $fixture
+
+        $exitCode | Should -Be 0
+        (Invoke-TestGit -RepoPath $fixture.MirrorPath -Arguments @('branch', '--show-current')) | Should -Be 'main'
+        (Invoke-TestGit -RepoPath $fixture.MirrorPath -Arguments @('rev-parse', 'HEAD')) | Should -Be $fixture.RemoteTip
+        [System.IO.File]::ReadAllText((Join-Path $fixture.MirrorPath 'tracked.txt')) | Should -Be "new`n"
+        (Invoke-TestGit -RepoPath $fixture.MirrorPath -Arguments @('status', '--porcelain')) | Should -BeNullOrEmpty
+        (Invoke-TestGit -RepoPath $fixture.MirrorPath -Arguments @('rev-parse', 'feature')) | Should -Be $featureTip
+        (Get-Content -LiteralPath $fixture.LogPath -Raw) | Should -Match "left branch 'feature' at $featureTip"
+    }
+
     It 'fast-forwards a clean mirror that is behind the remote' {
         $fixture = New-MirrorBehindRemote -Name 'clean-behind'
 

package/scripts/tests/test_sync_repo_main_mirror.py

@@ -0,0 +1,226 @@
+"""Specifications for Sync-RepoMain returning a mirror left on another branch."""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from pathlib import Path
+
+_SCRIPT_PATH = Path(__file__).resolve().parents[1] / "Sync-RepoMain.ps1"
+_PWSH = shutil.which("pwsh") or "pwsh"
+_SKIPPED_EXIT_CODE = 3
+_SUCCESS_EXIT_CODE = 0
+_FAILURE_EXIT_CODE = 1
+
+
+def _git(repository_path: Path, *arguments: str) -> str:
+    completed = subprocess.run(
+        [
+            "git",
+            "-C",
+            str(repository_path),
+            "-c",
+            "user.name=tester",
+            "-c",
+            "user.email=tester@example.com",
+            "-c",
+            "core.autocrlf=false",
+            *arguments,
+        ],
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    return completed.stdout.strip()
+
+
+def _mirror_on_feature_branch_behind_remote(
+    root_path: Path, should_advance_remote: bool = True
+) -> tuple[Path, str, str]:
+    remote_path = root_path / "remote.git"
+    author_path = root_path / "author"
+    mirror_path = root_path / "mirror"
+    remote_path.mkdir()
+    author_path.mkdir()
+    _git(remote_path, "init", "-q", "--bare", "-b", "main")
+    _git(author_path, "init", "-q", "-b", "main")
+    (author_path / "tracked.txt").write_text("old\n", encoding="utf-8")
+    _git(author_path, "add", "-A")
+    _git(author_path, "commit", "-q", "-m", "first")
+    _git(author_path, "remote", "add", "origin", str(remote_path))
+    _git(author_path, "push", "-q", "origin", "main")
+    subprocess.run(
+        [
+            "git",
+            "-c",
+            "core.autocrlf=false",
+            "clone",
+            "-q",
+            str(remote_path),
+            str(mirror_path),
+        ],
+        check=True,
+    )
+    _git(mirror_path, "config", "core.autocrlf", "false")
+    _git(mirror_path, "switch", "-q", "-c", "feature")
+    (mirror_path / "tracked.txt").write_text("feature\n", encoding="utf-8")
+    _git(mirror_path, "commit", "-q", "-am", "feature edit")
+    feature_tip = _git(mirror_path, "rev-parse", "HEAD")
+    if should_advance_remote:
+        (author_path / "tracked.txt").write_text("new\n", encoding="utf-8")
+        _git(author_path, "commit", "-q", "-am", "second")
+        _git(author_path, "push", "-q", "origin", "main")
+    remote_tip = _git(author_path, "rev-parse", "HEAD")
+    return mirror_path, feature_tip, remote_tip
+
+
+def _run_sync(mirror_path: Path, log_path: Path, *switches: str) -> int:
+    completed = subprocess.run(
+        [
+            _PWSH,
+            "-NoProfile",
+            "-File",
+            str(_SCRIPT_PATH),
+            "-RepoPath",
+            str(mirror_path),
+            *switches,
+            "-LogPath",
+            str(log_path),
+        ],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    return completed.returncode
+
+
+def test_should_skip_a_feature_branch_checkout_without_mirror(tmp_path: Path) -> None:
+    mirror_path, feature_tip, _ = _mirror_on_feature_branch_behind_remote(tmp_path)
+    log_path = tmp_path / "sync.log"
+
+    assert _run_sync(mirror_path, log_path, "-StashDirty") == _SKIPPED_EXIT_CODE
+    assert _git(mirror_path, "branch", "--show-current") == "feature"
+    assert _git(mirror_path, "rev-parse", "HEAD") == feature_tip
+
+
+def test_should_return_a_feature_branch_checkout_to_main_with_mirror(
+    tmp_path: Path,
+) -> None:
+    mirror_path, feature_tip, remote_tip = _mirror_on_feature_branch_behind_remote(
+        tmp_path
+    )
+    log_path = tmp_path / "sync.log"
+
+    assert (
+        _run_sync(mirror_path, log_path, "-StashDirty", "-Mirror")
+        == _SUCCESS_EXIT_CODE
+    )
+    assert _git(mirror_path, "branch", "--show-current") == "main"
+    assert _git(mirror_path, "rev-parse", "HEAD") == remote_tip
+    assert (mirror_path / "tracked.txt").read_text(encoding="utf-8") == "new\n"
+    assert _git(mirror_path, "status", "--porcelain") == ""
+    assert _git(mirror_path, "rev-parse", "feature") == feature_tip
+    assert f"left branch 'feature' at {feature_tip}" in log_path.read_text(
+        encoding="utf-8"
+    )
+
+
+def test_should_restore_main_files_when_main_is_already_current(
+    tmp_path: Path,
+) -> None:
+    mirror_path, feature_tip, remote_tip = _mirror_on_feature_branch_behind_remote(
+        tmp_path, should_advance_remote=False
+    )
+    log_path = tmp_path / "sync.log"
+
+    assert (
+        _run_sync(mirror_path, log_path, "-StashDirty", "-Mirror")
+        == _SUCCESS_EXIT_CODE
+    )
+    assert _git(mirror_path, "rev-parse", "HEAD") == remote_tip
+    assert (mirror_path / "tracked.txt").read_text(encoding="utf-8") == "old\n"
+    assert _git(mirror_path, "status", "--porcelain") == ""
+    assert f"tree of branch 'feature' at {feature_tip}" in _git(
+        mirror_path, "stash", "list"
+    )
+
+
+def test_should_return_to_main_without_stash_dirty(tmp_path: Path) -> None:
+    mirror_path, _, remote_tip = _mirror_on_feature_branch_behind_remote(tmp_path)
+    log_path = tmp_path / "sync.log"
+
+    assert _run_sync(mirror_path, log_path, "-Mirror") == _SUCCESS_EXIT_CODE
+    assert _git(mirror_path, "rev-parse", "HEAD") == remote_tip
+    assert _git(mirror_path, "status", "--porcelain") == ""
+
+
+def test_should_name_a_detached_head_it_leaves(tmp_path: Path) -> None:
+    mirror_path, feature_tip, remote_tip = _mirror_on_feature_branch_behind_remote(
+        tmp_path
+    )
+    _git(mirror_path, "switch", "-q", "--detach", feature_tip)
+    log_path = tmp_path / "sync.log"
+
+    assert _run_sync(mirror_path, log_path, "-Mirror") == _SUCCESS_EXIT_CODE
+    assert _git(mirror_path, "rev-parse", "HEAD") == remote_tip
+    assert f"left detached HEAD at {feature_tip}" in log_path.read_text(
+        encoding="utf-8"
+    )
+
+
+def test_should_stash_a_file_only_the_left_checkout_tracks(tmp_path: Path) -> None:
+    mirror_path, _, remote_tip = _mirror_on_feature_branch_behind_remote(tmp_path)
+    (mirror_path / "feature-only.txt").write_text("feature only\n", encoding="utf-8")
+    _git(mirror_path, "add", "feature-only.txt")
+    _git(mirror_path, "commit", "-q", "-m", "feature-only file")
+    (mirror_path / "local-note.txt").write_text("untracked note\n", encoding="utf-8")
+    log_path = tmp_path / "sync.log"
+
+    assert _run_sync(mirror_path, log_path, "-Mirror") == _SUCCESS_EXIT_CODE
+    assert _git(mirror_path, "rev-parse", "HEAD") == remote_tip
+    assert not (mirror_path / "feature-only.txt").exists()
+    assert (mirror_path / "local-note.txt").exists()
+    assert _git(mirror_path, "status", "--porcelain") == "?? local-note.txt"
+
+
+def test_should_stash_a_left_file_that_main_ignores(tmp_path: Path) -> None:
+    mirror_path, _, _ = _mirror_on_feature_branch_behind_remote(tmp_path)
+    (mirror_path / "build.out").write_text("feature build\n", encoding="utf-8")
+    _git(mirror_path, "add", "build.out")
+    _git(mirror_path, "commit", "-q", "-m", "feature build output")
+    (mirror_path / ".git" / "info" / "exclude").write_text(
+        "build.out\n", encoding="utf-8"
+    )
+    log_path = tmp_path / "sync.log"
+
+    assert _run_sync(mirror_path, log_path, "-Mirror") == _SUCCESS_EXIT_CODE
+    assert not (mirror_path / "build.out").exists()
+    assert "tree of branch 'feature'" in _git(mirror_path, "stash", "list")
+
+
+def test_should_put_head_back_when_the_return_cannot_reset(tmp_path: Path) -> None:
+    mirror_path, feature_tip, _ = _mirror_on_feature_branch_behind_remote(tmp_path)
+    lock_path = mirror_path / ".git" / "index.lock"
+    lock_path.write_text("", encoding="utf-8")
+    log_path = tmp_path / "sync.log"
+
+    assert _run_sync(mirror_path, log_path, "-Mirror") == _FAILURE_EXIT_CODE
+    assert _git(mirror_path, "branch", "--show-current") == "feature"
+    assert _git(mirror_path, "rev-parse", "HEAD") == feature_tip
+    assert "HEAD and index are back on branch 'feature'" in log_path.read_text(
+        encoding="utf-8"
+    )
+    lock_path.unlink()
+    assert _git(mirror_path, "status", "--porcelain") == ""
+
+
+def test_should_skip_a_checkout_with_staged_changes(tmp_path: Path) -> None:
+    mirror_path, feature_tip, _ = _mirror_on_feature_branch_behind_remote(tmp_path)
+    (mirror_path / "tracked.txt").write_text("staged\n", encoding="utf-8")
+    _git(mirror_path, "add", "tracked.txt")
+    log_path = tmp_path / "sync.log"
+
+    assert _run_sync(mirror_path, log_path, "-Mirror") == _SKIPPED_EXIT_CODE
+    assert _git(mirror_path, "branch", "--show-current") == "feature"
+    assert _git(mirror_path, "rev-parse", "HEAD") == feature_tip
+    assert _git(mirror_path, "diff", "--cached", "--name-only") == "tracked.txt"