sase-github 0.2.4__tar.gz → 0.2.6__tar.gz

sase_github-0.2.6/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.2.6"
+}

{sase_github-0.2.4 → sase_github-0.2.6}/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## [0.2.6](https://github.com/sase-org/sase-github/compare/v0.2.5...v0.2.6) (2026-08-18)
+
+
+### Features
+
+* claim GitHub workspaces atomically ([61dd36f](https://github.com/sase-org/sase-github/commit/61dd36fa1aef7ec71475608e19de3ddf91b67b74))
+* **workspace:** guard gh workflow steps against occupied checkouts ([51347d4](https://github.com/sase-org/sase-github/commit/51347d4f0a256c80785e7e2633fa589259073481))
+
+
+### Bug Fixes
+
+* **workspace:** release the gh setup claim when the occupancy guard refuses ([99a6277](https://github.com/sase-org/sase-github/commit/99a6277ecceb47d702c42351623ed27fbed11822))
+
+## [0.2.5](https://github.com/sase-org/sase-github/compare/v0.2.4...v0.2.5) (2026-08-18)
+
+
+### Features
+
+* register agent-uncreatable github task type ([a68b879](https://github.com/sase-org/sase-github/commit/a68b879ba9a8a0ca5dc6f253a0c66563f9a90d4b))
+
 ## [0.2.4](https://github.com/sase-org/sase-github/compare/v0.2.3...v0.2.4) (2026-08-11)
 
 

{sase_github-0.2.4 → sase_github-0.2.6}/CLAUDE.md

@@ -15,6 +15,7 @@ just check      # lint + test
 
 ## Architecture
 - `src/sase_github/plugin.py` — GitHubPlugin class (extends `sase.vcs_provider.plugins._git_common.GitCommon`)
+- `src/sase_github/task_types.py` — agent-uncreatable `github` task type via `sase_task_types`
 - `src/sase_github/xprompts/` — GitHub workflow YAML files discovered via `sase_xprompts` entry point
 - Depends on `sase>=0.1.3` for base classes, hookspec, and script modules
 

{sase_github-0.2.4 → sase_github-0.2.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sase-github
-Version: 0.2.4
+Version: 0.2.6
 Summary: GitHub VCS plugin for sase
 License-Expression: MIT
 License-File: LICENSE

{sase_github-0.2.4 → sase_github-0.2.6}/README.md

@@ -76,6 +76,10 @@ Requires `sase>=0.11.0` as a dependency. For GitHub Enterprise Server or self-ho
 - **`get_github_orgs()`** — Reads `github_orgs` from sase config to determine SSH vs HTTPS clone URLs for
   organizations/users with push access, and to seed local `#gh:` owner completion
 
+### Task type
+
+- **`github`** — Agent-uncreatable task type registered through the `sase_task_types` entry point. Beads of this type are created by SASE's external issue mirror, not by agents.
+
 ### XPrompts
 
 | XPrompt        | Description                                                                        |

{sase_github-0.2.4 → sase_github-0.2.6}/docs/architecture.md

@@ -14,6 +14,11 @@ Registered in `pyproject.toml`:
 | `sase_workspace:github`     | `GitHubWorkspacePlugin` | Workspace orchestration (ref resolution, submission, mail prep) |
 | `sase_xprompts:sase_github` | —                       | Makes `#gh`, `#new_pr_desc`, `#prdd` xprompts discoverable      |
 | `sase_config:sase_github`   | —                       | Contributes `default_config.yml` to the sase config chain       |
+| `sase_task_types:github`    | `GITHUB_TASK_TYPES`     | Agent-uncreatable `github` task type for mirrored issues        |
+
+### GitHub task type (`task_types.py`)
+
+Registers one `sase_task_types` spec: `task_type: github`, `agent_creatable: false`, no extra fields. Agents never create this type. SASE's external issue mirror stamps it on new mirrored task beads. This is not an `IssueType`; mirrored issues stay `task` beads with an `external_ref`.
 
 ### GitHubPlugin (`plugin.py`)
 

{sase_github-0.2.4 → sase_github-0.2.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sase-github"
-version = "0.2.4"
+version = "0.2.6"
 description = "GitHub VCS plugin for sase"
 requires-python = ">=3.12"
 license = "MIT"
@@ -32,6 +32,9 @@ sase_github = "sase_github"
 [project.entry-points."sase_xprompts"]
 sase_github = "sase_github"
 
+[project.entry-points."sase_task_types"]
+github = "sase_github.task_types:GITHUB_TASK_TYPES"
+
 [tool.hatch.build.targets.wheel]
 packages = ["src/sase_github"]
 

sase_github-0.2.6/src/sase_github/scripts/gh_setup.py

@@ -0,0 +1,257 @@
+"""Setup step for the #gh xprompt workflow."""
+
+import os
+import sys
+
+from sase.core.occupancy_guard import OccupancyCaller, ensure_workspace_not_occupied
+from sase.running_field import (
+    WorkspaceClaim,
+    claim_next_axe_workspace,
+    claim_workspace,
+    get_claimed_workspaces,
+    release_workspace,
+)
+from sase.sdd.store import materialize_sdd_store
+from sase.workspace_provider import resolve_ref
+from sase.workspace_provider.occupant import new_occupant_record, write_occupant_record
+from sase.workspace_provider.utils import ensure_workspace_checkout
+
+_CALLER_TAG = "gh-setup"
+
+
+def main(
+    *,
+    gh_ref: str,
+    n: int | None,
+    release: bool,
+    workflow_label: str | None = None,
+) -> None:
+    """Resolve GitHub ref, claim a workspace, and print config.
+
+    Prints key=value output for the workflow executor.
+    """
+    resolved = resolve_ref(gh_ref, "gh")
+
+    project_name = resolved.project_name
+    project_file = resolved.project_file
+    workflow_name = workflow_label or f"gh-{gh_ref}"
+    cl_name = None if "/" in gh_ref else gh_ref
+
+    # Use the parent process PID, not our own.  This setup step runs as a
+    # short-lived subprocess (via ``subprocess.run``), so ``os.getpid()``
+    # would die immediately after setup.  ``stale_running_cleanup`` would
+    # then incorrectly remove the RUNNING entry while the real workflow
+    # (the parent process) is still alive.
+    pid = os.getppid()
+
+    # Skip claiming when pre-allocated — the launcher already claimed the workspace
+    pre_allocated = os.environ.get("SASE_GH_PRE_ALLOCATED") == "1"
+    if pre_allocated:
+        workspace_num = int(os.environ["SASE_GH_WORKSPACE_NUM"])
+        workspace_dir = os.environ["SASE_GH_WORKSPACE_DIR"]
+        materialize_sdd_store(workspace_dir, workspace_num)
+    elif n is not None:
+        workspace_num, workspace_dir = _claim_pinned_workspace(
+            project_file=project_file,
+            primary_workspace_dir=resolved.primary_workspace_dir,
+            workspace_num=n,
+            workflow_name=workflow_name,
+            pid=pid,
+            cl_name=cl_name,
+            pinned=not release,
+        )
+    else:
+        workspace_num, workspace_dir = _claim_next_workspace(
+            project_file=project_file,
+            primary_workspace_dir=resolved.primary_workspace_dir,
+            workflow_name=workflow_name,
+            pid=pid,
+            cl_name=cl_name,
+            pinned=not release,
+        )
+
+    # Refuse to hand this checkout to `prepare`/`checkout` if another live
+    # agent still occupies it. Runs on the pre_allocated branch too: the
+    # launcher already wrote its own occupant record, and the conflict
+    # decision recognises the caller's own lineage via the shared pid.
+    # A refusal here aborts the step, so the slot this run just claimed must
+    # go back — the workflow's `release` step never runs once `setup` fails.
+    # The pre_allocated branch claimed nothing, so it releases nothing.
+    try:
+        ensure_workspace_not_occupied(
+            workspace_dir,
+            project_file=project_file,
+            caller=OccupancyCaller(
+                pid=pid,
+                workspace_num=workspace_num,
+                project=project_name,
+                workflow=workflow_name,
+            ),
+        )
+    except Exception:
+        if not pre_allocated:
+            release_workspace(
+                project_file,
+                workspace_num,
+                workflow_name,
+                cl_name,
+                caller_tag=_CALLER_TAG,
+            )
+        raise
+
+    # Claim the checkout for this run. Workspace numbers 0/1 both mean
+    # "primary", never a real numbered workspace (see
+    # ``ensure_workspace_checkout``), and the pre_allocated branch's
+    # occupant record already belongs to the launcher.
+    if not pre_allocated and workspace_num > 1:
+        write_occupant_record(
+            workspace_dir,
+            new_occupant_record(
+                pid=pid,
+                workflow=workflow_name,
+                project=project_name,
+                workspace_num=workspace_num,
+                cl_name=cl_name,
+            ),
+        )
+
+    print(f"project_name={project_name}")
+    print(f"project_file={project_file}")
+    print(f"workspace_dir={workspace_dir}")
+    print(f"workspace_num={workspace_num}")
+    print(f"checkout_target={resolved.checkout_target}")
+    print(f"primary_workspace_dir={resolved.primary_workspace_dir}")
+    # Don't release pre-allocated workspaces — the launcher handles that
+    should_release = release and not pre_allocated
+    print(f"should_release={'true' if should_release else 'false'}")
+    print(f"_chdir={workspace_dir}")
+    print(f"meta_workspace={workspace_num}")
+    print(f"workflow_name={workflow_name}")
+
+
+def _claim_next_workspace(
+    *,
+    project_file: str,
+    primary_workspace_dir: str,
+    workflow_name: str,
+    pid: int,
+    cl_name: str | None,
+    pinned: bool,
+) -> tuple[int, str]:
+    """Atomically allocate a slot, then materialize the checkout."""
+    workspace_num = claim_next_axe_workspace(
+        project_file,
+        workflow_name,
+        pid,
+        cl_name=cl_name,
+        pinned=pinned,
+        caller_tag=_CALLER_TAG,
+    )
+    workspace_dir = _materialize_or_release(
+        project_file=project_file,
+        primary_workspace_dir=primary_workspace_dir,
+        workspace_num=workspace_num,
+        workflow_name=workflow_name,
+        cl_name=cl_name,
+    )
+    return workspace_num, workspace_dir
+
+
+def _claim_pinned_workspace(
+    *,
+    project_file: str,
+    primary_workspace_dir: str,
+    workspace_num: int,
+    workflow_name: str,
+    pid: int,
+    cl_name: str | None,
+    pinned: bool,
+) -> tuple[int, str]:
+    """Claim a pinned ``n=<num>`` target once. Occupied slots fail with the occupant named."""
+    claim_result = claim_workspace(
+        project_file,
+        workspace_num,
+        workflow_name,
+        pid,
+        cl_name,
+        pinned=pinned,
+        caller_tag=_CALLER_TAG,
+    )
+    if not claim_result.success:
+        occupant = _describe_workspace_occupant(project_file, workspace_num)
+        if occupant is not None:
+            print(
+                f"Pinned workspace #{workspace_num} is already claimed by {occupant}",
+                file=sys.stderr,
+            )
+        else:
+            print(
+                f"Pinned workspace #{workspace_num} could not be claimed: "
+                f"{claim_result.error or 'unknown reason'}",
+                file=sys.stderr,
+            )
+        sys.exit(1)
+    workspace_dir = _materialize_or_release(
+        project_file=project_file,
+        primary_workspace_dir=primary_workspace_dir,
+        workspace_num=workspace_num,
+        workflow_name=workflow_name,
+        cl_name=cl_name,
+    )
+    return workspace_num, workspace_dir
+
+
+def _materialize_or_release(
+    *,
+    project_file: str,
+    primary_workspace_dir: str,
+    workspace_num: int,
+    workflow_name: str,
+    cl_name: str | None,
+) -> str:
+    """Materialize after a successful claim; release the slot if setup fails."""
+    try:
+        workspace_dir = ensure_workspace_checkout(primary_workspace_dir, workspace_num)
+        materialize_sdd_store(workspace_dir, workspace_num)
+    except Exception:
+        release_workspace(
+            project_file,
+            workspace_num,
+            workflow_name,
+            cl_name,
+            caller_tag=_CALLER_TAG,
+        )
+        raise
+    return workspace_dir
+
+
+def _describe_workspace_occupant(project_file: str, workspace_num: int) -> str | None:
+    occupants = [
+        claim
+        for claim in get_claimed_workspaces(project_file)
+        if claim.workspace_num == workspace_num
+    ]
+    if not occupants:
+        return None
+    return "; ".join(_format_workspace_occupant(claim) for claim in occupants)
+
+
+def _format_workspace_occupant(claim: WorkspaceClaim) -> str:
+    name = claim.cl_name or claim.workflow
+    liveness = "live" if _pid_is_alive(claim.pid) else "dead"
+    detail = f"{name} (pid {claim.pid}, {liveness}, workflow {claim.workflow}"
+    if claim.artifacts_timestamp:
+        detail += f", artifacts {claim.artifacts_timestamp}"
+    return detail + ")"
+
+
+def _pid_is_alive(pid: int) -> bool:
+    if pid <= 0:
+        return False
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True
+    return True

sase_github-0.2.6/src/sase_github/task_types.py

@@ -0,0 +1,46 @@
+"""Declarative ``github`` task-type spec for the sase-github plugin.
+
+Mirrored GitHub issues are already ``task`` beads created by sase's external
+issue mirror. This spec stamps that origin as an agent-uncreatable catalog
+member; it does not add an ``IssueType.GITHUB``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+from sase.task_types import hookimpl
+
+_TASK_TYPE_SPEC_SCHEMA_VERSION = 1
+
+GITHUB_TASK_TYPE = "github"
+
+GITHUB_TASK_TYPE_SPEC: Mapping[str, Any] = {
+    "schema_version": _TASK_TYPE_SPEC_SCHEMA_VERSION,
+    "task_type": GITHUB_TASK_TYPE,
+    "label": "GitHub",
+    "summary": (
+        "A GitHub issue mirrored into a task bead; agents never create this type."
+    ),
+    "when_to_use": (
+        "Agents never create this type. Beads of it are created by the "
+        "external issue mirror when it covers a GitHub issue. Do not file "
+        "one from `sase bead create` or `/sase_new_task`."
+    ),
+    "glyph": "⑂",
+    "accent_color": "#B2B2B2",
+    "agent_creatable": False,
+    "fields": [],
+}
+
+
+class _GitHubTaskTypes:
+    """Pluggy hookimpl exposing the ``github`` task-type spec."""
+
+    @hookimpl
+    def task_type_specs(self) -> tuple[Mapping[str, Any], ...]:
+        return (GITHUB_TASK_TYPE_SPEC,)
+
+
+GITHUB_TASK_TYPES = _GitHubTaskTypes()

{sase_github-0.2.4 → sase_github-0.2.6}/src/sase_github/workspace_plugin.py

@@ -487,10 +487,14 @@ class GitHubWorkspacePlugin:
             kill_and_persist_all_running_processes,
         )
         from sase.ace.operations import has_active_children
+        from sase.core.occupancy_guard import (
+            OccupancyCaller,
+            WorkspaceOccupiedError,
+            ensure_workspace_not_occupied,
+        )
         from sase.running_field import (
-            claim_workspace,
-            get_first_available_axe_workspace,
-            get_workspace_directory_for_num,
+            WorkspaceClaimError,
+            claim_next_axe_workspace_dir,
             release_workspace,
         )
         from sase.vcs_provider import get_vcs_provider
@@ -536,36 +540,42 @@ class GitHubWorkspacePlugin:
         if not workspace_dir:
             return (False, "WORKSPACE_DIR is not set for this project")
 
-        workspace_num = get_first_available_axe_workspace(patch_file)
         workflow_name = f"submit-{patch_name}"
-        pid = os.getpid()
-
         try:
-            ws_dir, _ = get_workspace_directory_for_num(workspace_num, project_basename)
-        except RuntimeError as e:
-            return (False, f"Failed to get workspace directory: {e}")
+            workspace_num, ws_dir, _ = claim_next_axe_workspace_dir(
+                patch_file,
+                workflow_name,
+                os.getpid(),
+                project_basename,
+                cl_name=patch_name,
+                caller_tag="gh-submit",
+            )
+        except WorkspaceClaimError as exc:
+            return (False, f"Failed to claim workspace: {exc}")
 
         if rich_console:
             rich_console.print(f"[cyan]Claiming workspace #{workspace_num}[/cyan]")
 
-        if not claim_workspace(
-            patch_file,
-            workspace_num,
-            workflow_name,
-            pid,
-            patch_name,
-        ):
-            return (
-                False,
-                f"Failed to claim workspace #{workspace_num}",
-            )
-
         try:
             if rich_console:
                 rich_console.print(
                     f"[cyan]Checking out {escape_markup(patch_name)}...[/cyan]"
                 )
 
+            try:
+                ensure_workspace_not_occupied(
+                    ws_dir,
+                    project_file=patch_file,
+                    caller=OccupancyCaller(
+                        pid=os.getpid(),
+                        workspace_num=workspace_num,
+                        project=project_basename,
+                        workflow=workflow_name,
+                    ),
+                )
+            except WorkspaceOccupiedError as exc:
+                return (False, f"Refusing checkout: {exc}")
+
             provider = get_vcs_provider(ws_dir)
             branch_name = provider.resolve_revision(
                 patch_name, project_basename, ws_dir
@@ -619,6 +629,7 @@ class GitHubWorkspacePlugin:
                 workspace_num,
                 workflow_name,
                 patch_name,
+                caller_tag="gh-submit",
             )
             if rich_console:
                 rich_console.print(f"[cyan]Released workspace #{workspace_num}[/cyan]")

{sase_github-0.2.4 → sase_github-0.2.6}/src/sase_github/xprompts/gh.yml

@@ -120,13 +120,16 @@ steps:
     if: "{{ setup.should_release }}"
     python: |
       from sase.running_field import release_workspace
+      from sase.workspace_provider.occupant import clear_occupant_record
 
       release_workspace(
           {{ setup.project_file | tojson }},
           {{ setup.workspace_num }},
           {{ setup.workflow_name | tojson }},
           {{ gh_ref | tojson }} if "/" not in {{ gh_ref | tojson }} else None,
+          caller_tag="gh-release",
       )
+      clear_occupant_record({{ setup.workspace_dir | tojson }})
       print("released=true")
     output: { released: bool }