multi-forge 0.2.0__py3-none-any.whl

forge/session/active.py

@@ -0,0 +1,339 @@
+"""Runtime active-session registry for live Claude launches.
+
+This registry is separate from session manifests and the global session index.
+It stores ephemeral "session is currently launched" state so Forge can warn
+before deleting a live session and self-heal stale entries after crashes.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from contextlib import contextmanager
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Callable, Iterator
+
+import dacite
+
+from forge.core.paths import get_forge_home
+from forge.core.process import is_pid_alive
+from forge.core.state import atomic_write_json, file_lock_for_target, now_iso
+
+from .config import LAUNCH_MODE_HOST, LAUNCH_MODE_SIDECAR
+
+logger = logging.getLogger(__name__)
+
+ACTIVE_INDEX_VERSION = 1
+ACTIVE_DIR = "sessions"
+ACTIVE_FILENAME = "active.json"
+CLI_LOCK_TIMEOUT_S = 5.0
+
+
+@dataclass
+class ActiveSessionEntry:
+    """Ephemeral runtime state for a currently launched session."""
+
+    worktree_path: str
+    started_at: str
+    launch_mode: str = LAUNCH_MODE_HOST
+    launcher_pid: int | None = None
+    claude_session_id: str | None = None
+    container_name: str | None = None
+    forge_root: str | None = None  # Scope axis (matches durable index)
+
+
+@dataclass
+class ActiveSessionIndex:
+    """All currently active sessions keyed by session name."""
+
+    version: int = ACTIVE_INDEX_VERSION
+    sessions: dict[str, ActiveSessionEntry] = field(default_factory=dict)
+
+
+def get_active_index_path() -> Path:
+    """Return the runtime active-session registry path."""
+    return get_forge_home() / ACTIVE_DIR / ACTIVE_FILENAME
+
+
+class ActiveSessionStore:
+    """Manage the runtime active-session registry."""
+
+    def __init__(self, index_path: Path | None = None) -> None:
+        self._index_path = index_path or get_active_index_path()
+
+    @property
+    def index_path(self) -> Path:
+        """Return the active-session registry path."""
+        return self._index_path
+
+    def exists(self) -> bool:
+        """Return True when the registry file exists."""
+        return self._index_path.is_file()
+
+    def read(self) -> ActiveSessionIndex:
+        """Read the registry, returning an empty registry when missing."""
+        if not self.exists():
+            return ActiveSessionIndex()
+
+        with open(self._index_path, encoding="utf-8") as f:
+            data = json.load(f)
+
+        version = data.get("version")
+        if version != ACTIVE_INDEX_VERSION or not self._has_current_key_shape(data):
+            logger.info("Discarding incompatible active-session registry (version=%s)", version)
+            empty = ActiveSessionIndex()
+            self.write(empty)
+            return empty
+
+        return dacite.from_dict(
+            data_class=ActiveSessionIndex,
+            data=data,
+            config=dacite.Config(strict=True),
+        )
+
+    def _has_current_key_shape(self, data: dict[str, object]) -> bool:
+        """Return True when the registry uses scoped session keys."""
+        from forge.session.identity import make_scoped_key, session_name_from_key
+
+        sessions = data.get("sessions")
+        if not isinstance(sessions, dict):
+            return True
+
+        for key, entry_data in sessions.items():
+            if not isinstance(key, str) or not isinstance(entry_data, dict):
+                return False
+            root = entry_data.get("forge_root") or entry_data.get("worktree_path")
+            if not isinstance(root, str) or not root:
+                return False
+            display_name = session_name_from_key(key)
+            if key != make_scoped_key(display_name, root):
+                return False
+        return True
+
+    def write(self, index: ActiveSessionIndex) -> None:
+        """Write the registry atomically."""
+        atomic_write_json(self._index_path, asdict(index))
+
+    def upsert_session(
+        self,
+        session_name: str,
+        *,
+        worktree_path: str,
+        launch_mode: str,
+        launcher_pid: int | None = None,
+        claude_session_id: str | None = None,
+        container_name: str | None = None,
+        forge_root: str | None = None,
+    ) -> ActiveSessionEntry:
+        """Create or replace a live-session entry."""
+        from forge.session.identity import make_scoped_key
+
+        launcher_pid = os.getpid() if launcher_pid is None else launcher_pid
+        effective_forge_root = forge_root or worktree_path
+
+        with file_lock_for_target(target_path=self._index_path, timeout_s=CLI_LOCK_TIMEOUT_S):
+            index = self.read()
+            entry = ActiveSessionEntry(
+                worktree_path=worktree_path,
+                started_at=now_iso(),
+                launch_mode=launch_mode,
+                launcher_pid=launcher_pid,
+                claude_session_id=claude_session_id,
+                container_name=container_name,
+                forge_root=effective_forge_root,
+            )
+            key = make_scoped_key(session_name, effective_forge_root)
+            index.sessions[key] = entry
+            self.write(index)
+            return entry
+
+    def update_uuid(self, session_name: str, claude_session_id: str, forge_root: str | None = None) -> bool:
+        """Update the Claude UUID for an active session if it exists.
+
+        Best-effort: uses best-effort resolver when forge_root is None.
+        """
+        from forge.session.identity import resolve_key_best_effort
+
+        with file_lock_for_target(target_path=self._index_path, timeout_s=CLI_LOCK_TIMEOUT_S):
+            index = self.read()
+            key = resolve_key_best_effort(index.sessions, session_name, forge_root)
+            if key is None:
+                return False
+            index.sessions[key].claude_session_id = claude_session_id
+            self.write(index)
+            return True
+
+    def clear_session(self, session_name: str, forge_root: str | None = None) -> bool:
+        """Remove an active-session entry by session name.
+
+        Uses strict resolution when forge_root is None.
+        """
+        from forge.session.identity import resolve_key_strict
+
+        with file_lock_for_target(target_path=self._index_path, timeout_s=CLI_LOCK_TIMEOUT_S):
+            index = self.read()
+            key = resolve_key_strict(index.sessions, session_name, forge_root)
+            if key is None:
+                return False
+            del index.sessions[key]
+            self.write(index)
+            return True
+
+    def clear_by_claude_session_id(self, claude_session_id: str) -> bool:
+        """Remove an active-session entry by Claude UUID (scans all)."""
+        with file_lock_for_target(target_path=self._index_path, timeout_s=CLI_LOCK_TIMEOUT_S):
+            index = self.read()
+            removed = False
+            for key, entry in list(index.sessions.items()):
+                if entry.claude_session_id == claude_session_id:
+                    del index.sessions[key]
+                    removed = True
+            if removed:
+                self.write(index)
+            return removed
+
+    def get_session(self, session_name: str, forge_root: str | None = None) -> ActiveSessionEntry | None:
+        """Return the live entry for a session, pruning stale entries.
+
+        Uses strict resolution when forge_root is None.
+        """
+        from forge.session.identity import resolve_key_strict
+
+        with file_lock_for_target(target_path=self._index_path, timeout_s=CLI_LOCK_TIMEOUT_S):
+            index = self.read()
+            key = resolve_key_strict(index.sessions, session_name, forge_root)
+
+        if key is None:
+            return None
+        entry = index.sessions.get(key)
+        if entry is None:
+            return None
+        if self._entry_is_live(entry):
+            return entry
+
+        with file_lock_for_target(target_path=self._index_path, timeout_s=CLI_LOCK_TIMEOUT_S):
+            latest = self.read()
+            latest_entry = latest.sessions.get(key)
+            if latest_entry is None:
+                return None
+            if self._entry_is_live(latest_entry):
+                return latest_entry
+            del latest.sessions[key]
+            self.write(latest)
+            return None
+
+    def list_sessions(self) -> list[tuple[str, ActiveSessionEntry]]:
+        """List all live sessions, pruning stale entries on read.
+
+        Returns display names (not compound keys).
+        """
+        from forge.session.identity import session_name_from_key
+
+        with file_lock_for_target(target_path=self._index_path, timeout_s=CLI_LOCK_TIMEOUT_S):
+            index = self.read()
+
+        stale_keys = [key for key, entry in index.sessions.items() if not self._entry_is_live(entry)]
+        if stale_keys:
+            with file_lock_for_target(target_path=self._index_path, timeout_s=CLI_LOCK_TIMEOUT_S):
+                latest = self.read()
+                pruned_any = False
+                for key in stale_keys:
+                    entry = latest.sessions.get(key)
+                    if entry is None:
+                        continue
+                    if not self._entry_is_live(entry):
+                        del latest.sessions[key]
+                        pruned_any = True
+                if pruned_any:
+                    self.write(latest)
+                index = latest
+
+        return sorted(
+            [(session_name_from_key(k), e) for k, e in index.sessions.items()],
+            key=lambda item: item[0],
+        )
+
+    def is_session_active(self, session_name: str, forge_root: str | None = None) -> bool:
+        """Return True when the session still appears to be live.
+
+        Uses strict resolution when forge_root is None.
+        """
+        return self.get_session(session_name, forge_root=forge_root) is not None
+
+    def _entry_is_live(self, entry: ActiveSessionEntry) -> bool:
+        """Return True when the runtime entry still points at a live launch."""
+        if entry.launch_mode == LAUNCH_MODE_SIDECAR and entry.container_name:
+            try:
+                from forge.sidecar.docker import is_container_running
+
+                if is_container_running(entry.container_name):
+                    return True
+            except Exception:
+                logger.debug("Failed to probe sidecar container liveness", exc_info=True)
+
+        if entry.launcher_pid is not None and is_pid_alive(entry.launcher_pid):
+            return True
+
+        return False
+
+
+@contextmanager
+def track_active_session(
+    *,
+    session_name: str,
+    worktree_path: str,
+    launch_mode: str,
+    forge_root: str | None = None,
+    claude_session_id: str | None = None,
+    launcher_pid: int | None = None,
+    container_name: str | None = None,
+) -> Iterator[None]:
+    """Track a live Claude launch for the duration of a context manager."""
+    store = ActiveSessionStore()
+    effective_forge_root = forge_root or worktree_path
+
+    try:
+        store.upsert_session(
+            session_name,
+            worktree_path=worktree_path,
+            launch_mode=launch_mode,
+            launcher_pid=launcher_pid,
+            claude_session_id=claude_session_id,
+            container_name=container_name,
+            forge_root=effective_forge_root,
+        )
+    except Exception:
+        logger.debug("Failed to register active session '%s'", session_name, exc_info=True)
+
+    try:
+        yield
+    finally:
+        try:
+            store.clear_session(session_name, forge_root=effective_forge_root)
+        except Exception:
+            logger.debug("Failed to clear active session '%s'", session_name, exc_info=True)
+
+
+def run_with_active_session(
+    *,
+    session_name: str,
+    worktree_path: Path,
+    launch_mode: str,
+    forge_root: str | None = None,
+    claude_session_id: str | None = None,
+    runner: Callable[[], int],
+) -> int:
+    """Track a live session while invoking a Claude launcher callback."""
+    container_name = f"forge-{session_name}" if launch_mode == LAUNCH_MODE_SIDECAR else None
+
+    with track_active_session(
+        session_name=session_name,
+        worktree_path=str(worktree_path),
+        launch_mode=launch_mode,
+        forge_root=forge_root,
+        claude_session_id=claude_session_id,
+        container_name=container_name,
+    ):
+        return runner()

forge/session/artifacts.py

@@ -0,0 +1,202 @@
+"""Session artifact helpers.
+
+This module implements Forge-project-local artifact storage for sessions.
+
+Artifacts are stored under the **Forge project root** (``forge_root``):
+
+- <forge_root>/.forge/artifacts/<session_name>/plans/
+- <forge_root>/.forge/artifacts/<session_name>/transcripts/
+
+The session manifest records artifact paths under ``confirmed.artifacts`` as
+**forge-root-relative** paths (e.g., ``.forge/artifacts/...``).
+"""
+
+from __future__ import annotations
+
+import logging
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+
+from .claude.paths import find_project_root
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class ArtifactPaths:
+    """Computed artifact roots for a session."""
+
+    forge_root: Path
+    artifacts_root_abs: Path
+    artifacts_root_rel: Path
+
+    plans_abs: Path
+    plans_rel: Path
+
+    transcripts_abs: Path
+    transcripts_rel: Path
+
+
+def resolve_forge_root(cwd: Path) -> Path:
+    """Resolve the Forge project root for artifact storage.
+
+    Preference order:
+    1) Walk up from *cwd* looking for ``.forge/`` (Forge project anchor)
+    2) Fallback to git-aware main-repo detection (worktree safe)
+    3) Fallback to walking upwards for a ``.git`` entry
+    4) Final fallback to cwd
+
+    In most managed sessions, the caller should prefer the session's
+    stored ``forge_root`` over this heuristic.
+    """
+    # Prefer .forge/ directory as the Forge project anchor
+    from forge.core.ops.context import find_forge_root
+
+    forge_root = find_forge_root(cwd)
+    if forge_root is not None:
+        return forge_root
+
+    try:
+        from .worktree import get_main_repo_root
+
+        return get_main_repo_root(cwd)
+    except Exception as e:
+        logger.debug("get_main_repo_root failed: %s, trying find_project_root", e)
+        try:
+            return find_project_root(str(cwd))
+        except Exception as e2:
+            logger.debug("find_project_root failed: %s, falling back to cwd", e2)
+            return cwd.resolve()
+
+
+def get_artifact_paths(forge_root: Path, session_name: str) -> ArtifactPaths:
+    """Compute standard artifact directories for a session.
+
+    Args:
+        forge_root: Forge project root (where .forge/ lives).
+        session_name: Forge session name.
+
+    Returns:
+        ArtifactPaths with absolute + forge-root-relative paths.
+    """
+
+    forge_root = forge_root.resolve()
+
+    artifacts_root_rel = Path(".forge") / "artifacts" / session_name
+    artifacts_root_abs = forge_root / artifacts_root_rel
+
+    plans_rel = artifacts_root_rel / "plans"
+    plans_abs = forge_root / plans_rel
+
+    transcripts_rel = artifacts_root_rel / "transcripts"
+    transcripts_abs = forge_root / transcripts_rel
+
+    return ArtifactPaths(
+        forge_root=forge_root,
+        artifacts_root_abs=artifacts_root_abs,
+        artifacts_root_rel=artifacts_root_rel,
+        plans_abs=plans_abs,
+        plans_rel=plans_rel,
+        transcripts_abs=transcripts_abs,
+        transcripts_rel=transcripts_rel,
+    )
+
+
+def resolve_artifact_path(forge_root: Path, stored_path: str | Path | None) -> Path | None:
+    """Resolve a stored artifact path against the owning Forge project root.
+
+    Artifact paths recorded in manifests are normally forge-root-relative
+    (for example ``.forge/artifacts/...``), but this helper also accepts
+    absolute paths as a compatibility fallback.
+    """
+    if stored_path is None:
+        return None
+
+    candidate = Path(stored_path).expanduser()
+    if candidate.is_absolute():
+        return candidate
+    return forge_root.resolve() / candidate
+
+
+def ensure_dirs(paths: ArtifactPaths) -> None:
+    """Create artifact directories if needed."""
+
+    paths.plans_abs.mkdir(parents=True, exist_ok=True)
+    paths.transcripts_abs.mkdir(parents=True, exist_ok=True)
+
+
+def safe_copy_file(src: Path, dst: Path, *, overwrite: bool = False) -> bool:
+    """Copy a file with idempotent semantics.
+
+    Args:
+        src: Source file.
+        dst: Destination file.
+        overwrite: Whether to overwrite if dst exists.
+
+    Returns:
+        True if a copy occurred, False if skipped.
+
+    Raises:
+        FileNotFoundError: if src does not exist.
+    """
+
+    if not src.is_file():
+        raise FileNotFoundError(str(src))
+
+    dst.parent.mkdir(parents=True, exist_ok=True)
+
+    if dst.exists() and not overwrite:
+        return False
+
+    shutil.copy2(src, dst)
+    return True
+
+
+def make_timestamp_suffix() -> str:
+    """Return a filesystem-friendly UTC timestamp suffix (``YYYYMMDD_HHMMSS``)."""
+    from datetime import UTC, datetime
+
+    return datetime.now(UTC).strftime("%Y%m%d_%H%M%S")
+
+
+def make_content_hash(data: bytes, *, length: int = 12) -> str:
+    """Return a short hex digest for content-addressable filenames.
+
+    12 hex chars = 48 bits of entropy — enough that collisions across a single
+    user's plan history are not a practical concern.
+    """
+    import hashlib
+
+    return hashlib.sha256(data).hexdigest()[:length]
+
+
+def snapshot_plan_approved(
+    *,
+    paths: ArtifactPaths,
+    source_plan_path: Path,
+) -> tuple[Path, Path]:
+    """Snapshot an approved plan file into a human-readable destination.
+
+    Filename format: ``{stem}-{hash}.md`` where ``stem`` is the source plan's
+    filename stem and ``hash`` is a 12-char SHA-256 prefix of the file content.
+    Same source file with same content always produces the same path (dedup).
+    Different source filenames with identical content produce distinct paths —
+    accepted tradeoff for human-readable snapshot names.
+
+    Returns:
+        (snapshot_abs_path, snapshot_rel_path)
+    """
+
+    ensure_dirs(paths)
+
+    content = source_plan_path.read_bytes()
+    digest = make_content_hash(content)
+    stem = source_plan_path.stem or digest
+    dst_name = f"{stem}-{digest}.md"
+
+    snapshot_abs = paths.plans_abs / dst_name
+    snapshot_rel = paths.plans_rel / dst_name
+
+    safe_copy_file(source_plan_path, snapshot_abs, overwrite=False)
+    return snapshot_abs, snapshot_rel

forge/session/claude/__init__.py

@@ -0,0 +1,50 @@
+"""Claude Code integration utilities.
+
+This module provides utilities for:
+- Path encoding and transcript path resolution
+- Claude binary invocation
+- Session data cleanup (transcripts, agent logs)
+"""
+
+from __future__ import annotations
+
+from .cleanup import (
+    CleanupResult,
+    cleanup_session,
+    delete_session_data,
+)
+from .invoke import (
+    build_claude_args,
+    find_claude_binary,
+    invoke_claude,
+    is_claude_available,
+)
+from .paths import (
+    encode_project_path,
+    find_agent_logs,
+    find_project_root,
+    get_claude_home,
+    get_claude_projects_dir,
+    get_project_encoded_dir,
+    get_transcript_path,
+)
+
+__all__ = [
+    # Cleanup
+    "CleanupResult",
+    "cleanup_session",
+    "delete_session_data",
+    # Invoke
+    "build_claude_args",
+    "invoke_claude",
+    "find_claude_binary",
+    "is_claude_available",
+    # Paths
+    "encode_project_path",
+    "find_agent_logs",
+    "find_project_root",
+    "get_claude_home",
+    "get_claude_projects_dir",
+    "get_project_encoded_dir",
+    "get_transcript_path",
+]

forge/session/claude/cleanup.py

@@ -0,0 +1,105 @@
+"""Transcript and agent log cleanup utilities.
+
+This module provides utilities for deleting Claude session data:
+- Transcript files (.jsonl)
+- Agent log files (agent-*.jsonl)
+
+Under the 1:1 session model, each Forge session has one current claude_session_id.
+If /compact or /clear rolled over to a new UUID, older raw transcript UUIDs may
+also be tracked via transcript artifacts and should be cleaned up too.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .paths import find_agent_logs, get_transcript_path
+
+
+@dataclass
+class CleanupResult:
+    """Result of a cleanup operation.
+
+    Attributes:
+        deleted_transcripts: Paths to successfully deleted transcript files.
+        deleted_agent_logs: Paths to successfully deleted agent log files.
+        failed: List of (path, error_message) tuples for failed deletions.
+    """
+
+    deleted_transcripts: list[Path] = field(default_factory=list)
+    deleted_agent_logs: list[Path] = field(default_factory=list)
+    failed: list[tuple[Path, str]] = field(default_factory=list)
+
+    @property
+    def total_deleted(self) -> int:
+        """Total number of files successfully deleted."""
+        return len(self.deleted_transcripts) + len(self.deleted_agent_logs)
+
+    @property
+    def has_failures(self) -> bool:
+        """Whether any deletions failed."""
+        return len(self.failed) > 0
+
+
+def delete_session_data(
+    project_root: str,
+    session_ids: list[str],
+) -> CleanupResult:
+    """Delete transcript and agent log files for given session IDs.
+
+    Best-effort: continues even if some deletions fail.
+
+    Args:
+        project_root: Absolute path to project root (for transcript path encoding).
+        session_ids: List of Claude session UUIDs to clean up.
+
+    Returns:
+        CleanupResult with lists of deleted files and any failures.
+    """
+    result = CleanupResult()
+
+    for session_id in session_ids:
+        # Delete transcript
+        transcript_path = get_transcript_path(project_root, session_id)
+        if transcript_path.exists():
+            try:
+                transcript_path.unlink()
+                result.deleted_transcripts.append(transcript_path)
+            except OSError as e:
+                result.failed.append((transcript_path, str(e)))
+
+        # Delete agent logs
+        agent_logs = find_agent_logs(project_root, session_id)
+        for log_path in agent_logs:
+            try:
+                log_path.unlink()
+                result.deleted_agent_logs.append(log_path)
+            except OSError as e:
+                result.failed.append((log_path, str(e)))
+
+    return result
+
+
+def cleanup_session(
+    project_root: str,
+    claude_session_id: str | None,
+    artifact_session_ids: list[str] | None = None,
+) -> CleanupResult:
+    """Clean up session data for the session's tracked Claude UUIDs.
+
+    Args:
+        project_root: Absolute path to project root.
+        claude_session_id: Session UUID (from confirmed.claude_session_id).
+        artifact_session_ids: Additional UUIDs referenced by transcript artifacts.
+
+    Returns:
+        CleanupResult with lists of deleted files and any failures.
+    """
+    session_ids: list[str] = []
+
+    for session_id in [claude_session_id, *(artifact_session_ids or [])]:
+        if session_id and session_id not in session_ids:
+            session_ids.append(session_id)
+
+    return delete_session_data(project_root, session_ids)