claude-dev-env 2.8.0 → 2.10.0

package/scripts/grok_patch_artifacts.py

@@ -0,0 +1,123 @@
+#!/usr/bin/env python3
+"""Extract patch artifacts and SHA-256 manifests from isolated worktrees.
+
+::
+
+    manifest = write_patch_manifest(
+        run_state_directory=run_dir,
+        task_id="O-04",
+        base_sha="abc",
+        worktree_path=worktree,
+        worker_report_text="ok",
+    )
+    ok: manifest carries content hash and changed paths
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import subprocess
+from pathlib import Path
+
+from dev_env_scripts_constants.grok_run_ledger_constants import (
+    JSON_INDENT,
+    LEDGER_SCHEMA_VERSION,
+    PATCH_MANIFEST_FILENAME,
+    UTF8_ENCODING,
+)
+
+
+def compute_sha256_hex(content: bytes) -> str:
+    """Return the hex SHA-256 digest of raw bytes.
+
+    Args:
+        content: Bytes to hash.
+
+    Returns:
+        Lowercase hex digest string.
+    """
+    return hashlib.sha256(content).hexdigest()
+
+
+def extract_worktree_diff(
+    *,
+    worktree_path: Path,
+    base_sha: str,
+) -> tuple[str, tuple[str, ...]]:
+    """Return unified diff text and changed paths against base_sha.
+
+    Args:
+        worktree_path: Isolated worker worktree.
+        base_sha: Base commit SHA the worker started from.
+
+    Returns:
+        ``(diff_text, changed_paths)``.
+    """
+    diff_text = subprocess.check_output(
+        ["git", "-C", str(worktree_path), "diff", base_sha],
+        text=True,
+        encoding=UTF8_ENCODING,
+    )
+    changed_paths_listing = subprocess.check_output(
+        ["git", "-C", str(worktree_path), "diff", "--name-only", base_sha],
+        text=True,
+        encoding=UTF8_ENCODING,
+    )
+    changed_paths = tuple(
+        each_line.strip()
+        for each_line in changed_paths_listing.splitlines()
+        if each_line.strip()
+    )
+    return diff_text, changed_paths
+
+
+def write_patch_manifest(
+    *,
+    run_state_directory: Path,
+    task_id: str,
+    base_sha: str,
+    worktree_path: Path,
+    worker_report_text: str,
+    patch_filename: str | None = None,
+) -> dict[str, object]:
+    """Write a patch file and JSON manifest binding hashes and paths.
+
+    Args:
+        run_state_directory: Directory that holds ledger and patch artifacts.
+        task_id: Task the patch belongs to.
+        base_sha: Base commit SHA.
+        worktree_path: Worker worktree to diff.
+        worker_report_text: Worker report body bound into the manifest.
+        patch_filename: Optional override for the ``.patch`` filename.
+
+    Returns:
+        The manifest document written to disk.
+    """
+    run_state_directory = Path(run_state_directory)
+    run_state_directory.mkdir(parents=True, exist_ok=True)
+    diff_text, changed_paths = extract_worktree_diff(
+        worktree_path=Path(worktree_path),
+        base_sha=base_sha,
+    )
+    patch_name = patch_filename or f"{task_id}.patch"
+    patch_path = run_state_directory / patch_name
+    patch_bytes = diff_text.encode(UTF8_ENCODING)
+    patch_path.write_bytes(patch_bytes)
+    content_hash = compute_sha256_hex(patch_bytes)
+    report_hash = compute_sha256_hex(worker_report_text.encode(UTF8_ENCODING))
+    manifest = {
+        "schema_version": LEDGER_SCHEMA_VERSION,
+        "task_id": task_id,
+        "base_sha": base_sha,
+        "changed_paths": list(changed_paths),
+        "patch_path": str(patch_path),
+        "content_sha256": content_hash,
+        "worker_report_sha256": report_hash,
+    }
+    manifest_path = run_state_directory / PATCH_MANIFEST_FILENAME
+    manifest_path.write_text(
+        json.dumps(manifest, indent=JSON_INDENT) + "\n",
+        encoding=UTF8_ENCODING,
+    )
+    return manifest

package/scripts/grok_run_ledger.py

@@ -0,0 +1,318 @@
+#!/usr/bin/env python3
+"""Host-neutral file-backed ledger for Grok orchestration task state.
+
+Records every delegated unit before dispatch, enforces one live owner and one
+unique advisor session per in-progress task, blocks on unfinished dependencies,
+and reopens tasks when the base snapshot drifts.
+
+::
+
+    ledger = GrokRunLedger(run_state_directory)
+    ledger.register_task(task_id="O-04", dependencies=())
+    ledger.mark_in_progress(
+        task_id="O-04",
+        owner_id="worker-1",
+        advisor_session_id="sess-1",
+        base_sha="abc",
+    )
+    ok: task status becomes in_progress with that owner and session
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+
+from dev_env_scripts_constants.grok_run_ledger_constants import (
+    ALL_LEGAL_TASK_STATUSES,
+    JSON_INDENT,
+    LEDGER_FILENAME,
+    LEDGER_SCHEMA_VERSION,
+    TASK_STATUS_ADVISOR_BLOCKED,
+    TASK_STATUS_COMPLETED,
+    TASK_STATUS_IN_PROGRESS,
+    TASK_STATUS_PENDING,
+    TASK_STATUS_PENDING_REVIEW,
+    TEMPORARY_LEDGER_PREFIX,
+    TEMPORARY_LEDGER_SUFFIX,
+    UTF8_ENCODING,
+)
+
+
+@dataclass
+class LedgerTaskRecord:
+    """One delegated unit tracked in the run ledger."""
+
+    task_id: str
+    status: str = TASK_STATUS_PENDING
+    dependencies: tuple[str, ...] = ()
+    owner_id: str | None = None
+    advisor_session_id: str | None = None
+    advisor_verdict: str | None = None
+    base_sha: str | None = None
+    reviewed_head: str | None = None
+    changed_paths: tuple[str, ...] = ()
+    acceptance_mapping: dict[str, str] = field(default_factory=dict)
+    test_evidence: list[str] = field(default_factory=list)
+
+
+class GrokRunLedger:
+    """Atomic file-backed ledger: register_task, get_task, can_dispatch, mark_in_progress, mark_completed, mark_advisor_blocked, invalidate_on_snapshot_drift, all_tasks."""
+
+    def __init__(self, run_state_directory: Path) -> None:
+        self.run_state_directory = Path(run_state_directory)
+        self.ledger_path = self.run_state_directory / LEDGER_FILENAME
+        self._task_by_id: dict[str, LedgerTaskRecord] = {}
+        self.run_state_directory.mkdir(parents=True, exist_ok=True)
+        if self.ledger_path.is_file():
+            self._load()
+
+    def _load(self) -> None:
+        payload = json.loads(self.ledger_path.read_text(encoding=UTF8_ENCODING))
+        for each_task in payload.get("tasks", []):
+            record = LedgerTaskRecord(
+                task_id=each_task["task_id"],
+                status=each_task["status"],
+                dependencies=tuple(each_task.get("dependencies") or ()),
+                owner_id=each_task.get("owner_id"),
+                advisor_session_id=each_task.get("advisor_session_id"),
+                advisor_verdict=each_task.get("advisor_verdict"),
+                base_sha=each_task.get("base_sha"),
+                reviewed_head=each_task.get("reviewed_head"),
+                changed_paths=tuple(each_task.get("changed_paths") or ()),
+                acceptance_mapping=dict(each_task.get("acceptance_mapping") or {}),
+                test_evidence=list(each_task.get("test_evidence") or []),
+            )
+            self._task_by_id[record.task_id] = record
+
+    def _atomic_write(self) -> None:
+        document = {
+            "schema_version": LEDGER_SCHEMA_VERSION,
+            "tasks": [
+                {
+                    **asdict(each_record),
+                    "dependencies": list(each_record.dependencies),
+                    "changed_paths": list(each_record.changed_paths),
+                }
+                for each_record in sorted(
+                    self._task_by_id.values(), key=lambda item: item.task_id
+                )
+            ],
+        }
+        encoded = json.dumps(document, indent=JSON_INDENT) + "\n"
+        file_descriptor, temporary_path = tempfile.mkstemp(
+            dir=self.run_state_directory,
+            prefix=TEMPORARY_LEDGER_PREFIX,
+            suffix=TEMPORARY_LEDGER_SUFFIX,
+        )
+        try:
+            with os.fdopen(file_descriptor, "w", encoding=UTF8_ENCODING) as handle:
+                handle.write(encoded)
+                handle.flush()
+                os.fsync(handle.fileno())
+            os.replace(temporary_path, self.ledger_path)
+        except (OSError, TypeError, ValueError):
+            if os.path.exists(temporary_path):
+                os.unlink(temporary_path)
+            raise
+
+    def register_task(
+        self,
+        *,
+        task_id: str,
+        all_dependencies: tuple[str, ...] = (),
+    ) -> LedgerTaskRecord:
+        """Record a delegated unit before dispatch.
+
+        Args:
+            task_id: Stable task identifier.
+            all_dependencies: Task ids that must complete before dispatch.
+
+        Returns:
+            The registered pending task record.
+
+        Raises:
+            ValueError: When the task id already exists.
+        """
+        if task_id in self._task_by_id:
+            raise ValueError(f"task already registered: {task_id}")
+        record = LedgerTaskRecord(
+            task_id=task_id,
+            status=TASK_STATUS_PENDING,
+            dependencies=all_dependencies,
+        )
+        self._task_by_id[task_id] = record
+        self._atomic_write()
+        return record
+
+    def get_task(self, task_id: str) -> LedgerTaskRecord:
+        """Return one task record.
+
+        Args:
+            task_id: Stable task identifier.
+
+        Returns:
+            The stored task record.
+
+        Raises:
+            KeyError: When the task id is unknown.
+        """
+        return self._task_by_id[task_id]
+
+    def can_dispatch(self, task_id: str) -> bool:
+        """Return whether every dependency has completed successfully.
+
+        Args:
+            task_id: Task to evaluate.
+
+        Returns:
+            True when every dependency is ``completed``.
+        """
+        record = self.get_task(task_id)
+        for each_dependency in record.dependencies:
+            dependency_record = self._task_by_id.get(each_dependency)
+            if dependency_record is None:
+                return False
+            if dependency_record.status != TASK_STATUS_COMPLETED:
+                return False
+        return True
+
+    def mark_in_progress(
+        self,
+        *,
+        task_id: str,
+        owner_id: str,
+        advisor_session_id: str,
+        base_sha: str,
+    ) -> LedgerTaskRecord:
+        """Assign one owner and unique advisor session and start the task.
+
+        Args:
+            task_id: Task to start.
+            owner_id: Live owner identity.
+            advisor_session_id: Unique advisor session for this worker.
+            base_sha: Snapshot SHA at dispatch.
+
+        Returns:
+            The updated task record.
+
+        Raises:
+            ValueError: When dispatch is blocked, another owner is live, the
+                advisor session is reused, or status is illegal.
+        """
+        if not self.can_dispatch(task_id):
+            raise ValueError(f"dependencies incomplete for {task_id}")
+        for each_record in self._task_by_id.values():
+            if (
+                each_record.status == TASK_STATUS_IN_PROGRESS
+                and each_record.owner_id == owner_id
+                and each_record.task_id != task_id
+            ):
+                raise ValueError(f"owner already live on {each_record.task_id}")
+            if (
+                each_record.advisor_session_id == advisor_session_id
+                and each_record.task_id != task_id
+            ):
+                raise ValueError(
+                    f"advisor session already bound to {each_record.task_id}"
+                )
+        record = self.get_task(task_id)
+        if record.status not in {TASK_STATUS_PENDING, TASK_STATUS_PENDING_REVIEW}:
+            raise ValueError(f"cannot start task from status {record.status}")
+        record.status = TASK_STATUS_IN_PROGRESS
+        record.owner_id = owner_id
+        record.advisor_session_id = advisor_session_id
+        record.base_sha = base_sha
+        self._atomic_write()
+        return record
+
+    def mark_completed(
+        self,
+        *,
+        task_id: str,
+        reviewed_head: str,
+        all_changed_paths: tuple[str, ...],
+        advisor_verdict: str,
+        all_acceptance_mapping: dict[str, str],
+        all_test_evidence: list[str],
+    ) -> LedgerTaskRecord:
+        """Record successful terminal state for an in-progress task.
+
+        Args:
+            task_id: Task to complete.
+            reviewed_head: Final reviewed commit SHA.
+            all_changed_paths: Paths changed by the worker.
+            advisor_verdict: Opening advisor signal (for example ENDORSE).
+            all_acceptance_mapping: Acceptance criterion to evidence map.
+            all_test_evidence: Commands or artifacts proving tests.
+
+        Returns:
+            The completed task record.
+
+        Raises:
+            ValueError: When the task is not in progress.
+        """
+        record = self.get_task(task_id)
+        if record.status != TASK_STATUS_IN_PROGRESS:
+            raise ValueError(f"cannot complete task from status {record.status}")
+        record.status = TASK_STATUS_COMPLETED
+        record.reviewed_head = reviewed_head
+        record.changed_paths = all_changed_paths
+        record.advisor_verdict = advisor_verdict
+        record.acceptance_mapping = dict(all_acceptance_mapping)
+        record.test_evidence = list(all_test_evidence)
+        self._atomic_write()
+        return record
+
+    def mark_advisor_blocked(self, *, task_id: str, reason: str) -> LedgerTaskRecord:
+        """Stop a task because the advisor path failed closed.
+
+        Args:
+            task_id: Task to block.
+            reason: Short failure reason stored in test evidence.
+
+        Returns:
+            The blocked task record.
+        """
+        record = self.get_task(task_id)
+        record.status = TASK_STATUS_ADVISOR_BLOCKED
+        record.test_evidence = [reason]
+        self._atomic_write()
+        return record
+
+    def invalidate_on_snapshot_drift(
+        self,
+        *,
+        task_id: str,
+        current_sha: str,
+    ) -> LedgerTaskRecord:
+        """Move a task back to pending review when the base snapshot drifts.
+
+        Args:
+            task_id: Task to invalidate.
+            current_sha: Live SHA compared to the recorded base.
+
+        Returns:
+            The updated task record (unchanged when SHAs match).
+        """
+        record = self.get_task(task_id)
+        if record.base_sha is None or record.base_sha == current_sha:
+            return record
+        record.status = TASK_STATUS_PENDING_REVIEW
+        record.owner_id = None
+        self._atomic_write()
+        return record
+
+    def all_tasks(self) -> tuple[LedgerTaskRecord, ...]:
+        """Return every task record sorted by task id."""
+        return tuple(
+            sorted(self._task_by_id.values(), key=lambda item: item.task_id)
+        )
+
+
+def is_legal_status(status: str) -> bool:
+    """Return whether a status token is in the legal set."""
+    return status in ALL_LEGAL_TASK_STATUSES

package/scripts/profile-isolation-launchers/config/mcp-bundles.json

@@ -0,0 +1,25 @@
+{
+  "schemaVersion": 1,
+  "supportedActivationInterface": "claude-config-dir-mcp-json",
+  "mcpConfigFileName": "mcp.json",
+  "bundles": {
+    "lean": {
+      "id": "lean",
+      "allServerNames": ["filesystem-readonly"]
+    },
+    "full": {
+      "id": "full",
+      "allServerNames": ["filesystem-readonly", "github-readonly"]
+    }
+  },
+  "serverByName": {
+    "filesystem-readonly": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "${PROFILE_ROOT}"]
+    },
+    "github-readonly": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"]
+    }
+  }
+}

package/scripts/profile-isolation-launchers/config/profile-isolation-constants.mjs

@@ -0,0 +1,60 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const CONFIG_DIRECTORY_PATH = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * @param {string} fileName
+ * @returns {unknown}
+ */
+function readJsonConfigFile(fileName) {
+  const absolutePath = join(CONFIG_DIRECTORY_PATH, fileName);
+  return JSON.parse(readFileSync(absolutePath, 'utf8'));
+}
+
+export const PROFILES_MANIFEST_FILE_NAME = 'profiles.manifest.json';
+export const SHARED_ALLOWLIST_FILE_NAME = 'shared-allowlist.json';
+
+/**
+ * Sole authoritative profile-root environment variable for CLI isolation.
+ * CLAUDE_HOME is never honored as a profile root by this contract.
+ */
+export const CLAUDE_CONFIG_DIR_ENVIRONMENT_VARIABLE = 'CLAUDE_CONFIG_DIR';
+export const CLAUDE_HOME_ENVIRONMENT_VARIABLE = 'CLAUDE_HOME';
+export const CLAUDE_CODE_TMPDIR_ENVIRONMENT_VARIABLE = 'CLAUDE_CODE_TMPDIR';
+export const CLAUDE_CODE_PLUGIN_SEED_DIR_ENVIRONMENT_VARIABLE = 'CLAUDE_CODE_PLUGIN_SEED_DIR';
+
+export const PROFILES_ROOT_ENVIRONMENT_VARIABLE = 'LLM_SETTINGS_PROFILES_ROOT';
+export const SHARED_SOURCE_ROOT_ENVIRONMENT_VARIABLE = 'LLM_SETTINGS_SHARED_SOURCE_ROOT';
+export const PLUGIN_SEED_ROOT_ENVIRONMENT_VARIABLE = 'LLM_SETTINGS_PLUGIN_SEED_ROOT';
+
+export const DEFAULT_PROFILES_ROOT_DIRECTORY_NAME = '.claude-profiles';
+export const DEFAULT_SHARED_SOURCE_DIRECTORY_NAME = 'shared-source';
+export const DEFAULT_PLUGIN_SEED_DIRECTORY_NAME = 'plugin-seed';
+
+export const MIGRATION_MODE_CLEAN_LOCAL_RUNTIME = 'clean-local-runtime';
+export const MIGRATION_MODE_MATERIALIZE_FROM_LEGACY = 'materialize-from-legacy';
+
+export const MCP_BUNDLE_LEAN = 'lean';
+export const MCP_BUNDLE_FULL = 'full';
+
+export const LAUNCHER_SCHEMA_VERSION = 1;
+export const PROFILE_ISOLATION_CONTRACT_OWNER = 'profile-isolation-contract';
+export const PACKAGE_FILES_WHITELIST_SCRIPTS_ENTRY = 'scripts/';
+export const LIVE_DEPLOYMENT_RESERVED_FOR = 'L1';
+export const INSTALL_DESTINATION_ROOT_RELATIVE_PATH = 'scripts/profile-isolation-launchers';
+
+/**
+ * @returns {Record<string, unknown>}
+ */
+export function loadProfilesManifestDocument() {
+  return /** @type {Record<string, unknown>} */ (readJsonConfigFile(PROFILES_MANIFEST_FILE_NAME));
+}
+
+/**
+ * @returns {Record<string, unknown>}
+ */
+export function loadSharedAllowlistDocument() {
+  return /** @type {Record<string, unknown>} */ (readJsonConfigFile(SHARED_ALLOWLIST_FILE_NAME));
+}

package/scripts/profile-isolation-launchers/config/profiles.manifest.json

@@ -0,0 +1,54 @@
+{
+  "schemaVersion": 1,
+  "profilesRootPlaceholder": "${PROFILES_ROOT}",
+  "sharedSourcePlaceholder": "${SHARED_SOURCE_ROOT}",
+  "pluginSeedPlaceholder": "${PLUGIN_SEED_ROOT}",
+  "migrationOrder": ["profile-c", "profile-b", "profile-a", "master", "profile-d"],
+  "profiles": {
+    "master": {
+      "id": "master",
+      "aliases": ["default"],
+      "directoryName": "master",
+      "launcherNames": ["claude"],
+      "fullLauncherNames": ["claude-full"],
+      "migrationMode": "materialize-from-legacy",
+      "mcpBundle": "lean"
+    },
+    "profile-a": {
+      "id": "profile-a",
+      "aliases": [],
+      "directoryName": "profile-a",
+      "launcherNames": ["claude-profile-a"],
+      "fullLauncherNames": ["claude-profile-a-full"],
+      "migrationMode": "materialize-from-legacy",
+      "mcpBundle": "lean"
+    },
+    "profile-c": {
+      "id": "profile-c",
+      "aliases": [],
+      "directoryName": "profile-c",
+      "launcherNames": ["claude-profile-c"],
+      "fullLauncherNames": ["claude-profile-c-full"],
+      "migrationMode": "clean-local-runtime",
+      "mcpBundle": "lean"
+    },
+    "profile-b": {
+      "id": "profile-b",
+      "aliases": [],
+      "directoryName": "profile-b",
+      "launcherNames": ["claude-profile-b"],
+      "fullLauncherNames": ["claude-profile-b-full"],
+      "migrationMode": "clean-local-runtime",
+      "mcpBundle": "lean"
+    },
+    "profile-d": {
+      "id": "profile-d",
+      "aliases": [],
+      "directoryName": "profile-d",
+      "launcherNames": ["claude-profile-d"],
+      "fullLauncherNames": ["claude-profile-d-full"],
+      "migrationMode": "clean-local-runtime",
+      "mcpBundle": "lean"
+    }
+  }
+}

package/scripts/profile-isolation-launchers/config/shared-allowlist.json

@@ -0,0 +1,64 @@
+{
+  "schemaVersion": 1,
+  "description": "Read-mostly paths shared across CLI profiles via links. Everything else defaults to physical profile-local.",
+  "allSharedRelativePaths": [
+    "CLAUDE.md",
+    "agents",
+    "skills",
+    "rules",
+    "commands",
+    "output-styles",
+    "system-prompts",
+    "audit-rubrics",
+    "docs",
+    "tools",
+    "hooks",
+    "scripts"
+  ],
+  "allAlwaysLocalRelativePaths": [
+    ".claude.json",
+    "settings.json",
+    "settings.local.json",
+    "credentials",
+    ".credentials.json",
+    "projects",
+    "sessions",
+    "history",
+    "history.jsonl",
+    "teams",
+    "tasks",
+    "jobs",
+    "daemon",
+    "plugins",
+    "marketplaces",
+    "registries",
+    "caches",
+    "file-history",
+    "shell-snapshots",
+    "browser",
+    "data",
+    "state",
+    "logs",
+    "locks",
+    "offsets",
+    "telemetry",
+    "verification",
+    "backups",
+    "tmp",
+    "tmpdir",
+    "session-env",
+    "statsig",
+    "todos",
+    "plans",
+    "debug",
+    ".state",
+    ".queue"
+  ],
+  "allDesktopExcludedPathFragments": [
+    "Claude Desktop",
+    "Claude Desktop Profiles",
+    "CLAUDE_USER_DATA_DIR",
+    "claude-desktop",
+    "Claude.exe"
+  ]
+}