claude-dev-env 8.43.4 → 8.43.6

package/_shared/advisor/advisor-protocol.md

@@ -138,8 +138,8 @@ Drift signals and the per-host re-spawn / re-bind steps: [`reference/lifecycle.m
 
 ## CLI chain
 
-The shared runner is `python "$HOME/.claude/scripts/claude_chain_runner.py" [--routing-mode usage_ranked|ordered_account] -- <claude args...>`.
-Modes and failover, the tier-to-alias table, brief piping, and `--resume` session handling: [`reference/cli-chain.md`](reference/cli-chain.md).
+The shared runner is `python "$HOME/.claude/scripts/account_broker.py" run --product claude --report <path> -- claude <args...>`.
+Account choice, failover, the tier-to-alias table, brief piping, and `--resume` session handling: [`reference/cli-chain.md`](reference/cli-chain.md).
 
 **Third-party host:** the primary bind and consult path; the walk order and fail-closed rule live in [`reference/third-party-bind.md`](reference/third-party-bind.md).
 

package/_shared/advisor/reference/cli-chain.md

@@ -1,18 +1,15 @@
 # CLI Claude-chain
 
 Detail behind the `## CLI chain` section of [`advisor-protocol.md`](../advisor-protocol.md).
-The shared runner is `python "$HOME/.claude/scripts/claude_chain_runner.py" [--routing-mode usage_ranked|ordered_account] -- <claude args...>`.
+The shared runner is `python "$HOME/.claude/scripts/account_broker.py" run --product claude --report <path> -- claude <args...>`.
 
-## Modes
+## Account choice
 
-| Mode | Flag | Walk order | Failover |
-|---|---|---|---|
-| Usage-ranked (default) | `--routing-mode usage_ranked` or omit the flag | Highest weekly remaining first (`claude_chain_usage` / usage-pause OAuth probe) | Usage-limit signature only |
-| Ordered-account | `--routing-mode ordered_account` | Config list order in `~/.claude/claude-chain.json` | Usage-limit signature only; auth / timeout / config / other process errors → `advisor_blocked` |
-
-**Root advisor bind and consult** (the third-party host path): ordered-account mode. A non-usage failure terminates with `terminal_status=advisor_blocked`, exit code 4 on the CLI.
-
-**General chain calls** (non-root automation): keep the default usage-ranked mode.
+The broker applies the main account guard and chooses an eligible extra account
+by remaining usage. On a usage-limit response, it tries another account. If no
+account has room, it reports a reset time and exits with code 3. A non-usage
+Claude failure has `JobOutcome.status == "advisor_blocked"`; the CLI exits with
+code 4. The report path receives the broker's decision and attempt events.
 
 ## Tier-to-alias map
 
@@ -38,8 +35,8 @@ Drop the file once the consult completes.
 
 ## Session resume
 
-Read the `session_id` out of the first call's JSON events.
+Read the `session_id` out of the first call's JSON events or `JobOutcome.session_id`.
 Pass it to `-p --resume <session_id> --output-format json` on every later consult — `-p` stays on the resume call too, since it is still a non-interactive invocation.
-A session store belongs to the binary and account that minted it, so after a usage-limit failover to the next binary a `--resume` against it can fail.
+A session store belongs to the account that minted it. The broker keeps account affinity when that account has room. If the account reaches a usage limit, a `--resume` on another account can fail.
 Treat that failure as starting over.
 Resend the charter plus a compact recap of the consults since the last one, capture the new `session_id` the fresh call returns, and continue from there.

package/_shared/advisor/reference/lifecycle.md

@@ -22,6 +22,6 @@ Every other consumer reaches it by message alone; spawn, respawn, and shutdown b
 
 The orchestrating session owns the CLI advisor bind for the whole run: first bind, re-bind on drift or lost `session_id`, and fail-closed report when the bound path cannot serve.
 
-**Re-bind on drift.** If a reply shows a stale picture, the task pivots, or `--resume` fails after a usage-limit failover (session stores are per binary/account), re-bind Opus through `claude_chain_runner.py` with the charter plus a compact recap of consults so far.
+**Re-bind on drift.** If a reply shows a stale picture, the task pivots, or `--resume` fails after a usage-limit failover, re-bind Opus through `python "$HOME/.claude/scripts/account_broker.py" run --product claude --report <path> -- claude <args...>` with the charter plus a compact recap of consults so far.
 Capture the new `session_id`, and log a fresh Opus walk with `result: "cli"` on success, then Astra when that rung is open. An Astra re-bind uses `codex_astra_advisor.py --bind --enable-astra` with the same charter and recap, and records `result: "codex"` on success.
 Executors keep reporting to the orchestrating session; advisor binding stays with that session alone.

package/_shared/advisor/reference/third-party-bind.md

@@ -22,15 +22,15 @@ When the Astra flag is off, follow the Claude-chain steps below.
 3. **CLI bind (primary path):** for Opus, pipe a charter file into:
 
    ```
-   python "$HOME/.claude/scripts/claude_chain_runner.py" --routing-mode ordered_account -- -p --model <alias> --effort <effort> --output-format json
+   python "$HOME/.claude/scripts/account_broker.py" run --product claude --report <path> -- claude -p --model <alias> --effort <effort> --output-format json
    ```
 
    Use `--model opus --effort` with the value of `ADVISOR_EFFORT` (default `xhigh`) on Opus.
    User-facing wording follows [`rules/asd-ste100-language.md`](../../../rules/asd-ste100-language.md).
-   A root advisor bind uses `--routing-mode ordered_account`. Walk order, failover, and the `advisor_blocked` terminal status are in [`cli-chain.md`](cli-chain.md).
+   Account choice, failover, and the `advisor_blocked` status are in [`cli-chain.md`](cli-chain.md).
 4. Stop at the first successful bind.
    Record `{tier, result: "cli"}` for Opus or `{tier: "Astra", result: "codex"}` for the Astra helper, and set `selected_tier` to that tier.
-   Persist `session_id` from the JSON events (any event carries it; the runner also surfaces it on `ChainInvocationOutcome.session_id`; reply text is the `type == "result"` event's `.result` field).
+   Persist `session_id` from the JSON events or `JobOutcome.session_id`; reply text is the `type == "result"` event's `.result` field.
    Run every bind and every later consult with cwd set to the repo root the work is for. Claude sessions are project-scoped by working directory.
 5. **Fail closed:** when every candidate fails (chain exhausted, `advisor_blocked`, or model unavailable), set `selected_tier = null` and a `fallback_reason`, report that the advisor is unreachable, and **stop**. ENDORSE / CORRECTION / PLAN / STOP come only from a bound advisor.
 6. Assemble and paste each executor's Advisor block from [`advisor-block.md`](advisor-block.md). Executors report to the orchestrating session; that session consults the bound advisor and relays the four-signal reply.

package/bin/install.mjs

@@ -1363,15 +1363,16 @@ function commandRunsHookOfRootSharingSettings(normalizedCommand, relativePath, s
     while (tailStart !== -1) {
         const characterAfterPath = normalizedCommand[tailStart + hookPathTail.length];
         if (characterAfterPath === undefined || commandArgumentBoundary.test(characterAfterPath)) {
-            let rootStart = tailStart;
+            let rootPath;
             if (characterAfterPath === '"' || characterAfterPath === "'") {
-                rootStart = normalizedCommand.lastIndexOf(characterAfterPath, tailStart - 1) + 1;
+                rootPath = quotedRootPathBeforeTail(normalizedCommand.slice(0, tailStart), characterAfterPath);
             } else {
+                let rootStart = tailStart;
                 while (rootStart > 0 && !commandArgumentBoundary.test(normalizedCommand[rootStart - 1])) {
                     rootStart--;
                 }
+                rootPath = normalizedCommand.slice(rootStart, tailStart);
             }
-            const rootPath = normalizedCommand.slice(rootStart, tailStart);
             const rootSettingsRealPath = rootPath
                 ? realPathOrNull(join(rootPath, SETTINGS_FILE_NAME))
                 : null;
@@ -1384,6 +1385,41 @@ function commandRunsHookOfRootSharingSettings(normalizedCommand, relativePath, s
     return false;
 }
 
+/**
+ * How each quote style of a hook path argument joins the segments around an
+ * escaped character, keyed by the quote, in the forward-slash command form.
+ */
+const QUOTED_ARGUMENT_ESCAPES = {
+    '"': { segmentJoin: '"^%"', joinedCharacter: '%' },
+    "'": { segmentJoin: "'/''", joinedCharacter: "'" },
+};
+
+/**
+ * Decode the root part of a quoted argument that `commandArgumentFromPath`
+ * wrote, read from the command text that ends where the hook path tail starts.
+ *
+ * The win32 form splits a path at each `%` into `"a"^%"b"`. The POSIX form
+ * escapes each `'` as `'\''`, which reads `'/''` once backslashes become
+ * forward slashes.
+ *
+ * @param {string} commandBeforeTail Normalized command text up to the hook path tail.
+ * @param {string} closingQuote The quote that closes the argument after the tail.
+ * @returns {string} The root path with each escaped character restored.
+ */
+function quotedRootPathBeforeTail(commandBeforeTail, closingQuote) {
+    const { segmentJoin, joinedCharacter } = QUOTED_ARGUMENT_ESCAPES[closingQuote];
+    const segments = [];
+    let segmentEnd = commandBeforeTail.length;
+    let openingQuote = commandBeforeTail.lastIndexOf(closingQuote, segmentEnd - 1);
+    while (commandBeforeTail.slice(openingQuote - segmentJoin.length + 1, openingQuote + 1) === segmentJoin) {
+        segments.unshift(commandBeforeTail.slice(openingQuote + 1, segmentEnd));
+        segmentEnd = openingQuote - segmentJoin.length + 1;
+        openingQuote = commandBeforeTail.lastIndexOf(closingQuote, segmentEnd - 1);
+    }
+    segments.unshift(commandBeforeTail.slice(openingQuote + 1, segmentEnd));
+    return segments.join(joinedCharacter);
+}
+
 function commandTailEndsAtManagedHook(normalizedCommand, relativePath) {
     if (commandHoldsPathAtBoundary(normalizedCommand, `/.claude/hooks/${relativePath}`)) {
         return true;

package/bin/install.shared-settings.test.mjs

@@ -243,3 +243,49 @@ test('the merge prunes a quoted hook of a sharing root whose path holds a space'
         rmSync(sandboxRoot, { recursive: true, force: true });
     }
 });
+
+for (const { shape, rootDirectoryName, platform } of [
+    { shape: 'a percent sign', rootDirectoryName: 'Jane 100% Doe', platform: 'win32' },
+    { shape: 'an apostrophe', rootDirectoryName: "Jane O'Doe", platform: 'linux' },
+]) {
+    test(`the merge prunes a ${platform}-quoted hook of a sharing root whose path holds ${shape}`, t => {
+        const sandboxRoot = mkdtempSync(join(tmpdir(), 'cdev-shared-settings-escape-'));
+        try {
+            const installRoot = join(sandboxRoot, 'install-root');
+            const sharingRoot = join(sandboxRoot, rootDirectoryName, 'profiles', 'second');
+            for (const eachRoot of [installRoot, sharingRoot]) mkdirSync(eachRoot, { recursive: true });
+            const settingsPath = join(installRoot, 'settings.json');
+            writeFileSync(settingsPath, '{}\n');
+            try {
+                symlinkSync(settingsPath, join(sharingRoot, 'settings.json'), 'file');
+            } catch (linkError) {
+                t.skip(`this host cannot create a file symlink (${linkError.code})`);
+                return;
+            }
+            const hooksConfig = {
+                hooks: {
+                    SessionStart: [{
+                        matcher: '',
+                        hooks: [{ type: 'command', command: 'python3 ${CLAUDE_PLUGIN_ROOT}/hooks/session/start.py' }],
+                    }],
+                },
+            };
+            const forwardSlashed = rootPath => rootPath.replace(/\\/g, '/');
+            const sharingHookPath = `${forwardSlashed(sharingRoot)}/hooks/session/start.py`;
+            const sharingCommand = `python3 ${commandArgumentFromPath(sharingHookPath, platform)}`;
+            const settings = {
+                hooks: {
+                    SessionStart: [{ matcher: '', hooks: [{ type: 'command', command: sharingCommand }] }],
+                },
+            };
+
+            mergeHooksIntoSettings(settings, hooksConfig, forwardSlashed(installRoot), 'python3', settingsPath);
+
+            const allCommands = settings.hooks.SessionStart.flatMap(group => group.hooks.map(hook => hook.command));
+            assert.ok(!allCommands.includes(sharingCommand), `the sharing root entry ${sharingCommand} is pruned`);
+            assert.equal(allCommands.length, 1, 'only the install root entry stays after the merge');
+        } finally {
+            rmSync(sandboxRoot, { recursive: true, force: true });
+        }
+    });
+}

package/bin/install.test.mjs

@@ -216,7 +216,7 @@ test('core includeDirectories ships _shared and scripts for advisor protocol and
     );
     assert.ok(
         CORE_INCLUDE_DIRECTORIES.includes('scripts'),
-        'scripts must ship with --only core so claude_chain_runner.py is available for advisor CLI fallback',
+        'scripts must ship with --only core so account_broker.py is available for advisor CLI fallback',
     );
 });
 

package/docs/second-claude-account.md

@@ -9,12 +9,12 @@ keeps its own sign-in and history.
 | File | What it does |
 |---|---|
 | `scripts/claude_account_profile.py` | Links each shared entry of `~/.claude` into the profile `~/.claude-profiles/ev`, moves stale copies into `.replaced/<time>/`, and writes the `claude-ev.cmd` launcher into `~/.local/bin` |
-| `scripts/claude_account_choice.py` | Reads both accounts' 5-hour and weekly meters and prints which account a job runs on |
-| `scripts/claude_account_worker.py` | Runs one headless Claude worker using the account chosen by the picker |
-| `scripts/claude_account_worker_process.py` | Launches the worker process, feeds it the brief, and kills it on timeout |
+| `scripts/account_broker.py` | Reads the account roster and usage meters, chooses an account, and runs Claude with that account's home |
+| `scripts/claude_account_worker.py` | Runs one headless Claude worker through the broker |
+| `scripts/claude_account_worker_process.py` | Sends the brief to the broker and measures the run |
 | `scripts/claude_account_worker_report.py` | Builds and writes the JSON report a worker leaves behind |
 | `scripts/dev_env_scripts_constants/claude_account_worker_constants.py` | The worker's flag names, defaults, exit codes, and report keys |
-| `scripts/dev_env_scripts_constants/claude_account_constants.py` | The profile name, the entries that stay per account, and the picker thresholds |
+| `scripts/dev_env_scripts_constants/claude_account_constants.py` | The profile name, the entries that stay per account, and the account thresholds |
 
 The launcher sets `CLAUDE_CONFIG_DIR` to the profile and passes every argument to
 `claude`, so `claude-ev -p "..."` runs like `claude -p "..."` on the second
@@ -43,19 +43,17 @@ to spend leftover usage that expires soon.
 |---|---|
 | Main week resets within 24 hours, main under 90% of its week, main under 50% of its 5-hour window | main |
 | Otherwise, second under 95% of its week and under 90% of its 5-hour window | second |
-| Second meter unreadable | second, whose own run refreshes the sign-in |
+| Second meter unreadable | wait until the meter can be read |
 | Otherwise | wait, with the next reset time |
 
 An unreadable main meter never picks main.
 
 ```
-python packages/claude-dev-env/scripts/claude_account_choice.py
-{"account": "second", "config_dir": "C:\\Users\\me\\.claude-profiles\\ev", "reason": "...",
- "meters": {"main": {"session_used_percent": 12.0, "session_resets_at": "...",
-                     "weekly_used_percent": 34.0, "weekly_resets_at": "..."},
-            "second": null}}
+python packages/claude-dev-env/scripts/account_broker.py choose --product claude
 ```
 
-The `meters` object carries each account's used percent and reset time for the
-5-hour window and the week. An account whose meter could not be read shows `null`.
-A usage report reads both accounts from this one call.
+The JSON output has a `decision` object and an `accounts` list. Each account's
+`meters` holds its remaining percent and reset time for the 5-hour window and
+the week. An unreadable meter appears as `null`. A wait decision has
+`action: "wait"` and a `resets_at` timestamp. The broker exits with code 3 on
+wait. The worker writes the same reset time to its report.

package/package.json

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

package/scripts/_code_review_test_support.py

@@ -24,13 +24,8 @@ _SCRIPTS_DIRECTORY = str(Path(__file__).resolve().parent)
 if _SCRIPTS_DIRECTORY not in sys.path:
     sys.path.insert(0, _SCRIPTS_DIRECTORY)
 
-import claude_chain_runner as chain_runner  # noqa: E402
 import invoke_code_review as invoker  # noqa: E402
-from claude_chain_runner import ChainAttempt, ChainInvocationOutcome  # noqa: E402
-from dev_env_scripts_constants.claude_chain_constants import (  # noqa: E402
-    TERMINAL_STATUS_CHAIN_EXHAUSTED,
-    TERMINAL_STATUS_SERVED,
-)
+from dev_env_scripts_constants.account_broker_constants import JobOutcome, Product, WAIT_EXIT_CODE
 from dev_env_scripts_constants.code_review_constants import (  # noqa: E402
     CLI_SESSION_MODEL_FLAG,
     CODE_REVIEW_MODEL_ALIAS,
@@ -111,27 +106,29 @@ def claude_served(
     *,
     returncode: int = FIXTURE_CHAIN_RETURNCODE,
     stdout: str = FIXTURE_CHAIN_STDOUT,
-) -> ChainInvocationOutcome:
-    return ChainInvocationOutcome(
-        served_command=FIXTURE_SERVED_COMMAND,
+) -> JobOutcome:
+    return JobOutcome(
         returncode=returncode,
         stdout=stdout,
         stderr="",
-        attempts=(ChainAttempt(command=FIXTURE_SERVED_COMMAND, status="served"),),
-        terminal_status=TERMINAL_STATUS_SERVED,
+        account_name=FIXTURE_SERVED_COMMAND,
+        attempts=((FIXTURE_SERVED_COMMAND, "served"),),
+        status="served" if returncode == 0 else "advisor_blocked",
+        session_id=None,
+        wait_reset_at=None,
     )
 
 
-def claude_failed() -> ChainInvocationOutcome:
-    return ChainInvocationOutcome(
-        served_command=None,
-        returncode=FIXTURE_FAILED_RETURNCODE,
+def claude_failed() -> JobOutcome:
+    return JobOutcome(
+        returncode=WAIT_EXIT_CODE,
         stdout="",
-        stderr="chain exhausted",
-        attempts=(
-            ChainAttempt(command=FIXTURE_SERVED_COMMAND, status="usage_limited"),
-        ),
-        terminal_status=TERMINAL_STATUS_CHAIN_EXHAUSTED,
+        stderr="",
+        account_name=None,
+        attempts=((FIXTURE_SERVED_COMMAND, "usage_limited"),),
+        status="exhausted",
+        session_id=None,
+        wait_reset_at=None,
     )
 
 
@@ -179,7 +176,7 @@ class SeamCallLog:
 @dataclass
 class _SeamConfiguration:
     host_profile: str
-    claude_outcome: ChainInvocationOutcome | BaseException | None
+    claude_outcome: JobOutcome | BaseException | None
     should_dirty_tree_on_chain: bool
     working_directory: Path | None
 
@@ -220,23 +217,21 @@ def _build_host_profile_seam(
 
 def _build_claude_seam(
     call_log: SeamCallLog, configuration: _SeamConfiguration
-) -> Callable[..., ChainInvocationOutcome]:
+) -> Callable[..., JobOutcome]:
     def fake_claude(
-        all_claude_arguments: list[str], *, timeout_seconds: int
-    ) -> ChainInvocationOutcome:
+        product: Product, all_claude_arguments: list[str], **options: object
+    ) -> JobOutcome:
+        assert product is Product.CLAUDE
         call_log.claude_calls += 1
-        call_log.claude_arguments = list(all_claude_arguments)
-        chain_runner.chain_subprocess_runner(
-            ["claude", *all_claude_arguments],
-            capture_output=True,
-            text=True,
-            timeout=timeout_seconds,
-            check=False,
-        )
+        call_log.claude_arguments = list(all_claude_arguments[1:])
+        call_log.is_stdin_empty = options.get("stdin_text") == ""
+        if options.get("cwd") is not None:
+            call_log.claude_working_directory = Path(options["cwd"])
+            call_log.all_observed_working_directories.append(Path(options["cwd"]))
         _record_dirty_tree(configuration)
         if isinstance(configuration.claude_outcome, BaseException):
             raise configuration.claude_outcome
-        assert isinstance(configuration.claude_outcome, ChainInvocationOutcome)
+        assert isinstance(configuration.claude_outcome, JobOutcome)
         return configuration.claude_outcome
 
     return fake_claude
@@ -284,18 +279,13 @@ def _apply_seams(
         "review_claude_runner",
         _build_claude_seam(call_log, configuration),
     )
-    monkeypatch.setattr(
-        chain_runner,
-        "chain_subprocess_runner",
-        _build_subprocess_seam(call_log),
-    )
 
 
 def install_seams(
     monkeypatch: pytest.MonkeyPatch,
     *,
     host_profile: str = HOST_PROFILE_CLAUDE,
-    claude_outcome: ChainInvocationOutcome | BaseException | None = None,
+    claude_outcome: JobOutcome | BaseException | None = None,
     should_dirty_tree_on_chain: bool = False,
     working_directory: Path | None = None,
 ) -> SeamCallLog: