arctx-cli 0.2.0b2__tar.gz → 0.2.0b3__tar.gz

{arctx_cli-0.2.0b2 → arctx_cli-0.2.0b3}/PKG-INFO

@@ -1,11 +1,12 @@
 Metadata-Version: 2.4
 Name: arctx-cli
-Version: 0.2.0b2
-Summary: ARCTX CLI: command-line interface for arctx
-Project-URL: Homepage, https://github.com/takumiecd/stag
-Project-URL: Repository, https://github.com/takumiecd/stag
+Version: 0.2.0b3
+Summary: CLI for ARCTX — append-only DAG for reasoning history and parallel agent work
+Project-URL: Homepage, https://github.com/takumiecd/arctx
+Project-URL: Repository, https://github.com/takumiecd/arctx
 Author: Takumi Ishida
 License: MIT
+Keywords: agents,arctx,cli,dag,developer-tools,workflow
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -13,8 +14,10 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
 Requires-Python: >=3.10
-Requires-Dist: arctx>=0.2.0b2
+Requires-Dist: arctx>=0.2.0b3
 Provides-Extra: dev
 Requires-Dist: black>=23.0; extra == 'dev'
 Requires-Dist: mypy>=1.0; extra == 'dev'

{arctx_cli-0.2.0b2 → arctx_cli-0.2.0b3}/pyproject.toml

@@ -4,14 +4,15 @@ build-backend = "hatchling.build"
 
 [project]
 name = "arctx-cli"
-version = "0.2.0b2"
-description = "ARCTX CLI: command-line interface for arctx"
+version = "0.2.0b3"
+description = "CLI for ARCTX — append-only DAG for reasoning history and parallel agent work"
 readme = "README.md"
 requires-python = ">=3.10"
 license = {text = "MIT"}
 authors = [
     {name = "Takumi Ishida"},
 ]
+keywords = ["cli", "arctx", "dag", "agents", "developer-tools", "workflow"]
 classifiers = [
     "Development Status :: 4 - Beta",
     "Intended Audience :: Developers",
@@ -20,9 +21,11 @@ classifiers = [
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Utilities",
 ]
 dependencies = [
-    "arctx>=0.2.0b2",
+    "arctx>=0.2.0b3",
 ]
 
 [project.optional-dependencies]
@@ -38,8 +41,8 @@ dev = [
 arctx = "arctx_cli.main:main"
 
 [project.urls]
-Homepage = "https://github.com/takumiecd/stag"
-Repository = "https://github.com/takumiecd/stag"
+Homepage = "https://github.com/takumiecd/arctx"
+Repository = "https://github.com/takumiecd/arctx"
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/arctx_cli"]

{arctx_cli-0.2.0b2 → arctx_cli-0.2.0b3}/src/arctx_cli/commands/__init__.py

@@ -17,6 +17,8 @@ def core_cli_commands() -> list[CliCommand]:
     from arctx_cli.commands.cut import cli_cut
     from arctx_cli.commands.dump import add_parser as add_dump_parser
     from arctx_cli.commands.dump import cli_dump
+    from arctx_cli.commands.export import add_parser as add_export_parser
+    from arctx_cli.commands.export import cli_export
     from arctx_cli.commands.ext import add_parser as add_ext_parser
     from arctx_cli.commands.ext import cli_ext
     from arctx_cli.commands.graph import add_parser as add_graph_parser
@@ -58,6 +60,7 @@ def core_cli_commands() -> list[CliCommand]:
         CliCommand("current", add_current_parser, cli_current),
         CliCommand("ext", add_ext_parser, cli_ext),
         CliCommand("dump", add_dump_parser, cli_dump),
+        CliCommand("export", add_export_parser, cli_export),
         CliCommand("graph", add_graph_parser, cli_graph),
         CliCommand("guide", add_guide_parser, cli_guide),
         CliCommand("init", add_init_parser, cli_init),

arctx_cli-0.2.0b3/src/arctx_cli/commands/export.py

@@ -0,0 +1,66 @@
+"""arctx CLI export command: render a run as markdown, LaTeX, or HTML.
+
+Unlike ``dump`` (inspection / LLM), ``export`` produces a standalone document
+to share. By default it strips machine-local data (repo ``local_path``); pass
+``--include-local`` to keep it. ``--exclude-cut`` drops cut history.
+"""
+
+from __future__ import annotations
+
+import argparse
+
+from arctx.core.run.export import ExportOptions, export
+from arctx_cli.context import resolve_run_id_from_args, resolve_store
+
+
+def add_parser(subparsers) -> argparse.ArgumentParser:
+    parser = subparsers.add_parser(
+        "export",
+        help="Export the run as a shareable document (md / tex / html)",
+    )
+    parser.add_argument(
+        "--format",
+        dest="fmt",
+        choices=["md", "tex", "html"],
+        default="md",
+        help="Output format (default: md)",
+    )
+    parser.add_argument("--node", dest="node_id", default=None,
+                        help="Export only the subtree rooted at this node")
+    parser.add_argument("--depth", type=int, default=None,
+                        help="Limit traversal depth")
+    parser.add_argument("--full-payloads", action="store_true",
+                        help="Include full payload content")
+    parser.add_argument("--exclude-cut", action="store_true",
+                        help="Drop cut (inactive) nodes and transitions")
+    parser.add_argument("--include-local", action="store_true",
+                        help="Keep repo local_path in the output (off by default)")
+    parser.add_argument("--output", "-o", default=None,
+                        help="Write to this file instead of stdout")
+    parser.add_argument("--run", default=None)
+    parser.add_argument("--store-dir", default=None)
+    return parser
+
+
+def cli_export(args) -> int:
+    store = resolve_store(args.store_dir)
+    run_id = resolve_run_id_from_args(args)
+    if not store.run_path(run_id).exists():
+        raise KeyError(f"unknown run_id: {run_id}")
+    handle = store.load_run(run_id)
+
+    opts = ExportOptions(
+        node_id=args.node_id,
+        depth=args.depth,
+        full_payloads=args.full_payloads,
+        exclude_cut=args.exclude_cut,
+        include_local=args.include_local,
+    )
+    text = export(handle, args.fmt, opts)
+    if args.output:
+        with open(args.output, "w", encoding="utf-8") as f:
+            f.write(text)
+        print(f"wrote {args.output}")
+    else:
+        print(text)
+    return 0

{arctx_cli-0.2.0b2 → arctx_cli-0.2.0b3}/src/arctx_cli/commands/git.py

@@ -31,6 +31,7 @@ def add_parser(subparsers) -> argparse.ArgumentParser:
     from arctx_cli.ext.git.hook import add_parser as add_hook_parser
     from arctx_cli.ext.git.merge import add_parser as add_merge_parser
     from arctx_cli.ext.git.reset import add_parser as add_reset_parser
+    from arctx_cli.ext.git.repo import add_init_parser, add_repo_parser
     from arctx_cli.ext.git.revert import add_parser as add_revert_parser
     from arctx_cli.ext.git.verify import add_parser as add_verify_parser
     from arctx_cli.ext.git.worktree import add_parser as add_worktree_parser
@@ -39,7 +40,9 @@ def add_parser(subparsers) -> argparse.ArgumentParser:
     add_cherry_pick_parser(git_sub)
     add_commit_parser(git_sub)
     add_hook_parser(git_sub)
+    add_init_parser(git_sub)
     add_merge_parser(git_sub)
+    add_repo_parser(git_sub)
     add_reset_parser(git_sub)
     add_revert_parser(git_sub)
     add_verify_parser(git_sub)
@@ -100,10 +103,18 @@ def cli_git(args) -> int:
         return cli_commit(args)
     if args.git_command == "hook":
         return cli_hook(args)
+    if args.git_command == "init":
+        from arctx_cli.ext.git.repo import cli_git_init  # noqa: PLC0415
+
+        return cli_git_init(args)
     if args.git_command == "list":
         return _cli_git_list(args)
     if args.git_command == "merge":
         return cli_merge(args)
+    if args.git_command == "repo":
+        from arctx_cli.ext.git.repo import cli_repo  # noqa: PLC0415
+
+        return cli_repo(args)
     if args.git_command == "reset":
         return cli_reset(args)
     if args.git_command == "revert":

{arctx_cli-0.2.0b2 → arctx_cli-0.2.0b3}/src/arctx_cli/commands/use.py

@@ -19,6 +19,15 @@ def add_parser(subparsers) -> argparse.ArgumentParser:
         default=None,
         help="Directory where runs are stored (default: <ARCTX_HOME>/runs)",
     )
+    parser.add_argument(
+        "--shell",
+        action="store_true",
+        help=(
+            "Print 'export ARCTX_RUN_ID=<run>' for this terminal instead of "
+            "writing the repo's persistent pointer. Use as: "
+            'eval "$(arctx use <run> --shell)"'
+        ),
+    )
     return parser
 
 
@@ -26,8 +35,15 @@ def run_use_command(
     *,
     run_id: str,
     store_dir: str | None,
+    shell: bool = False,
 ) -> dict:
-    """Set the current run by writing its id to ``<gitdir>/arctx-id``.
+    """Set the current run.
+
+    By default this writes the run id to ``<gitdir>/arctx-id`` — a persistent,
+    repo-scoped default that every terminal in that checkout sees. With
+    *shell* set, nothing is written; the caller is expected to ``eval`` the
+    emitted ``export ARCTX_RUN_ID=<run>`` line to pin the run for the current
+    terminal only (env beats the repo pointer in the resolution chain).
 
     Parameters
     ----------
@@ -35,23 +51,29 @@ def run_use_command(
         Identifier of the run.
     store_dir:
         Directory where runs are stored.
+    shell:
+        Emit a shell ``export`` line (terminal-scoped) instead of writing the
+        repo pointer.
 
     Returns
     -------
-    dict with ``run_id`` and ``arctx_id_path`` keys.
+    dict with ``run_id``; ``arctx_id_path`` (repo mode) or ``export`` (shell
+    mode).
 
     Raises
     ------
     KeyError
         If the run_id does not exist in the store.
     RuntimeError
-        If not inside a git repository.
+        If not inside a git repository (repo mode only).
     """
     resolved_store_dir = store_dir if store_dir is not None else resolve_store_dir()
     store = resolve_store(resolved_store_dir)
     run_path = store.run_path(run_id)
     if not run_path.exists():
         raise KeyError(f"unknown run_id: {run_id}")
+    if shell:
+        return {"run_id": run_id, "export": f"export ARCTX_RUN_ID={run_id}"}
     repo_root = find_repo_root()
     write_arctx_id(repo_root, run_id)
     return {"run_id": run_id, "arctx_id_path": str(arctx_id_path(repo_root))}
@@ -62,6 +84,10 @@ def cli_use(args) -> int:
     result = run_use_command(
         run_id=args.run_id,
         store_dir=args.store_dir,
+        shell=getattr(args, "shell", False),
     )
-    print(result["run_id"])
+    if "export" in result:
+        print(result["export"])
+    else:
+        print(result["run_id"])
     return 0

arctx_cli-0.2.0b3/src/arctx_cli/ext/git/repo.py

@@ -0,0 +1,231 @@
+"""arctx git repo — manage the run's git repo registry (the repo 対応表).
+
+One run can span several git repos. ``repo add`` is the "途中で入れる" verb:
+it registers a repo into an already-running run (RepoPayload + ``.arctx-id``
+pointer + ``.arctx-repo`` marker, and optionally installs hooks). ``arctx git
+init`` is a thin wrapper that always installs hooks.
+
+``repo list`` / ``repo show`` inspect the registry. These are local-inspection
+commands (like ``dump``), so they show ``local_path`` by default — export is
+the outlet that strips it for sharing.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from arctx_cli.context import (
+    resolve_run_id_from_args,
+    resolve_store,
+    resolve_user_id_from_args,
+    resolve_work_session_id_from_args,
+)
+
+
+# ---------------------------------------------------------------------------
+# Parser registration
+# ---------------------------------------------------------------------------
+
+
+def add_repo_parser(git_sub) -> argparse.ArgumentParser:
+    p = git_sub.add_parser("repo", help="Manage the run's git repo registry (対応表)")
+    sub = p.add_subparsers(dest="repo_command", required=True)
+
+    add = sub.add_parser(
+        "add", help="Register a git repo into the current run (途中で入れる)"
+    )
+    _add_common(add)
+    add.add_argument("--repo-path", default=None, help="Repo working tree (default: cwd)")
+    add.add_argument("--slug", default=None, help="Override display slug (USER/REPO)")
+    add.add_argument("--no-hooks", action="store_true", help="Skip installing git hooks")
+    add.add_argument("--user", default=None)
+    add.add_argument("--work-session", default=None)
+
+    lst = sub.add_parser("list", help="List repos registered in the run")
+    _add_common(lst)
+
+    show = sub.add_parser("show", help="Show one repo registry entry as JSON")
+    _add_common(show)
+    show.add_argument("--repo-id", default=None, help="Repo id (default: resolve cwd)")
+    show.add_argument("--repo-path", default=None, help="Resolve by working tree instead")
+
+    return p
+
+
+def add_init_parser(git_sub) -> argparse.ArgumentParser:
+    p = git_sub.add_parser(
+        "init",
+        help="Set up git integration for the current run on this repo "
+        "(registers the repo and installs hooks)",
+    )
+    _add_common(p)
+    p.add_argument("--repo-path", default=None, help="Repo working tree (default: cwd)")
+    p.add_argument("--slug", default=None, help="Override display slug (USER/REPO)")
+    p.add_argument("--no-hooks", action="store_true", help="Skip installing git hooks")
+    p.add_argument("--user", default=None)
+    p.add_argument("--work-session", default=None)
+    return p
+
+
+def _add_common(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--run", default=None)
+    p.add_argument("--store-dir", default=None)
+
+
+# ---------------------------------------------------------------------------
+# add (the primitive; git init wraps it)
+# ---------------------------------------------------------------------------
+
+
+def run_repo_add(
+    *,
+    repo_path: str | None,
+    slug: str | None,
+    run_id: str | None,
+    store_dir: str | None,
+    user_id: str | None,
+    work_session_id: str | None,
+    install_hooks: bool,
+) -> dict:
+    from arctx.ext.git.helpers.repo import resolve_worktree_path
+    from arctx.ext.git.registry import list_repos, repo_by_id, resolve_repo_id
+    from arctx.paths import find_repo_root, write_arctx_id
+
+    store = resolve_store(store_dir)
+    handle = store.load_run(run_id)
+
+    resolved_path = resolve_worktree_path(repo_path)
+    existing_ids = {r.repo_id for r in list_repos(handle.run_graph)}
+    repo_id = resolve_repo_id(handle, resolved_path, slug=slug)
+    entry = repo_by_id(handle.run_graph, repo_id)
+
+    if repo_id not in existing_ids and entry is not None:
+        handle.record_work_event(
+            user_id=user_id,
+            work_session_id=work_session_id,
+            event_type="repo_added",
+            target_kind="node",
+            target_id=handle.root_node_id,
+            created_records=(entry.payload_id,),
+            summary=f"repo {entry.slug or repo_id} added",
+            data={"repo_id": repo_id, "slug": entry.slug, "canonical": entry.canonical},
+        )
+
+    store.save_run(handle)
+
+    # Point this repo's checkout at the run so future commands resolve it.
+    try:
+        repo_root = find_repo_root(resolved_path)
+        write_arctx_id(repo_root, handle.run_id)
+    except RuntimeError:
+        repo_root = Path(resolved_path)
+
+    hooks: dict | None = None
+    if install_hooks:
+        from arctx_cli.ext.git.hook import run_hook_install
+
+        hooks = run_hook_install(repo_path=repo_root)
+
+    result: dict = {
+        "run_id": handle.run_id,
+        "repo_id": repo_id,
+        "slug": entry.slug if entry else None,
+        "canonical": entry.canonical if entry else None,
+        "local_path": entry.local_path if entry else None,
+    }
+    if hooks is not None:
+        result["hooks"] = hooks.get("status")
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Dispatch
+# ---------------------------------------------------------------------------
+
+
+def cli_repo(args) -> int:
+    if args.repo_command == "add":
+        return _cli_repo_add(args)
+    if args.repo_command == "list":
+        return _cli_repo_list(args)
+    if args.repo_command == "show":
+        return _cli_repo_show(args)
+    print(f"unknown repo subcommand: {args.repo_command}", file=sys.stderr)
+    return 1
+
+
+def cli_git_init(args) -> int:
+    try:
+        result = run_repo_add(
+            repo_path=args.repo_path,
+            slug=args.slug,
+            run_id=resolve_run_id_from_args(args),
+            store_dir=args.store_dir,
+            user_id=resolve_user_id_from_args(args),
+            work_session_id=resolve_work_session_id_from_args(args),
+            install_hooks=not args.no_hooks,
+        )
+    except Exception as exc:  # noqa: BLE001
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    print(json.dumps(result, indent=2))
+    return 0
+
+
+def _cli_repo_add(args) -> int:
+    try:
+        result = run_repo_add(
+            repo_path=args.repo_path,
+            slug=args.slug,
+            run_id=resolve_run_id_from_args(args),
+            store_dir=args.store_dir,
+            user_id=resolve_user_id_from_args(args),
+            work_session_id=resolve_work_session_id_from_args(args),
+            install_hooks=not args.no_hooks,
+        )
+    except Exception as exc:  # noqa: BLE001
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    print(json.dumps(result, indent=2))
+    return 0
+
+
+def _cli_repo_list(args) -> int:
+    from arctx.ext.git.registry import list_repos
+
+    store = resolve_store(args.store_dir)
+    run_id = resolve_run_id_from_args(args)
+    handle = store.load_run(run_id)
+    entries = [r.to_dict() for r in list_repos(handle.run_graph)]
+    print(json.dumps(entries, indent=2))
+    return 0
+
+
+def _cli_repo_show(args) -> int:
+    from arctx.ext.git.helpers.repo import resolve_worktree_path
+    from arctx.ext.git.registry import read_repo_marker, repo_by_id
+
+    store = resolve_store(args.store_dir)
+    run_id = resolve_run_id_from_args(args)
+    handle = store.load_run(run_id)
+
+    repo_id = args.repo_id
+    if repo_id is None:
+        marker = read_repo_marker(resolve_worktree_path(args.repo_path))
+        if marker is None:
+            print(
+                "error: no --repo-id given and no .arctx-repo marker found in cwd",
+                file=sys.stderr,
+            )
+            return 1
+        repo_id = marker
+
+    entry = repo_by_id(handle.run_graph, repo_id)
+    if entry is None:
+        print(f"error: repo not found in run: {repo_id}", file=sys.stderr)
+        return 1
+    print(json.dumps(entry.to_dict(), indent=2))
+    return 0

arctx_cli-0.2.0b3/tests/cli/test_git_repo.py

@@ -0,0 +1,118 @@
+"""Integration tests for `arctx git repo` / `arctx git init` with real repos."""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+from arctx_cli.commands.init import run_init_command
+from arctx_cli.context import resolve_store
+from arctx_cli.ext.git.repo import run_repo_add
+
+
+def _init_git_repo(path: Path, *, remote: str | None = None) -> Path:
+    path.mkdir(parents=True, exist_ok=True)
+    subprocess.run(["git", "init"], cwd=str(path), capture_output=True, check=True)
+    subprocess.run(["git", "config", "user.email", "t@e.com"], cwd=str(path),
+                   capture_output=True, check=True)
+    subprocess.run(["git", "config", "user.name", "t"], cwd=str(path),
+                   capture_output=True, check=True)
+    subprocess.run(["git", "checkout", "-b", "main"], cwd=str(path),
+                   capture_output=True, check=True)
+    (path / "README.md").write_text("hello\n")
+    subprocess.run(["git", "add", "."], cwd=str(path), capture_output=True, check=True)
+    subprocess.run(["git", "commit", "-m", "init"], cwd=str(path),
+                   capture_output=True, check=True)
+    if remote is not None:
+        subprocess.run(["git", "remote", "add", "origin", remote], cwd=str(path),
+                       capture_output=True, check=True)
+    return path
+
+
+def _store_dir(tmp_path: Path) -> str:
+    return str(tmp_path / "arctx_home" / "runs")
+
+
+def _init_run(tmp_path: Path, run_id: str) -> None:
+    run_init_command(
+        requirement_id="req1",
+        target_type="task",
+        target_id="t",
+        run_id=run_id,
+        store_dir=_store_dir(tmp_path),
+        extensions=["git"],
+    )
+
+
+class TestRepoAdd:
+    def test_add_registers_repo_and_persists(self, tmp_path, monkeypatch):
+        repo = _init_git_repo(tmp_path / "repo", remote="git@github.com:me/proj.git")
+        monkeypatch.setenv("ARCTX_HOME", str(tmp_path / "arctx_home"))
+        monkeypatch.chdir(repo)
+        _init_run(tmp_path, "run_a")
+
+        result = run_repo_add(
+            repo_path=str(repo),
+            slug=None,
+            run_id="run_a",
+            store_dir=_store_dir(tmp_path),
+            user_id="alice",
+            work_session_id="ws",
+            install_hooks=False,
+        )
+        assert result["repo_id"].startswith("repo_")
+        assert result["slug"] == "me/proj"
+        assert result["canonical"] == "github.com/me/proj"
+
+        # Reload from store: registry survived persistence.
+        store = resolve_store(_store_dir(tmp_path))
+        handle = store.load_run("run_a")
+        from arctx.ext.git.registry import list_repos
+
+        repos = list_repos(handle.run_graph)
+        assert [r.repo_id for r in repos] == [result["repo_id"]]
+        # .arctx-id pointer written for this repo.
+        from arctx.paths import read_arctx_id
+
+        assert read_arctx_id(repo) == "run_a"
+
+    def test_slug_override(self, tmp_path, monkeypatch):
+        repo = _init_git_repo(tmp_path / "repo", remote="git@github.com:me/proj.git")
+        monkeypatch.setenv("ARCTX_HOME", str(tmp_path / "arctx_home"))
+        monkeypatch.chdir(repo)
+        _init_run(tmp_path, "run_b")
+
+        result = run_repo_add(
+            repo_path=str(repo),
+            slug="custom/name",
+            run_id="run_b",
+            store_dir=_store_dir(tmp_path),
+            user_id="alice",
+            work_session_id="ws",
+            install_hooks=False,
+        )
+        assert result["slug"] == "custom/name"
+
+    def test_idempotent_re_add(self, tmp_path, monkeypatch):
+        repo = _init_git_repo(tmp_path / "repo", remote="git@github.com:me/proj.git")
+        monkeypatch.setenv("ARCTX_HOME", str(tmp_path / "arctx_home"))
+        monkeypatch.chdir(repo)
+        _init_run(tmp_path, "run_c")
+
+        first = run_repo_add(
+            repo_path=str(repo), slug=None, run_id="run_c",
+            store_dir=_store_dir(tmp_path), user_id="alice",
+            work_session_id="ws", install_hooks=False,
+        )
+        second = run_repo_add(
+            repo_path=str(repo), slug=None, run_id="run_c",
+            store_dir=_store_dir(tmp_path), user_id="alice",
+            work_session_id="ws", install_hooks=False,
+        )
+        assert first["repo_id"] == second["repo_id"]
+
+        store = resolve_store(_store_dir(tmp_path))
+        handle = store.load_run("run_c")
+        from arctx.ext.git.registry import list_repos
+
+        assert len(list_repos(handle.run_graph)) == 1

{arctx_cli-0.2.0b2 → arctx_cli-0.2.0b3}/tests/cli/test_init_stag_id.py

@@ -182,6 +182,58 @@ def test_use_raises_for_unknown_run(tmp_path, monkeypatch):
         run_use_command(run_id="no_such_run", store_dir=_store_dir(tmp_path))
 
 
+def test_use_shell_emits_export_without_writing_pointer(tmp_path, monkeypatch):
+    repo = _fake_git_repo(tmp_path)
+    monkeypatch.setenv("ARCTX_HOME", str(_arctx_home(tmp_path)))
+    monkeypatch.chdir(repo)
+    run_init_command(
+        requirement_id="req1", target_type="task", target_id="t",
+        run_id="run_a", store_dir=_store_dir(tmp_path),
+    )
+    run_init_command(
+        requirement_id="req2", target_type="task", target_id="t",
+        run_id="run_b", store_dir=_store_dir(tmp_path),
+    )
+    # After the two inits the repo pointer is run_b.
+    assert read_arctx_id(repo) == "run_b"
+
+    result = run_use_command(
+        run_id="run_a", store_dir=_store_dir(tmp_path), shell=True
+    )
+
+    # Shell mode emits an export line for eval and leaves the repo pointer
+    # untouched (terminal-scoped, not repo-scoped).
+    assert result["export"] == "export ARCTX_RUN_ID=run_a"
+    assert read_arctx_id(repo) == "run_b"
+
+
+def test_use_shell_validates_run_exists(tmp_path, monkeypatch):
+    repo = _fake_git_repo(tmp_path)
+    monkeypatch.setenv("ARCTX_HOME", str(_arctx_home(tmp_path)))
+    monkeypatch.chdir(repo)
+
+    with pytest.raises(KeyError, match="unknown run_id"):
+        run_use_command(run_id="nope", store_dir=_store_dir(tmp_path), shell=True)
+
+
+def test_use_shell_works_outside_git_repo(tmp_path, monkeypatch):
+    # No .git here: shell mode must not require a repo (it writes no pointer).
+    monkeypatch.setenv("ARCTX_HOME", str(_arctx_home(tmp_path)))
+    monkeypatch.chdir(tmp_path)
+    run_init_command(
+        requirement_id="req1",
+        target_type="task",
+        target_id="t",
+        run_id="run_a",
+        store_dir=_store_dir(tmp_path),
+    )
+
+    result = run_use_command(
+        run_id="run_a", store_dir=_store_dir(tmp_path), shell=True
+    )
+    assert result["export"] == "export ARCTX_RUN_ID=run_a"
+
+
 # ---------------------------------------------------------------------------
 # ARCTX_HOME env overrides run storage location end-to-end
 # ---------------------------------------------------------------------------