sediment-cli 0.5.0__tar.gz → 0.6.1__tar.gz

sediment_cli-0.6.1/PKG-INFO

@@ -0,0 +1,71 @@
+Metadata-Version: 2.5
+Name: sediment-cli
+Version: 0.6.1
+Summary: A self-hosted evidence store for coding agents: the sediment CLI and local server
+Project-URL: Source, https://github.com/sediment-ai/sediment
+Project-URL: Documentation, https://docs.sediment.so
+Project-URL: Issues, https://github.com/sediment-ai/sediment/issues
+Project-URL: Changelog, https://github.com/sediment-ai/sediment/blob/main/CHANGELOG.md
+License-Expression: AGPL-3.0-or-later
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.27
+Requires-Dist: sediment-api==0.6.1
+Requires-Dist: sediment-core==0.6.1
+Requires-Dist: sediment-derive==0.6.1
+Requires-Dist: sediment-export==0.6.1
+Description-Content-Type: text/markdown
+
+# sediment-cli
+
+Sediment is an open-source, self-hosted evidence store for coding agents.
+
+Coding agents write a growing share of your code, but you can't tell which of
+their output a developer kept, which commits it reached, or whether those
+commits passed CI. Sediment records that evidence on your infrastructure: model
+calls, code changes, developer decisions, and check results. It links them so
+you can compare models, give agents earlier context, and build training data.
+
+This package installs the `sediment` command: the local server, agent capture,
+reports, and dataset exports.
+
+## Install
+
+Use Python 3.12:
+
+```sh
+pipx install sediment-cli    # or: uv tool install sediment-cli
+```
+
+Inside a virtual environment, `pip install sediment-cli` also works.
+
+`sediment server` downloads a PostgreSQL server that loads shared libraries
+from your system: `libpq` and `openssl@3` with Homebrew, or
+`git ca-certificates libpq5 libxml2 libzstd1 liblz4-1 zlib1g` with `apt-get` on Debian and Ubuntu. The
+[installer](https://sediment.so/install.sh) installs them for you:
+
+```sh
+curl -fsSL https://sediment.so/install.sh | sh
+```
+
+## Get started
+
+```sh
+sediment server                              # terminal 1
+sediment login http://127.0.0.1:8000         # terminal 2
+sediment install /path/to/your/repository
+```
+
+The [Quickstart](https://github.com/sediment-ai/sediment/blob/main/docs/quickstart.md)
+verifies capture end to end. If a coding agent helps you set up Sediment, give
+it the output of `sediment guide`.
+
+## Learn more
+
+- [Documentation](https://docs.sediment.so)
+- [Agent integrations](https://github.com/sediment-ai/sediment/blob/main/docs/capture/agent-integrations.md):
+  Claude Code, Codex, Cursor, pi, and Copilot Chat
+- [Source and issues](https://github.com/sediment-ai/sediment)
+
+Copyright (C) 2026 PAULSEN'S LLC. Sediment is licensed under
+[AGPL-3.0-or-later](https://github.com/sediment-ai/sediment/blob/main/LICENSE).

sediment_cli-0.6.1/README.md

@@ -0,0 +1,53 @@
+# sediment-cli
+
+Sediment is an open-source, self-hosted evidence store for coding agents.
+
+Coding agents write a growing share of your code, but you can't tell which of
+their output a developer kept, which commits it reached, or whether those
+commits passed CI. Sediment records that evidence on your infrastructure: model
+calls, code changes, developer decisions, and check results. It links them so
+you can compare models, give agents earlier context, and build training data.
+
+This package installs the `sediment` command: the local server, agent capture,
+reports, and dataset exports.
+
+## Install
+
+Use Python 3.12:
+
+```sh
+pipx install sediment-cli    # or: uv tool install sediment-cli
+```
+
+Inside a virtual environment, `pip install sediment-cli` also works.
+
+`sediment server` downloads a PostgreSQL server that loads shared libraries
+from your system: `libpq` and `openssl@3` with Homebrew, or
+`git ca-certificates libpq5 libxml2 libzstd1 liblz4-1 zlib1g` with `apt-get` on Debian and Ubuntu. The
+[installer](https://sediment.so/install.sh) installs them for you:
+
+```sh
+curl -fsSL https://sediment.so/install.sh | sh
+```
+
+## Get started
+
+```sh
+sediment server                              # terminal 1
+sediment login http://127.0.0.1:8000         # terminal 2
+sediment install /path/to/your/repository
+```
+
+The [Quickstart](https://github.com/sediment-ai/sediment/blob/main/docs/quickstart.md)
+verifies capture end to end. If a coding agent helps you set up Sediment, give
+it the output of `sediment guide`.
+
+## Learn more
+
+- [Documentation](https://docs.sediment.so)
+- [Agent integrations](https://github.com/sediment-ai/sediment/blob/main/docs/capture/agent-integrations.md):
+  Claude Code, Codex, Cursor, pi, and Copilot Chat
+- [Source and issues](https://github.com/sediment-ai/sediment)
+
+Copyright (C) 2026 PAULSEN'S LLC. Sediment is licensed under
+[AGPL-3.0-or-later](https://github.com/sediment-ai/sediment/blob/main/LICENSE).

{sediment_cli-0.5.0 → sediment_cli-0.6.1}/pyproject.toml

@@ -5,8 +5,9 @@
 # Depends on sediment-api deliberately: the operator verbs are DB-local by
 # design (ADR 0001) and `server`/reports/mirror-gc forward into it.
 name = "sediment-cli"
-version = "0.5.0"
-description = "The sediment command: login, install, server, facts, exports"
+version = "0.6.1"
+description = "A self-hosted evidence store for coding agents: the sediment CLI and local server"
+readme = "README.md"
 requires-python = ">=3.12"
 license = "AGPL-3.0-or-later"
 license-files = ["LICENSE"]
@@ -14,16 +15,16 @@ license-files = ["LICENSE"]
 # so an install never mixes member versions (the release workflow asserts
 # the versions agree before publishing).
 dependencies = [
-    "sediment-core==0.5.0",
-    "sediment-derive==0.5.0",
-    "sediment-export==0.5.0",
-    "sediment-api==0.5.0",
+    "sediment-core==0.6.1",
+    "sediment-derive==0.6.1",
+    "sediment-export==0.6.1",
+    "sediment-api==0.6.1",
     "httpx>=0.27",
 ]
 
 [project.urls]
 Source = "https://github.com/sediment-ai/sediment"
-Documentation = "https://github.com/sediment-ai/sediment/tree/main/docs"
+Documentation = "https://docs.sediment.so"
 Issues = "https://github.com/sediment-ai/sediment/issues"
 Changelog = "https://github.com/sediment-ai/sediment/blob/main/CHANGELOG.md"
 

{sediment_cli-0.5.0 → sediment_cli-0.6.1}/sediment_cli/_pi/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Sediment
+Copyright (c) 2026 PAULSEN'S LLC
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

{sediment_cli-0.5.0 → sediment_cli-0.6.1}/sediment_cli/_pi/README.md

@@ -195,7 +195,7 @@ delivery changes also trigger this workflow. To exercise the same tests locally,
 set `SEDIMENT_PI_TEST_PYTHON` to the installed environment's Python executable
 and `SEDIMENT_PI_TEST_INSTALLED_BIN` to its `bin` directory before `npm test`.
 
-The lockfile pins pi 0.87.1 (`@earendil-works/pi-coding-agent`) as a development
+The lockfile pins pi 1.1.0 (`@earendil-works/pi-coding-agent`) as a development
 dependency. The native retrieval test exercises its extension registration,
 argument validation, agent loop, and model-visible tool result with a scripted
 model stream. It makes no paid inference request and downloads no package during

{sediment_cli-0.5.0 → sediment_cli-0.6.1}/sediment_cli/_pi/package.json

@@ -13,8 +13,8 @@
     "typecheck": "tsc --noEmit"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "0.87.1",
-    "@types/node": "^24.19.0",
+    "@earendil-works/pi-coding-agent": "1.1.0",
+    "@types/node": "^24.19.2",
     "typescript": "^7.0.2"
   }
 }

{sediment_cli-0.5.0 → sediment_cli-0.6.1}/sediment_cli/agent_guide.txt

@@ -124,10 +124,11 @@ Follow [Secure a deployment](security.md) when handling secrets.
 
 Capture can leave the developer machine in these forms:
 
-- The pre-push hook sends the whole notes ref to each push remote, including
-  forks, even during `git push --dry-run`. Notes contain commit SHAs, agent
-  names, Session identifiers, and timestamps, including other branches' notes.
-  They don't contain prompts, diffs, file paths, model names, or hostnames.
+- The pre-push hook sends the whole notes ref to `origin` only, even during
+  `git push --dry-run`. A push to any other remote, such as a fork, sends and
+  fetches no notes. Notes contain commit SHAs, agent names, Session
+  identifiers, and timestamps, including other branches' notes. They don't
+  contain prompts, diffs, file paths, model names, or hostnames.
 - Agent telemetry goes to the Sediment server. Claude Code tool details can
   include paths, shell commands, edit text, and the Claude account email.
   Codex decisions can include patch code and tool arguments; Sediment removes

{sediment_cli-0.5.0 → sediment_cli-0.6.1}/sediment_cli/attribution.py

@@ -33,16 +33,19 @@ Stdlib only, no daemon. Nine subcommands:
                      and unions their already-written notes back into the
                      local marker file, so the post-commit ``stamp`` step
                      above writes a correct note on the squash commit too
-  push-notes REMOTE  pre-push hook: reconciles the notes ref with the remote
-                     (fetch + ``cat_sort_uniq`` union merge), then pushes it
-                     alongside the push, retrying once if the remote moved;
-                     a final failure is logged to
-                     ``~/.sediment/attribution.log``
+  push-notes REMOTE  pre-push hook: when the push goes to ``origin``,
+                     reconciles the notes ref with it (fetch +
+                     ``cat_sort_uniq`` union merge), then pushes it alongside
+                     the push, retrying once if the remote moved; a final
+                     failure is logged to ``~/.sediment/attribution.log``.
+                     A push to any other remote, such as a fork, syncs
+                     nothing and logs ``notes-push-skipped``
   repair-notes [REMOTE]
                      operator command (not a hook, NOT best-effort): the same
                      reconcile + push on demand, for a machine whose notes
                      ref already diverged, or a fresh machine adopting
-                     the remote's notes; exits non-zero on failure
+                     the remote's notes; exits non-zero on failure, and
+                     refuses a REMOTE that is not ``origin``
   doctor [REPO ...]  operator command: one-shot health check of everything
                      attribution needs on this machine — agent hook entries,
                      the fleet git template, the attribution log's recorded
@@ -748,6 +751,7 @@ _CAPTURE_FAILURE_REASONS = (
     "stamp_cleanup_unconfirmed",
     "notes_reconcile_busy",
     "notes_reconcile_failed",
+    "notes_remote_not_origin",
     "notes_lock_failed",
 )
 
@@ -1148,6 +1152,25 @@ def cmd_union_squash_notes(msg_file: str, source: str) -> int:
 # Where the remote's notes land during reconcile. A plain tracking ref, so a
 # failed merge can never damage the real local ref.
 NOTES_REMOTE_TRACKING_REF = "refs/notes/sediment-remote"
+NOTES_PUSH_TIMEOUT_SECONDS = 120
+
+
+def _is_notes_remote(remote: str) -> bool:
+    """True when ``remote`` is this repository's ``origin``, by name or URL.
+
+    Git hands ``pre-push`` whatever the developer pushes to. Reconciling
+    with a fork would union-merge notes its owner wrote into the ref the
+    server-side Attribution Derivation reads, and publish every local note
+    to that fork.
+    """
+    # ponytail: origin is the one notes remote, as in doctor and the owner
+    # allowlist; a git config key if a shared remote ever has another name.
+    origin = _git(["remote", "get-url", "origin"])
+    if not origin:
+        return False
+    # Expands a remote name or a URL alike, applying url.<base>.insteadOf.
+    url = _git(["ls-remote", "--get-url", remote]) or remote
+    return _normalize_remote(url) == _normalize_remote(origin)
 
 
 def _reconcile_notes(remote: str) -> bool:
@@ -1176,6 +1199,11 @@ def _reconcile_notes(remote: str) -> bool:
 
 def _reconcile_notes_locked(remote: str) -> bool:
     """The caller owns the common notes mutex, including the tracking-ref fetch."""
+    # The one guard every notes sync passes. The refusal makes
+    # ``_reconcile_notes`` return False, which also stops
+    # ``_reconciled_push`` before its push.
+    if not _is_notes_remote(remote):
+        raise _CaptureFailure("notes_remote_not_origin")
     if _git(["fetch", remote, f"+{NOTES_REF}:{NOTES_REMOTE_TRACKING_REF}"]) is None:
         return True  # remote unreachable or has no notes ref yet — the push decides
     if _git(["rev-parse", "--verify", "--quiet", NOTES_REF]) is None:
@@ -1219,18 +1247,49 @@ def _reconciled_push(remote: str) -> subprocess.CompletedProcess:
             return subprocess.CompletedProcess(
                 ["git", "push"], 1, "", "notes_reconcile_incomplete"
             )
-        result = subprocess.run(
-            ["git", "push", remote, f"{NOTES_REF}:{NOTES_REF}"],
-            capture_output=True,
-            text=True,
-            timeout=120,
-            env=env,
-        )
+        try:
+            result = subprocess.run(
+                ["git", "push", remote, f"{NOTES_REF}:{NOTES_REF}"],
+                capture_output=True,
+                text=True,
+                timeout=NOTES_PUSH_TIMEOUT_SECONDS,
+                env=env,
+            )
+        except subprocess.TimeoutExpired:
+            # Never surfaced: the exception text holds git's arguments, and
+            # ``remote`` can be a URL with credentials.
+            return subprocess.CompletedProcess(
+                ["git", "push"],
+                1,
+                "",
+                f"git push timed out after {NOTES_PUSH_TIMEOUT_SECONDS}s",
+            )
         if result.returncode == 0:
             break
     return result
 
 
+# ponytail: everything from "://" to the last "@" counts as userinfo, so an
+# "@" in a URL path, or later in the text, over-strips: ``https://host/a@b``
+# shows as ``https://b``. That is the safe side: a pattern that stops at "/"
+# or at whitespace passes ``scheme://user:pa/ss@host`` and
+# ``scheme://user:pass word@host`` through as typed. Parse the authority if
+# a hidden path segment ever matters.
+_URL_USERINFO_RE = re.compile(r"://.*@", re.DOTALL)
+
+
+def _strip_userinfo(text: str) -> str:
+    """``text`` with the userinfo cut from the URL in it.
+
+    Git hands ``pre-push`` a pushed URL exactly as typed, and Git before
+    2.27 repeats a push URL unchanged in its error line, so the remote
+    argument and the push diagnostic can each carry a credential. A remote
+    name, a bare path, and an scp-like ``user@host:path`` hold no ``://``
+    and pass through.
+    """
+    return _URL_USERINFO_RE.sub("://", text)
+
+
 def _push_failure_detail(result: subprocess.CompletedProcess) -> str:
     """Last stderr line, else last stdout line, else the exit code.
 
@@ -1239,10 +1298,10 @@ def _push_failure_detail(result: subprocess.CompletedProcess) -> str:
     """
     stderr = result.stderr.strip().splitlines()
     if stderr:
-        return stderr[-1]
+        return _strip_userinfo(stderr[-1])
     stdout = result.stdout.strip().splitlines()
     if stdout:
-        return stdout[-1]
+        return _strip_userinfo(stdout[-1])
     return f"exit {result.returncode}"
 
 
@@ -1250,9 +1309,10 @@ def _log_push_failure(remote: str, detail: str) -> None:
     """Log a ``notes-push-failed`` event naming the checkout when known.
 
     ``git_dir`` matches ``unhooked-repo`` so ``doctor`` can point at the
-    failing checkout the way it points at unhooked ones.
+    failing checkout the way it points at unhooked ones. ``remote`` is
+    logged without URL userinfo.
     """
-    fields: dict[str, str] = {"remote": remote, "detail": detail}
+    fields: dict[str, str] = {"remote": _strip_userinfo(remote), "detail": detail}
     git_dir = _git_dir(os.getcwd())
     if git_dir is not None:
         fields["git_dir"] = str(git_dir)
@@ -1262,6 +1322,9 @@ def _log_push_failure(remote: str, detail: str) -> None:
 def cmd_push_notes(remote: str) -> int:
     """pre-push: reconcile then push the notes ref, best-effort.
 
+    Syncs with ``origin`` only (``_is_notes_remote``); a push to any other
+    remote logs ``notes-push-skipped`` and leaves both notes refs untouched.
+
     A final failure prints one stderr line and logs a ``notes-push-failed``
     event to the local attribution log — a stderr line inside ``git push``
     output is not a signal anyone sees.
@@ -1275,12 +1338,17 @@ def cmd_push_notes(remote: str) -> int:
             return 0
         if _git(["rev-parse", "--verify", "--quiet", NOTES_REF]) is None:
             return 0  # nothing to push
+        if not _is_notes_remote(remote):
+            # A push to a fork is ordinary, so it is a skip and no failure.
+            # Content-free: a pushed URL can carry credentials.
+            _log_event("notes-push-skipped", git_dir=str(_git_dir(os.getcwd()) or ""))
+            return 0
         result = _reconciled_push(remote)
         if result.returncode != 0:
             detail = _push_failure_detail(result)
             print(
-                f"sediment-attribution: notes push to {remote} failed "
-                f"(push continues): {detail}",
+                f"sediment-attribution: notes push to {_strip_userinfo(remote)} "
+                f"failed (push continues): {detail}",
                 file=sys.stderr,
             )
             _log_push_failure(remote, detail)
@@ -1294,27 +1362,29 @@ def cmd_repair_notes(remote: str) -> int:
 
     The on-demand fix for a machine already in the diverged state, safe to
     run any time — fetch, union merge, push are each idempotent. On a fresh
-    machine with no local notes ref it adopts the remote's. Unlike the
+    machine with no local notes ref it adopts the remote's. A ``remote``
+    other than ``origin`` is refused (``notes_remote_not_origin``). Unlike the
     hooks this is NOT best-effort: it reports what happened and exits
     non-zero on failure so operators and scripts can trust the result.
     """
     if _git(["rev-parse", "--is-inside-work-tree"]) != "true":
         print("repair-notes: not inside a git work tree", file=sys.stderr)
         return 1
+    shown = _strip_userinfo(remote)
     if not _reconcile_notes(remote):
         return 1
     if _git(["rev-parse", "--verify", "--quiet", NOTES_REF]) is None:
-        print(f"repair-notes: no notes ref locally or on {remote}; nothing to do")
+        print(f"repair-notes: no notes ref locally or on {shown}; nothing to do")
         return 0
     result = _reconciled_push(remote)
     if result.returncode != 0:
         detail = _push_failure_detail(result)
-        print(f"repair-notes: push to {remote} failed: {detail}", file=sys.stderr)
+        print(f"repair-notes: push to {shown} failed: {detail}", file=sys.stderr)
         _log_push_failure(remote, detail)
         return 1
     print(
         f"{ui.glyph('✓', 'phosphor')}repair-notes: notes ref reconciled "
-        f"and pushed to {remote}"
+        f"and pushed to {shown}"
     )
     return 0
 
@@ -3758,7 +3828,17 @@ def build_parser() -> argparse.ArgumentParser:
         "--tool", required=True, choices=["claude-code", "codex", "cursor", "pi"]
     )
 
-    sub.add_parser("stamp", help="write the attribution note on HEAD (post-commit)")
+    sub.add_parser(
+        "stamp",
+        help="write the attribution note on HEAD (post-commit)",
+        description="Write this repository's pending Session markers to the "
+        "note on HEAD under refs/notes/sediment, then clear the markers that "
+        "it wrote. The post-commit hook runs this command after each commit. "
+        "Run it yourself only to recover a pending stamp, while HEAD is still "
+        "the commit that the markers belong to. The command always exits 0, "
+        "prints each failure on stderr, and logs it to "
+        "~/.sediment/attribution.log.",
+    )
 
     p_squash = sub.add_parser(
         "union-squash-notes",
@@ -3775,9 +3855,20 @@ def build_parser() -> argparse.ArgumentParser:
 
     p_repair = sub.add_parser(
         "repair-notes",
-        help="reconcile the notes ref with a remote and push (operator fix)",
+        help="reconcile a behind or diverged notes ref and push it (operator fix)",
+        description="Fetch refs/notes/sediment from the remote, union-merge it "
+        "into the local notes ref, and push the result. Run it inside a "
+        "repository when `sediment doctor --fetch` reports a notes ref that "
+        "is behind or diverged. Unlike the pre-push hook, the command exits 1 "
+        "when it can't reconcile or push.",
+    )
+    p_repair.add_argument(
+        "remote",
+        nargs="?",
+        default="origin",
+        help="remote to fetch from and push to; use origin, the remote that "
+        "doctor checks (default: origin)",
     )
-    p_repair.add_argument("remote", nargs="?", default="origin")
 
     p_doctor = sub.add_parser(
         "doctor",
@@ -3876,7 +3967,12 @@ def build_parser() -> argparse.ArgumentParser:
     )
 
     p_uninstall = sub.add_parser("uninstall", help="remove hooks from a repo")
-    p_uninstall.add_argument("repo", nargs="?", default=".")
+    p_uninstall.add_argument(
+        "repo",
+        nargs="?",
+        default=".",
+        help="repository to remove the git hooks from (default: current directory)",
+    )
     p_uninstall.add_argument(
         "--agents",
         action="store_true",

{sediment_cli-0.5.0 → sediment_cli-0.6.1}/sediment_cli/cli.py

@@ -87,9 +87,9 @@ from sediment_export import (
 )
 
 # The one-line answer to "what is this?", coder-style, shown beside the
-# version on the root --help title. With the title prefix it fills exactly
-# the pinned 80 columns. Keep in step with the root pyproject description.
-_TAGLINE = "Turn AI developer workflow traces into RL-ready training data."
+# version on the root --help title. Keep in step with the root pyproject
+# description and the README tagline.
+_TAGLINE = "A self-hosted evidence store for coding agents."
 
 _TABLES = [t.value for t in FactTable]
 
@@ -1596,9 +1596,10 @@ class _ArgumentParser(argparse.ArgumentParser):
 def _print_dispatched_help(parser: argparse.ArgumentParser, *, prog: str) -> int:
     """Render a forwarded command through the public CLI help contract.
 
-    Report, mirror-GC, and attribution modules keep standalone parsers because
-    their execution seams have different dependency constraints. The installed
-    command still owns their public path and presentation.
+    Report, mirror-GC, attribution, and transcript modules keep standalone
+    parsers because their execution seams have different dependency
+    constraints. The installed command still owns their public path and
+    presentation.
     """
     parser.prog = prog
     parser.formatter_class = _CoderFormatter
@@ -1815,8 +1816,8 @@ def build_parser() -> argparse.ArgumentParser:
     p_qc.add_argument("--reason", required=True)
     p_qc.set_defaults(func=cmd_quarantine_inference_calls)
 
-    # Stubs for --help only — the attribution dispatch in main() runs first
-    # (the report/mirror-gc pattern).
+    # Stubs for --help only — the attribution and transcript dispatch in
+    # main() runs first (the report/mirror-gc pattern).
     sub.add_parser(
         "install",
         help="wire a repo + this machine: git hooks, agent hooks, telemetry "
@@ -1826,6 +1827,15 @@ def build_parser() -> argparse.ArgumentParser:
         "uninstall", help="remove the per-repo git hooks (--agents: user-level too)"
     )
     sub.add_parser("doctor", help="check attribution + server health on this machine")
+    # The docs tell people to run these three by hand; hooks also run `stamp`
+    # and `transcript`.
+    sub.add_parser(
+        "repair-notes", help="reconcile a behind or diverged notes ref and push it"
+    )
+    sub.add_parser("stamp", help="write pending Session markers to the note on HEAD")
+    sub.add_parser(
+        "transcript", help="send one Session's Edit observations from its transcript"
+    )
 
     p_server = sub.add_parser(
         "server", help="run a local API server with managed PostgreSQL"
@@ -2030,9 +2040,10 @@ def build_parser() -> argparse.ArgumentParser:
 # store and never construct Settings.
 _REMOTE_VERBS = {"login", "logout", "commit", "facts", "demo", "evidence"}
 
-# Dispatched pre-argparse to the stdlib-only attribution module.
-# install/uninstall/doctor get help stubs; the hook-plumbing verbs are
-# execution-only (hidden from --help).
+# Dispatched pre-argparse to the stdlib-only attribution module. The verbs
+# that people run by hand (install, uninstall, doctor, stamp, repair-notes)
+# get help stubs; the hook-only verbs (cursor-hook, mark, union-squash-notes,
+# push-notes) are execution-only and stay out of --help.
 _ATTRIBUTION_VERBS = {
     "cursor-hook",
     "install",
@@ -2082,17 +2093,27 @@ def main(argv: list[str] | None = None) -> int:
             return _fail(str(exc))
     if argv[:1] == ["transcript"]:
         module = importlib.import_module("sediment_cli.transcript")
+        # The hook entry point hand-parses argv and always exits 0, so help
+        # returns here, before it reads capture configuration or stdin. No
+        # hook passes a help flag.
+        if {"-h", "--help"} & set(argv[1:]):
+            return _print_dispatched_help(
+                module.build_parser(), prog="sediment transcript"
+            )
         return _public_status(module.main(argv[1:]))
     if argv[:1] and argv[0] in _ATTRIBUTION_VERBS:
         # Forwarded verbatim to the attribution module's own parser —
-        # stdlib-only, never constructs Settings. The plumbing verbs (mark,
-        # stamp, union-squash-notes, push-notes, repair-notes) get no help
+        # stdlib-only, never constructs Settings. The hook-only verbs
+        # (cursor-hook, mark, union-squash-notes, push-notes) get no help
         # stub: hooks invoke them, humans don't.
         module = importlib.import_module("sediment_cli.attribution")
-        if argv[0] in {"install", "uninstall", "doctor"} and argv[1:] in (
-            ["-h"],
-            ["--help"],
-        ):
+        if argv[0] in {
+            "install",
+            "uninstall",
+            "doctor",
+            "stamp",
+            "repair-notes",
+        } and argv[1:] in (["-h"], ["--help"]):
             action = _subparsers_action(module.build_parser())
             return _print_dispatched_help(
                 action.choices[argv[0]], prog=f"sediment {argv[0]}"

{sediment_cli-0.5.0 → sediment_cli-0.6.1}/sediment_cli/transcript.py

@@ -1687,6 +1687,43 @@ def _publish(url: str, payload: dict) -> bool:
     return complete
 
 
+def build_parser():
+    """The command's shape, for ``sediment transcript --help`` and the CLI
+    reference only."""
+    # ponytail: a help-only twin of the hand parsing in main, which must exit
+    # 0 where argparse exits 2. Two arguments described twice; drive both from
+    # one table if the grammar grows.
+    import argparse  # the hook path never imports it
+
+    parser = argparse.ArgumentParser(
+        prog="sediment transcript",
+        # argparse prints options before positionals; main reads `snapshot`
+        # only as the first argument.
+        usage="%(prog)s [-h] [snapshot] --agent {" + ",".join(_PARSERS) + "}",
+        description="Read one hook event on stdin: a JSON object with "
+        "session_id and transcript_path. Extract the Session's Edit "
+        "observations from that agent transcript, and send them to "
+        "SEDIMENT_OTLP_ENDPOINT. For Claude Code, also send Rejected edits and "
+        "Retry linkages. Agent session-end hooks run this command. Run it "
+        "yourself to recover a Session that ended without its extractor. The "
+        "command always exits 0 and reports problems on stderr. If "
+        "SEDIMENT_OTLP_ENDPOINT is unset, it does nothing.",
+    )
+    parser.add_argument(
+        "snapshot",
+        nargs="?",
+        help="run as the PreToolUse hook instead: record line hashes around "
+        "one edit call in a local cache; must come before --agent",
+    )
+    parser.add_argument(
+        "--agent",
+        required=True,
+        choices=tuple(_PARSERS),
+        help="agent harness that wrote the transcript",
+    )
+    return parser
+
+
 def main(argv: list[str] | None = None) -> int:
     """The hook entry point — SessionEnd, or ``snapshot`` for PreToolUse.
 

{sediment_cli-0.5.0 → sediment_cli-0.6.1}/tests/test_cli_help.py

@@ -24,13 +24,26 @@ import pytest
 from sediment_cli.cli import _REPORTS, build_parser, main
 
 GOLDEN_DIR = Path(__file__).parent / "testdata" / "help"
-_DISPATCH_ONLY = {"report", "mirror-gc", "install", "uninstall", "doctor", "delivery"}
+_DISPATCH_ONLY = {
+    "report",
+    "mirror-gc",
+    "install",
+    "uninstall",
+    "doctor",
+    "stamp",
+    "repair-notes",
+    "transcript",
+    "delivery",
+}
 _DISPATCH_PATHS = [
     ("report",),
     ("mirror-gc",),
     ("install",),
     ("uninstall",),
     ("doctor",),
+    ("stamp",),
+    ("repair-notes",),
+    ("transcript",),
     ("delivery",),
     *(("delivery", name) for name in ("enqueue", "status", "replay")),
     *(("report", name) for name in _REPORTS),
@@ -137,6 +150,42 @@ def test_dispatched_runtime_help_uses_public_command_path(path) -> None:
     assert f"sediment {' '.join(path)}" in captured.stdout.splitlines()[1]
 
 
+def test_hook_only_verbs_stay_out_of_help() -> None:
+    # Hooks invoke these; listing them invites hand-running them. The docs
+    # tell people to run the other three, so those are listed.
+    commands = set(_subparsers_action(build_parser()).choices)
+
+    assert not commands & {"mark", "cursor-hook", "union-squash-notes", "push-notes"}
+    assert {"stamp", "repair-notes", "transcript"} <= commands
+
+
+@pytest.mark.parametrize(
+    "argv", (["--help"], ["-h"], ["snapshot", "--agent", "pi", "--help"])
+)
+def test_transcript_help_returns_before_the_hook_reads_anything(
+    argv, monkeypatch, capsys
+) -> None:
+    from sediment_cli import transcript
+
+    touched: list[str] = []
+
+    class _Stdin:
+        def read(self):
+            touched.append("stdin")
+            return "{}"
+
+    # A configured endpoint, so a regression into the hook path would go on
+    # to read stdin; the hook's own fail-soft would hide a raised error.
+    monkeypatch.setattr(
+        transcript, "_endpoint", lambda: touched.append("config") or "http://127.0.0.1"
+    )
+    monkeypatch.setattr(sys, "stdin", _Stdin())
+
+    assert main(["transcript", *argv]) == 0
+    assert touched == []
+    assert capsys.readouterr().out.startswith("USAGE:\n  sediment transcript ")
+
+
 def test_report_registry_uses_attribution_vocabulary() -> None:
     captured = _installed_help(("report",))
 

sediment_cli-0.6.1/tests/testdata/help/repair-notes.txt

@@ -0,0 +1,14 @@
+USAGE:
+  sediment repair-notes [-h] [remote]
+
+  Fetch refs/notes/sediment from the remote, union-merge it into the local
+  notes ref, and push the result. Run it inside a repository when `sediment
+  doctor --fetch` reports a notes ref that is behind or diverged. Unlike the
+  pre-push hook, the command exits 1 when it can't reconcile or push.
+
+ARGUMENTS:
+  remote      remote to fetch from and push to; use origin, the remote that
+              doctor checks (default: origin)
+
+OPTIONS:
+  -h, --help  show this help message and exit

{sediment_cli-0.5.0 → sediment_cli-0.6.1}/tests/testdata/help/sediment.txt

@@ -1,4 +1,4 @@
-sediment v0.5.0 — Turn AI developer workflow traces into RL-ready training data.
+sediment v0.6.1 — A self-hosted evidence store for coding agents.
 
 USAGE:
   sediment <command> [options]
@@ -27,6 +27,9 @@ COMMANDS:
                         telemetry env (sediment install --help)
   uninstall             remove the per-repo git hooks (--agents: user-level too)
   doctor                check attribution + server health on this machine
+  repair-notes          reconcile a behind or diverged notes ref and push it
+  stamp                 write pending Session markers to the note on HEAD
+  transcript            send one Session's Edit observations from its transcript
   server                run a local API server with managed PostgreSQL
   login                 store credentials for a server
   logout                remove stored credentials

sediment_cli-0.6.1/tests/testdata/help/stamp.txt

@@ -0,0 +1,12 @@
+USAGE:
+  sediment stamp [-h]
+
+  Write this repository's pending Session markers to the note on HEAD under
+  refs/notes/sediment, then clear the markers that it wrote. The post-commit
+  hook runs this command after each commit. Run it yourself only to recover a
+  pending stamp, while HEAD is still the commit that the markers belong to.
+  The command always exits 0, prints each failure on stderr, and logs it to
+  ~/.sediment/attribution.log.
+
+OPTIONS:
+  -h, --help  show this help message and exit

sediment_cli-0.6.1/tests/testdata/help/transcript.txt

@@ -0,0 +1,20 @@
+USAGE:
+  sediment transcript [-h] [snapshot] --agent {claude-code,codex,pi}
+
+  Read one hook event on stdin: a JSON object with session_id and
+  transcript_path. Extract the Session's Edit observations from that agent
+  transcript, and send them to SEDIMENT_OTLP_ENDPOINT. For Claude Code, also
+  send Rejected edits and Retry linkages. Agent session-end hooks run this
+  command. Run it yourself to recover a Session that ended without its
+  extractor. The command always exits 0 and reports problems on stderr. If
+  SEDIMENT_OTLP_ENDPOINT is unset, it does nothing.
+
+ARGUMENTS:
+  snapshot              run as the PreToolUse hook instead: record line hashes
+                        around one edit call in a local cache; must come before
+                        --agent
+
+OPTIONS:
+  -h, --help            show this help message and exit
+  --agent {claude-code,codex,pi}
+                        agent harness that wrote the transcript

{sediment_cli-0.5.0 → sediment_cli-0.6.1}/tests/testdata/help/uninstall.txt

@@ -2,7 +2,8 @@ USAGE:
   sediment uninstall [-h] [--agents] [repo]
 
 ARGUMENTS:
-  repo
+  repo        repository to remove the git hooks from (default: current
+              directory)
 
 OPTIONS:
   -h, --help  show this help message and exit

sediment_cli-0.5.0/PKG-INFO

@@ -1,16 +0,0 @@
-Metadata-Version: 2.5
-Name: sediment-cli
-Version: 0.5.0
-Summary: The sediment command: login, install, server, facts, exports
-Project-URL: Source, https://github.com/sediment-ai/sediment
-Project-URL: Documentation, https://github.com/sediment-ai/sediment/tree/main/docs
-Project-URL: Issues, https://github.com/sediment-ai/sediment/issues
-Project-URL: Changelog, https://github.com/sediment-ai/sediment/blob/main/CHANGELOG.md
-License-Expression: AGPL-3.0-or-later
-License-File: LICENSE
-Requires-Python: >=3.12
-Requires-Dist: httpx>=0.27
-Requires-Dist: sediment-api==0.5.0
-Requires-Dist: sediment-core==0.5.0
-Requires-Dist: sediment-derive==0.5.0
-Requires-Dist: sediment-export==0.5.0