agent-memory-cli 0.1.0__tar.gz → 0.1.2__tar.gz

{agent_memory_cli-0.1.0 → agent_memory_cli-0.1.2}/CHANGELOG.md

@@ -4,6 +4,32 @@ All notable changes to agent-memory are documented in this file. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the
 project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.1.2 - 2026-09-17
+
+### Added
+
+- `status --json` prints the readout as one object, with an `ok` flag and a `prerequisites` block ([status](docs/commands.md#status)).
+
+### Fixed
+
+- `status` and `doctor` exit non-zero with a reason code when a prerequisite such as git fails ([prerequisites](docs/commands.md#prerequisites)).
+- `doctor` and `status --fetch` name a sandbox-blocked credential helper, not an unreachable remote ([doctor](docs/commands.md#doctor)).
+
+## 0.1.1 - 2026-09-12
+
+### Added
+
+- `event write` publishes one org-memory event under `org-memory/events/`, never replacing a published record ([event](docs/commands.md#event-write)).
+- A `v*` tag attaches the built sdist and wheel to the GitHub Release ([releases](https://github.com/kiloloop/agent-memory/releases)).
+
+### Fixed
+
+- A nested `.gitignore` or `.oacp-memory-repo` no longer blocks `pull`; the allowlist anchors both names to the home root ([sync](docs/commands.md#sync)).
+- `enable` retires superseded lines when it updates a home's `.gitignore`, and the receipt names them ([sync](docs/commands.md#sync)).
+- `doctor` scopes its working-tree row to the allowlist: memory changes read DIRTY, and changes elsewhere are named as outside it ([doctor](docs/commands.md#doctor)).
+- `push` and `doctor` keep both paths of a rename git detects in the working tree; the source path was previously misread ([sync](docs/commands.md#sync)).
+- `push` names a credential helper a sandbox blocked as its own failure, with the remedy, instead of reporting it as a rejected push ([sync](docs/commands.md#sync)).
+
 ## 0.1.0 - 2026-09-06
 
 ### Added

{agent_memory_cli-0.1.0 → agent_memory_cli-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agent-memory-cli
-Version: 0.1.0
+Version: 0.1.2
 Summary: Cross-session memory for coding agents: plain files, git-native, no server
 Project-URL: Homepage, https://github.com/kiloloop/agent-memory
 Project-URL: Source, https://github.com/kiloloop/agent-memory
@@ -24,7 +24,7 @@ Requires-Python: >=3.10
 Provides-Extra: dev
 Requires-Dist: build<2,>=1.2; extra == 'dev'
 Requires-Dist: pytest<10,>=8; extra == 'dev'
-Requires-Dist: ruff<1,>=0.11; extra == 'dev'
+Requires-Dist: ruff<0.17,>=0.16; extra == 'dev'
 Requires-Dist: twine<8,>=7; extra == 'dev'
 Description-Content-Type: text/markdown
 
@@ -177,6 +177,7 @@ similarity queries, synthesis, or indexing. Recall reads a fixed file set.
 | [`capture`][capture-and-recall] | Record a decision. |
 | [`recall`][capture-and-recall] | Read bounded context. |
 | [`debrief write`][debrief-write] | Publish a session summary. |
+| [`event write`][event-write] | Publish an org-memory event. |
 
 [status]: https://github.com/kiloloop/agent-memory/blob/main/docs/commands.md#status
 [doctor]: https://github.com/kiloloop/agent-memory/blob/main/docs/commands.md#doctor
@@ -187,6 +188,7 @@ similarity queries, synthesis, or indexing. Recall reads a fixed file set.
 [startup]: https://github.com/kiloloop/agent-memory/blob/main/docs/commands.md#startup
 [capture-and-recall]: https://github.com/kiloloop/agent-memory/blob/main/docs/commands.md#capture-and-recall
 [debrief-write]: https://github.com/kiloloop/agent-memory/blob/main/docs/commands.md#debrief-write
+[event-write]: https://github.com/kiloloop/agent-memory/blob/main/docs/commands.md#event-write
 
 ## Examples
 

{agent_memory_cli-0.1.0 → agent_memory_cli-0.1.2}/README.md

@@ -147,6 +147,7 @@ similarity queries, synthesis, or indexing. Recall reads a fixed file set.
 | [`capture`][capture-and-recall] | Record a decision. |
 | [`recall`][capture-and-recall] | Read bounded context. |
 | [`debrief write`][debrief-write] | Publish a session summary. |
+| [`event write`][event-write] | Publish an org-memory event. |
 
 [status]: https://github.com/kiloloop/agent-memory/blob/main/docs/commands.md#status
 [doctor]: https://github.com/kiloloop/agent-memory/blob/main/docs/commands.md#doctor
@@ -157,6 +158,7 @@ similarity queries, synthesis, or indexing. Recall reads a fixed file set.
 [startup]: https://github.com/kiloloop/agent-memory/blob/main/docs/commands.md#startup
 [capture-and-recall]: https://github.com/kiloloop/agent-memory/blob/main/docs/commands.md#capture-and-recall
 [debrief-write]: https://github.com/kiloloop/agent-memory/blob/main/docs/commands.md#debrief-write
+[event-write]: https://github.com/kiloloop/agent-memory/blob/main/docs/commands.md#event-write
 
 ## Examples
 

{agent_memory_cli-0.1.0 → agent_memory_cli-0.1.2}/pyproject.toml

@@ -1,5 +1,5 @@
 [build-system]
-requires = ["hatchling>=1.27"]
+requires = ["hatchling>=1.32,<2"]
 build-backend = "hatchling.build"
 
 [project]
@@ -38,7 +38,7 @@ Changelog = "https://github.com/kiloloop/agent-memory/blob/main/CHANGELOG.md"
 dev = [
   "build>=1.2,<2",
   "pytest>=8,<10",
-  "ruff>=0.11,<1",
+  "ruff>=0.16,<0.17",
   "twine>=7,<8",
 ]
 

agent_memory_cli-0.1.2/scripts/release_notes.py

@@ -0,0 +1,78 @@
+#!/usr/bin/env python3
+# SPDX-FileCopyrightText: 2026 Kiloloop
+# SPDX-License-Identifier: Apache-2.0
+"""Print the changelog section for one release, as GitHub Release notes.
+
+The release workflow feeds this to ``gh release create --notes-file``. GitHub's own
+``--generate-notes`` cannot serve here: the public repository receives each version as a
+single squashed commit, so the generated summary is one line no matter how much the
+release contains. The changelog section already says what shipped, one line per change.
+
+Two transformations make a changelog section stand alone on a release page:
+
+1. Relative links (``docs/commands.md#init``) are rewritten against the tag. A release
+   body is not rendered relative to the repository root, so a relative target 404s; and
+   pinning to the tag rather than to ``main`` keeps old release notes pointing at the
+   documentation as it stood for that version.
+2. The section heading itself is dropped — the release already carries the version.
+
+Exits 1 when the section is absent, so the caller can fall back rather than publish a
+release with an empty body.
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+LINK = re.compile(r"\]\(([^)]+)\)")
+
+
+def extract(changelog: str, version: str) -> str | None:
+    """Return the body of ``## <version>``, or None when no such section exists."""
+    lines = changelog.split("\n")
+    start = None
+    for i, line in enumerate(lines):
+        # "## 0.1.0 - 2026-09-06" and "## [0.1.0] - ..." both name this version.
+        if line.startswith("## ") and re.match(rf"##\s+\[?{re.escape(version)}\]?\b", line):
+            start = i + 1
+            break
+    if start is None:
+        return None
+    body: list[str] = []
+    for line in lines[start:]:
+        if line.startswith("## "):
+            break
+        body.append(line)
+    return "\n".join(body).strip() or None
+
+
+def absolutise(notes: str, repository: str, tag: str) -> str:
+    """Rewrite repo-relative link targets to absolute URLs pinned at ``tag``."""
+    base = f"https://github.com/{repository}/blob/{tag}/"
+    return LINK.sub(
+        lambda m: f"]({m.group(1)})" if m.group(1).startswith("http") else f"]({base}{m.group(1)})",
+        notes,
+    )
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--tag", required=True, help="release tag, e.g. v0.1.0")
+    parser.add_argument("--repository", required=True, help="owner/repo, for absolute links")
+    parser.add_argument("--changelog", default="CHANGELOG.md", type=Path)
+    args = parser.parse_args()
+
+    version = args.tag[1:] if args.tag.startswith("v") else args.tag
+    notes = extract(args.changelog.read_text(encoding="utf-8"), version)
+    if notes is None:
+        print(f"no changelog section for {version} in {args.changelog}", file=sys.stderr)
+        return 1
+    print(absolutise(notes, args.repository, args.tag))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

{agent_memory_cli-0.1.0 → agent_memory_cli-0.1.2}/src/agent_memory/__init__.py

@@ -4,6 +4,6 @@
 
 from .home import HomeError, HomeResolution, resolve_home
 
-__version__ = "0.1.0"
+__version__ = "0.1.2"
 
 __all__ = ["HomeError", "HomeResolution", "__version__", "resolve_home"]

{agent_memory_cli-0.1.0 → agent_memory_cli-0.1.2}/src/agent_memory/cli.py

@@ -10,7 +10,7 @@ import sys
 from pathlib import Path
 from typing import Callable, List, Optional, Sequence, Tuple
 
-from . import __version__, archive, debrief, doctor, org, setup, startup, status, sync, workflow
+from . import __version__, archive, debrief, doctor, events, org, prerequisites, setup, startup, status, sync, workflow
 from .home import BINDING_FILE, HomeError, HomeResolution, find_project, resolve_home
 
 EXIT_OK = 0
@@ -51,16 +51,17 @@ def build_parser() -> argparse.ArgumentParser:
         "status",
         _status,
         "Show which home resolves, which rule chose it, whether the layout is in place, and where the sync stands. "
-        "Exit 1 when the tree is dirty or diverged.",
+        "Exit 1 when the tree is dirty or diverged, or a prerequisite (git, the home, the credential helper) failed.",
     )
     status_.add_argument(
         "--fetch", action="store_true", help="contact the remote before counting ahead/behind (no network otherwise)"
     )
+    status_.add_argument("--json", dest="json_output", action="store_true", help="emit the readout as JSON")
     doctor_ = add(
         "doctor",
         _doctor,
         "Check the home's setup and health: the debrief store's layout and the sync repository. "
-        "Reads no memory content; repairs nothing. Exit 1 on an error row.",
+        "Reads no memory content; repairs nothing. Exit 1 on an error row or a failed prerequisite.",
     )
     doctor_.add_argument("--json", dest="json_output", action="store_true", help="emit the report as JSON")
     init_ = add(
@@ -189,6 +190,38 @@ def build_parser() -> argparse.ArgumentParser:
     write.add_argument("--oacp-dir", dest="home", metavar="PATH", help=argparse.SUPPRESS)
     write.add_argument("--dry-run", action="store_true", help="validate and compose the record, print it, and write nothing")
     write.add_argument("--json", dest="json_output", action="store_true", help="emit a machine-readable result")
+    event_ = commands.add_parser("event", help="Org-memory event commands.", description="Org-memory event commands.")
+    event_commands = event_.add_subparsers(dest="event_command", metavar="<command>")
+    event_help = (
+        "Publish one org-memory event into the home's events store, failure-atomically: the canonical path only ever "
+        "holds a complete, verified record, byte-identical to the kernel's write-event script for the same inputs. "
+        "Exit 0 published (or an identical record was already there), 1 on a validation error, 2 on a publication "
+        "failure."
+    )
+    event_write = event_commands.add_parser("write", parents=[common], help=event_help, description=event_help)
+    event_write.set_defaults(handler=_event_write)
+    event_write.add_argument("--agent", required=True, help="agent creating the event")
+    event_write.add_argument("--project", required=True, help="originating project")
+    event_write.add_argument(
+        "--type", dest="event_type", required=True, choices=sorted(events.ALLOWED_TYPES), help="event type"
+    )
+    event_write.add_argument(
+        "--slug", required=True, help="short slug for the filename: lowercase alphanumerics and hyphens, no dots"
+    )
+    event_body = event_write.add_mutually_exclusive_group()
+    event_body.add_argument("--body", help="event body, inline")
+    event_body.add_argument("--body-file", help="path to the event body in Markdown, or '-' to read stdin")
+    event_write.add_argument("--source-ref", help="provenance id, e.g. the debrief stem the event was folded from")
+    event_write.add_argument(
+        "--related", help="cross-references: comma-separated or a JSON array (e.g. 'PR #43,issue #10')"
+    )
+    event_write.add_argument("--supersedes", help="path of the event this entry overrides")
+    # The kernel script's home flag; accepted, unadvertised, through v0.1.x.
+    event_write.add_argument("--oacp-dir", dest="home", metavar="PATH", help=argparse.SUPPRESS)
+    event_write.add_argument(
+        "--dry-run", action="store_true", help="validate and compose the record, print it, and write nothing"
+    )
+    event_write.add_argument("--json", dest="json_output", action="store_true", help="emit a machine-readable result")
     return parser
 
 
@@ -203,23 +236,44 @@ def _max_chars(value: str) -> int:
 
 
 def _status(args: argparse.Namespace) -> int:
-    readout = status.inspect(resolve_home(args.home), fetch=args.fetch)
-    print("\n".join(readout.lines()))
+    try:
+        resolution = resolve_home(args.home)
+    except HomeError as exc:
+        if not args.json_output:
+            raise
+        print(json.dumps(status.unresolved(exc), indent=2))
+        return EXIT_USAGE
+    readout = status.inspect(resolution, fetch=args.fetch)
+    if args.json_output:
+        print(json.dumps(readout.to_json(), indent=2))
+    else:
+        print("\n".join(readout.lines()))
     return readout.exit_code
 
 
 def _doctor(args: argparse.Namespace) -> int:
-    home = resolve_home(args.home).path
+    memory_lint = doctor.find_memory_lint()
+    try:
+        home = resolve_home(args.home).path
+    except HomeError as exc:
+        if not args.json_output:
+            raise
+        unresolved = prerequisites.home_error(exc)
+        print(json.dumps(doctor.to_json([], memory_lint=memory_lint, prerequisites=unresolved), indent=2))
+        return EXIT_USAGE
     if not home.is_dir():
-        print(f"agent-memory: error: {home} is not a directory", file=sys.stderr)
+        missing = prerequisites.home_missing(home)
+        if args.json_output:
+            print(json.dumps(doctor.to_json([], memory_lint=memory_lint, prerequisites=missing), indent=2))
+        elif missing.failure:
+            print(f"agent-memory: error: {missing.failure.line()}", file=sys.stderr)
         return EXIT_FAILED
-    categories = doctor.run_doctor(home)
-    memory_lint = doctor.find_memory_lint()
+    categories, readout = doctor.diagnose(home)
     if args.json_output:
-        print(json.dumps(doctor.to_json(categories, memory_lint=memory_lint), indent=2))
+        print(json.dumps(doctor.to_json(categories, memory_lint=memory_lint, prerequisites=readout), indent=2))
     else:
         sys.stdout.write(doctor.report(categories, memory_lint=memory_lint))
-    return EXIT_FAILED if doctor.has_errors(categories) else EXIT_OK
+    return EXIT_FAILED if doctor.has_errors(categories) or not readout.ok else EXIT_OK
 
 
 def _init(args: argparse.Namespace) -> int:
@@ -414,6 +468,85 @@ def _debrief_write(args: argparse.Namespace) -> int:
     return EXIT_OK
 
 
+def _event_write(args: argparse.Namespace) -> int:
+    home = resolve_home(args.home).path
+    try:
+        body = _event_body(args)
+    except OSError as exc:
+        print(f"ERROR: cannot read body: {exc}", file=sys.stderr)
+        return EXIT_FAILED
+    except events.WriterError as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
+        return exc.code
+
+    try:
+        result = events.write_event(
+            home=home,
+            agent=args.agent,
+            project=args.project,
+            event_type=args.event_type,
+            slug=args.slug,
+            body=body,
+            source_ref=args.source_ref,
+            related=events.normalize_related(args.related) if args.related else None,
+            supersedes=args.supersedes,
+            dry_run=args.dry_run,
+        )
+    except events.WriterError as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
+        return exc.code
+    except OSError as exc:
+        print(f"ERROR: publication failed: {exc}", file=sys.stderr)
+        return 2
+
+    if args.json_output:
+        print(
+            json.dumps(
+                {
+                    "path": str(result.path),
+                    "status": result.status,
+                    "created_at_utc": result.created_at_utc,
+                    "date": result.created_at_utc[:10],
+                    "agent": args.agent,
+                    "project": args.project,
+                    "type": args.event_type,
+                },
+                indent=2,
+            )
+        )
+    else:
+        print(f"{result.status}: {result.path}")
+        print(f"created_at_utc: {result.created_at_utc}")
+
+    if args.dry_run:
+        print("--- record preview (nothing was written) ---", file=sys.stderr)
+        sys.stderr.flush()
+        sys.stderr.buffer.write(result.record)
+        sys.stderr.buffer.flush()
+    return EXIT_OK
+
+
+def _event_body(args: argparse.Namespace) -> bytes:
+    """The body bytes: ``--body-file`` (a path, or ``-`` for stdin), ``--body``, else piped stdin.
+
+    Trailing newlines are dropped, as the kernel script drops them; the record
+    closes the body with exactly one. A body file is read as text, so its
+    CRLF and CR line endings become LF (:func:`events.body_from_file`); stdin
+    and the inline body are taken as given, both as the script does.
+    """
+    if args.body_file is not None and args.body_file != "-":
+        return events.body_from_file(Path(args.body_file).expanduser().read_bytes())
+    if args.body_file is not None:
+        raw = sys.stdin.buffer.read()
+    elif args.body is not None:
+        raw = args.body.encode("utf-8")
+    elif not sys.stdin.isatty():
+        raw = sys.stdin.buffer.read()
+    else:
+        raise events.WriterError("no body provided: use --body, --body-file <path|->, or pipe the body to stdin", 1)
+    return raw.rstrip(b"\n")
+
+
 def _report(outcome: sync.Outcome) -> int:
     if outcome.lines:
         print("\n".join(outcome.lines), file=sys.stdout if outcome.ok else sys.stderr)

{agent_memory_cli-0.1.0 → agent_memory_cli-0.1.2}/src/agent_memory/doctor.py

@@ -36,8 +36,9 @@ from enum import Enum
 from pathlib import Path
 from typing import Any, Callable, Dict, List, Optional, Sequence, Tuple
 
-from . import layout, sync
+from . import layout, prerequisites, sync
 from .git_runner import GitResult, GitRunner, run_git
+from .prerequisites import Prerequisites
 from .sync import GitState
 
 #: A last commit older than this many days is reported stale.
@@ -109,7 +110,15 @@ def run_doctor(
     home: Path, *, runner: Optional[GitRunner] = None, now: Optional[dt.datetime] = None
 ) -> List[Category]:
     """Both memory categories for ``home``, in report order."""
-    return [check_org_memory(home), check_memory_sync(home, runner=runner, now=now)]
+    return diagnose(home, runner=runner, now=now)[0]
+
+
+def diagnose(
+    home: Path, *, runner: Optional[GitRunner] = None, now: Optional[dt.datetime] = None
+) -> Tuple[List[Category], Prerequisites]:
+    """Both memory categories in report order, and the prerequisite readout the sync checks took."""
+    memory_sync, readout = _memory_sync(home, runner=runner, now=now)
+    return [check_org_memory(home), memory_sync], readout
 
 
 def find_memory_lint(which: Callable[[str], Optional[str]] = shutil.which) -> Optional[str]:
@@ -135,10 +144,16 @@ def report(categories: Sequence[Category], *, memory_lint: Optional[str] = None)
     return "\n".join(lines) + "\n"
 
 
-def to_json(categories: Sequence[Category], *, memory_lint: Optional[str] = None) -> Dict[str, Any]:
-    """The report as data, in the same order as the text."""
+def to_json(
+    categories: Sequence[Category],
+    *,
+    memory_lint: Optional[str] = None,
+    prerequisites: Optional[Prerequisites] = None,
+) -> Dict[str, Any]:
+    """The report as data, in the same order as the text; ``prerequisites`` goes last, so the
+    rows before it read as they did without it."""
     output: Dict[str, Any] = {
-        "has_errors": has_errors(categories),
+        "has_errors": has_errors(categories) or (prerequisites is not None and not prerequisites.ok),
         "memory_lint": memory_lint,
         "categories": [],
     }
@@ -152,6 +167,8 @@ def to_json(categories: Sequence[Category], *, memory_lint: Optional[str] = None
         output["categories"].append(
             {"name": category.name, "worst_severity": category.worst_severity.value, "results": rows}
         )
+    if prerequisites is not None:
+        output["prerequisites"] = prerequisites.to_json()
     return output
 
 
@@ -325,14 +342,21 @@ def check_memory_sync(
     home: Path, *, runner: Optional[GitRunner] = None, now: Optional[dt.datetime] = None
 ) -> Category:
     """The sync setup and the repository's state, through git alone; nothing is changed."""
+    return _memory_sync(home, runner=runner, now=now)[0]
+
+
+def _memory_sync(
+    home: Path, *, runner: Optional[GitRunner], now: Optional[dt.datetime]
+) -> Tuple[Category, Prerequisites]:
     cat = Category("Memory Sync")
     marker = layout.MARKER_FILE
+    git = prerequisites.probe_git(runner)
 
     try:
         configured = _is_file(sync.marker_path(home))
     except OSError as exc:
         cat.add("memory-marker", Severity.warn, f"{marker} — {_not_inspected(exc)}")
-        return cat
+        return cat, prerequisites.assess(git, configured=False)
     if not configured:
         cat.add(
             "memory-marker",
@@ -340,9 +364,18 @@ def check_memory_sync(
             f"{marker} — not configured; memory sync hooks are disabled",
             "Run: agent-memory enable [--remote URL]",
         )
-        return cat
+        return cat, prerequisites.assess(git, configured=False)
     cat.add("memory-marker", Severity.ok, f"{marker} — present")
 
+    if not git.present:
+        # Without git every readout below fails, and "not a git repository" would be the wrong finding.
+        cat.add(
+            "memory-git",
+            Severity.error,
+            f"{marker} — present, but {prerequisites.GIT_MISSING_TEXT}",
+            prerequisites.GIT_MISSING_REMEDY,
+        )
+        return cat, prerequisites.assess(git, configured=True)
     if not sync.is_git_repo(home, runner):
         cat.add(
             "memory-git",
@@ -350,7 +383,7 @@ def check_memory_sync(
             f"{marker} — present, but {home} is not a git repository",
             "Run `agent-memory enable`, or `agent-memory disable` to remove the marker",
         )
-        return cat
+        return cat, prerequisites.assess(git, configured=True)
     enclosing = enclosing_repository(home, runner)
     if enclosing is not None:
         # The sync verbs refuse this home; reading the enclosing repository's state as the home's would be wrong.
@@ -361,7 +394,7 @@ def check_memory_sync(
             "a memory home must be the root of its own repository",
             "Move the home out of the enclosing repository, or `agent-memory disable` to remove the marker",
         )
-        return cat
+        return cat, prerequisites.assess(git, configured=True)
 
     root_gitignore = home / layout.GITIGNORE_FILE
     try:
@@ -444,20 +477,16 @@ def check_memory_sync(
         state = None
 
     if state is not None:
-        if state.dirty:
-            cat.add(
-                "working-tree",
-                Severity.warn,
-                "working tree — DIRTY memory changes present",
-                "Run `agent-memory push` or resolve changes manually",
-            )
-        else:
-            cat.add("working-tree", Severity.ok, "working tree — clean")
+        _add_working_tree(cat, home, runner, state)
 
         text = f"sync state — {sync_state_text(state)}"
         if not state.has_remote:
             cat.add("sync-state", Severity.ok, text)
             cat.add("remote", Severity.skip, "remote — skipped; local-only memory repo")
+        elif prerequisites.helper_blocked(state):
+            # Not the network and not the remote's permissions: git never had credentials to try with.
+            cat.add("sync-state", Severity.error, text, prerequisites.HELPER_BLOCKED_REMEDY)
+            cat.add("remote", Severity.skip, "remote — not checked; the sandbox blocked the git credential helper")
         elif state.fetch_failed:
             cat.add("sync-state", Severity.warn, text, "Check network access and remote permissions")
             cat.add("remote", Severity.warn, "remote — not reachable", "Check network access and remote permissions")
@@ -531,7 +560,42 @@ def check_memory_sync(
     else:
         cat.add("memory-overlays", Severity.ok, f"memory .gitignore overlays — {len(overlays)} safe")
 
-    return cat
+    fetched = state is not None and state.has_remote
+    return cat, prerequisites.assess(git, configured=True, state=state, fetched=fetched)
+
+
+def _add_working_tree(cat: Category, home: Path, runner: Optional[GitRunner], state: GitState) -> None:
+    """The tree row, scoped like the counts above it.
+
+    Memory changes inside the allowlist are what ``push`` would publish and
+    read DIRTY. Changes anywhere else are named as outside the allowlist: not
+    memory content, but ``pull`` still refuses a tree that carries them.
+    """
+    if not state.dirty:
+        cat.add("working-tree", Severity.ok, "working tree — clean")
+        return
+    try:
+        changed = sync.changed_paths(home, runner)
+    except sync.SyncError as exc:
+        cat.add("working-tree", Severity.warn, f"working tree — DIRTY; the change readout failed: {exc}")
+        return
+    memory = [path for path in changed if layout.is_allowed_memory_path(path)]
+    elsewhere = [path for path in changed if not layout.is_allowed_memory_path(path)]
+    if memory:
+        text = f"working tree — DIRTY {len(memory)} memory change(s): {_summarize(memory)}"
+        if elsewhere:
+            text += f"; {len(elsewhere)} change(s) outside the memory allowlist"
+        cat.add("working-tree", Severity.warn, text, "Run `agent-memory push` or resolve changes manually")
+    elif elsewhere:
+        cat.add(
+            "working-tree",
+            Severity.warn,
+            f"working tree — {len(elsewhere)} change(s) outside the memory allowlist: {_summarize(elsewhere)}; "
+            "no memory change is pending, but memory pull refuses a dirty tree",
+            "Commit, stash or ignore them outside the memory tiers",
+        )
+    else:
+        cat.add("working-tree", Severity.ok, "working tree — clean")
 
 
 def enclosing_repository(home: Path, runner: Optional[GitRunner] = None) -> Optional[Path]:
@@ -542,10 +606,30 @@ def enclosing_repository(home: Path, runner: Optional[GitRunner] = None) -> Opti
     return root
 
 
+def sync_state(state: GitState) -> str:
+    """Where the repository stands, as the code ``status --json`` carries beside :func:`sync_state_text`."""
+    if not state.has_remote:
+        return "local_only"
+    if state.fetch_failed:
+        return "fetch_failed"
+    if not state.has_upstream:
+        return "no_upstream"
+    if state.diverged:
+        return "diverged"
+    if state.behind:
+        return "behind"
+    if state.ahead:
+        return "ahead"
+    return "synced"
+
+
 def sync_state_text(state: GitState) -> str:
     """One phrase for where the repository stands; ``status`` and ``doctor`` share it."""
     if not state.has_remote:
         return "local-only; no remote configured"
+    if prerequisites.helper_blocked(state):
+        # The helper's own output names the secret it was after; the phrase names the cause instead.
+        return f"remote fetch failed: {prerequisites.HELPER_BLOCKED_TEXT}"
     if state.fetch_failed:
         return f"remote fetch failed: {state.fetch_output}"
     if not state.has_upstream: