agentic-home-cli 0.1.0

package/README.md

@@ -0,0 +1,161 @@
+# agentic-home-cli
+
+One command to gather global agent skills and shared instructions into a managed home, then connect installed agents with symlinks.
+
+**Requirements:** macOS or Linux, Python 3.11+, and Git for three-way text merges. No runtime Python dependencies, embedded LLM, network requests, or background service.
+
+## Install and preview
+
+With npm (Node.js 18+):
+
+```sh
+npm install -g agentic-home-cli
+agentic sync --dry-run
+```
+
+Or run `npx agentic-home-cli sync --dry-run`. Python 3.11+ must already be installed; npm does not install Python or Git. The launcher searches common Python executable names. Set `AGENTIC_PYTHON=/absolute/path/to/python3.12` to select an interpreter explicitly. Git is needed for three-way merges.
+
+From this checkout with pipx:
+
+```sh
+pipx install .
+agentic sync --dry-run
+agentic sync
+```
+
+The distribution is `agentic-home-cli`; the command is `agentic`. Check `command -v agentic` if you already have a command with that name.
+
+Without installing:
+
+```sh
+python3.12 -m agentic_cli.cli sync --dry-run --json
+```
+
+Only existing agent setups are detected. Project files, credentials, sessions, caches, plugin installations, and unrelated settings are not managed. Skills can contain executable scripts and instructions: review their contents before sharing them with more agents. The CLI never executes skill content.
+
+## Choose a directory
+
+```sh
+agentic sync --root "$HOME/my shared agent files"
+agentic sync                     # remembers the selected directory
+agentic status
+```
+
+The default is `~/.agentic`. The saved selection lives in `$XDG_CONFIG_HOME/agentic/config.json`, or `~/.config/agentic/config.json` when XDG_CONFIG_HOME is unset. `--root` overrides that selection. Relative paths become absolute; spaces are supported. Dry runs do not save a selection or modify the home.
+
+A root can already contain `skills/<name>/SKILL.md` and `AGENTS.md`. Other files in that root are left alone, including an existing `index.json`.
+
+To switch roots later, run `sync --root NEW_PATH`. The previous root becomes another import source, not an automatically preferred version. Old content is retained. Conflicts are resolved normally. A pending-root pointer routes `status`, `resolve`, and `continue` to the new workspace; the saved active root switches only once the transition is complete. Finish pending work before selecting another root. Nested/overlapping roots and roots within agent/configuration directories are rejected.
+
+## Supported discovery locations
+
+| Agent detected | Skills destination | Shared instructions |
+| --- | --- | --- |
+| `~/.claude` | `~/.claude/skills/<name>` | `~/.claude/CLAUDE.md` |
+| `~/.codex` | `~/.agents/skills/<name>` | `~/.codex/AGENTS.md` |
+| `~/.cursor` | `~/.cursor/skills/<name>` | Unsupported global file integration; reported explicitly |
+| `~/.pi/agent` | `~/.pi/agent/skills/<name>` | `~/.pi/agent/AGENTS.md` |
+
+Existing legacy `~/.codex/skills` entries are imported and linked too. Existing shared `~/.agents/skills` entries are imported when Codex or Pi is detected. Hidden catalogs such as `.system` are left untouched. Custom agent-home environment variables/settings are not interpreted in this first version.
+
+Portable skills are directories containing a regular `SKILL.md` file (a directory with that name is invalid). Pi-only standalone Markdown skills are reported and left untouched, rather than made undiscoverable by other agents. Instructions have one shared body, without agent-specific additions.
+
+Cursor's documented global User Rules are configured in Settings, not discovered from a documented global file path. The CLI therefore does **not** create a misleading `~/.cursor/rules` wrapper or modify Cursor's database. A thin wrapper/reference is permitted if a supported global hook becomes available; it must reference the selected root rather than hardcode `~/.agentic`.
+
+`AGENTS.override.md` in Codex or Pi blocks instruction publication and is reported for explicit reconciliation. It does not stop unrelated skills. Additional custom instruction settings and project-local instructions remain outside this tool's scope.
+
+### Discovery evidence
+
+Checked against primary documentation during implementation:
+
+- [Claude Code skills](https://code.claude.com/docs/en/skills): personal `~/.claude/skills/<name>/SKILL.md`.
+- [Claude Code memory](https://code.claude.com/docs/en/memory): user `~/.claude/CLAUDE.md`. Cowork has additional symlink/import restrictions and is **not** a supported target.
+- [Codex skills](https://developers.openai.com/codex/skills/): user `~/.agents/skills`; symlinked skill folders explicitly supported.
+- [Codex instructions](https://developers.openai.com/codex/guides/agents-md/): global `~/.codex/AGENTS.md`, with `AGENTS.override.md` taking precedence.
+- [Cursor skills](https://cursor.com/docs/context/skills): global `~/.cursor/skills` and compatibility discovery locations.
+- [Cursor rules](https://cursor.com/docs/context/rules): `.cursor/rules` is project-scoped; global User Rules live in Settings.
+- [Pi README](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md#context-files) and [skills documentation](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/skills.md): global `~/.pi/agent/AGENTS.md`, skill catalogs, and override behavior. Also verified against the locally installed Pi documentation.
+
+These are documented discovery contracts, not a claim of live end-to-end validation in each agent application. Restart/reload your agents and inspect their loaded skills/instructions after setup.
+
+## Conflicts, like Git
+
+```sh
+agentic sync
+agentic status --json
+agentic resolve CONFLICT_ID --take claude
+agentic continue
+```
+
+There is **no source precedence**. Identical content deduplicates; unique files combine. First-import differences without a recorded common ancestor become conflicts. Subsequent text changes use `git merge-file` when a baseline exists. Multiple distinct variants, binary differences, and type collisions are never guessed away.
+
+Non-conflicting skills are organized immediately. An entire conflicting skill remains inactive in the new home until its files are resolved; the agents keep their original files. Shared instructions are a separate activation unit. Conflict-marked files live only in private working copies, never in active discovery locations.
+
+In a terminal, the CLI offers a source label, an edited file/directory, or deferral. For manual or LLM editing:
+
+```sh
+agentic sync --json
+# Inspect conflicts[].variants and conflicts[].working_copy.
+# Edit the working copy; for a skill, preserve the entire directory tree.
+agentic resolve CONFLICT_ID --file '/reported/working/copy'
+agentic continue --json
+```
+
+`resolve` stages a snapshot, so edit first and stage afterward. `continue` validates the resolved node type and rediscovers sources, including agents and legacy catalogs added since staging. New or changed sources invalidate the staged result and refresh the conflict workspace; previously unseen content is never silently selected against. An instruction override that appears meanwhile also blocks publication. Repeated `sync` calls retain unfinished working copies.
+
+Conflict markers beginning with `<<<<<<<`, `=======`, or `>>>>>>>` are rejected anywhere in staged text. Binary files require explicit source selection or replacement content. If documentation intentionally contains lines with these prefixes, rewrite/indent those lines before staging.
+
+**LLM contract:** use `--json` to avoid prompts; stable conflict IDs, labeled live source paths, snapshot locations, relative conflicting paths, and resolution commands are returned. No PTY is required. Exit codes: `0` success, `1` operational failure, `2` unresolved conflicts or blocked units. JSON goes to stdout; normal human diagnostics go to stderr. `--dry-run` uses the publication validation path and reports prospective conflicts, invalid units, and catalog normalization without creating workspaces.
+
+## Repeated runs and symlinks
+
+- New skills and regular files that replace managed links are imported through the same workflow.
+- Missing discovery links are repaired when the canonical content exists.
+- Absence is not a deletion instruction. Missing children retained in a baseline are restored; missing whole units with no live source are reported instead of silently recreated. Deletion propagation is intentionally unsupported.
+- Valid external source links are retained when the selected content matches. Their targets are not moved or modified. When a merge requires a local copy, content is materialized; nested source links are followed into that copy, not rewritten in the external source.
+- Whole-catalog links to the selected canonical catalog can remain as-is. Other whole-catalog links are backed up and replaced by a local catalog of child links before individual skills are adopted. External targets remain untouched.
+- Broken links, cycles, special files, and unsafe directory-link writes are reported. A missing/invalid unit does not normally block independent units.
+- An unchanged successful rerun does not rewrite content, links, configuration, or backups.
+
+## Backups and recovery
+
+Private state lives under `<root>/.agentic/`:
+
+```text
+state.json            ownership, baselines, pending resolutions/publication
+journal.json          one interrupted filesystem replacement (when present)
+conflicts/<id>/...    retained source variants and editable working copies
+backups/<uuid>.json   original path plus lossless snapshot before replacement
+```
+
+Snapshots preserve bytes (base64), ordinary POSIX permissions, directory entries, and original symlink text. They do not preserve ACLs, extended attributes, ownership, timestamps, or hard-link relationships. Full snapshots favor simplicity over storage efficiency; backups are never automatically pruned.
+
+A process lock prevents concurrent writers through the same configuration directory. Journaled publication resumes on the next mutating command. File/link replacement is atomic where POSIX allows it. Replacing nonempty directories or changing between directory and non-directory types has a brief recoverable gap; the tool does not claim a cross-directory filesystem transaction. Recovery refuses to overwrite newer changes.
+
+Manual restore: inspect a backup's `path` first, then reconstruct it into a **new scratch path**, not over live files:
+
+```sh
+python3.12 - /absolute/backup.json /absolute/new-scratch-path <<'PY'
+import json, sys
+from pathlib import Path
+from agentic_cli.storage import exists, materialize
+record = json.loads(Path(sys.argv[1]).read_text())
+target = Path(sys.argv[2])
+assert not exists(target), 'Choose a new scratch path'
+assert record['original'] is not None, 'There was no original at this path'
+materialize(target, record['original'])
+print('Original location:', record['path'])
+print('Restored snapshot:', target)
+PY
+```
+
+Run this from the checkout with a compatible Python, or from an environment with the package installed. Review the result before manually replacing the live path. A restored relative symlink keeps its original text and may only resolve correctly at its original location. The CLI intentionally has no undo/delete-backups command. Its private state is trusted local data; do not edit journals or accept them from untrusted sources.
+
+## Development checks
+
+```sh
+python3.12 -m unittest discover -s tests -v
+python3.12 -m pip wheel --no-deps . --wheel-dir /tmp/agentic-wheels
+```
+
+Tests use temporary homes, including subprocess CLI tests. They never run `sync` against the developer's real home. CI is configured to run the suite and package installation on macOS/Linux with Python 3.11 and 3.12. No test framework dependency is needed.

package/agentic_cli/__init__.py

@@ -0,0 +1 @@
+"""Shared agent home manager."""

package/agentic_cli/cli.py

@@ -0,0 +1,106 @@
+"""Standalone and LLM-friendly command-line interface."""
+import argparse
+import json
+import sys
+
+from .core import Home
+from .storage import lock
+
+
+def parser():
+    root = argparse.ArgumentParser(description="Share global agent skills and instructions safely.")
+    commands = root.add_subparsers(dest="command", required=True)
+    for name in ("sync", "status", "resolve", "continue"):
+        command = commands.add_parser(name)
+        command.add_argument("--json", action="store_true", help="Machine-readable output; never prompt")
+        if name == "sync":
+            command.add_argument("--root", help="Managed directory (remembered after initialization)")
+            command.add_argument("--dry-run", action="store_true", help="Inspect without changing the home or configuration")
+        if name == "resolve":
+            command.add_argument("id")
+            choice = command.add_mutually_exclusive_group(required=True)
+            choice.add_argument("--take", metavar="SOURCE")
+            choice.add_argument("--file", help="Resolved file, or complete directory for a skill")
+    return root
+
+
+def display(report, as_json=False):
+    if as_json:
+        print(json.dumps(report, indent=2))
+        return
+    if "root" in report:
+        print("Managed home:", report["root"])
+    for key in report.get("changed", []):
+        print("Would organize:" if report.get("dry_run") else "Organized:", key)
+    for warning in report.get("warnings", []):
+        print("Warning:", warning, file=sys.stderr)
+    for issue in report.get("issues", []):
+        print(f"Blocked: {issue['path']}: {issue['reason']}", file=sys.stderr)
+    for conflict in report.get("conflicts", []):
+        print(f"Conflict {conflict['id']}: {conflict['unit']}")
+        for source, info in conflict["sources"].items():
+            print(f"  {source}: {info['path']}")
+        if "working_copy" in conflict:
+            print("  Working copy:", conflict["working_copy"])
+        for command in conflict.get("commands", []):
+            print(" ", command)
+    for link in report.get("links", []):
+        print("Linked:" if link["linked"] else "Not linked:", link["path"])
+    if report.get("staged"):
+        print("Resolution staged; run agentic continue.")
+    if report.get("interrupted"):
+        print("Interrupted operation: run agentic sync to resume.")
+    if report.get("backups"):
+        print("Backups:", report["backups"])
+
+
+def interact(manager, report):
+    for conflict in report.get("conflicts", []):
+        sources = list(conflict.get("variants", {}))
+        print(f"\nResolve {conflict['unit']}: " + ", ".join(sources))
+        try:
+            answer = input("Source label, 'file' for an edited result, or Enter to defer: ").strip()
+            if answer == "file":
+                manager.resolve(conflict["id"], file=input("Resolved file/directory path: ").strip())
+            elif answer:
+                manager.resolve(conflict["id"], source=answer)
+        except (EOFError, KeyboardInterrupt):
+            print("\nDeferred; originals remain active.")
+            break
+        except (OSError, ValueError) as exc:
+            print(str(exc), file=sys.stderr)
+    return manager.continue_()
+
+
+def main(argv=None):
+    args = parser().parse_args(argv)
+    try:
+        manager = Home(root=getattr(args, "root", None))
+        if args.command == "status":
+            report = manager.status()
+        elif args.command == "sync" and args.dry_run:
+            report = manager.sync(dry_run=True)
+        else:
+            with lock(manager.config_dir):
+                manager = Home(root=getattr(args, "root", None))
+                if args.command == "sync":
+                    report = manager.sync()
+                elif args.command == "continue":
+                    report = manager.continue_()
+                else:
+                    report = manager.resolve(args.id, source=args.take, file=args.file)
+                if args.command in ("sync", "continue") and not args.json and sys.stdin.isatty() and report.get("conflicts"):
+                    display(report)
+                    report = interact(manager, report)
+        display(report, args.json)
+        return 2 if report.get("conflicts") or report.get("issues") else 0
+    except (OSError, RuntimeError, ValueError) as exc:
+        if args.json:
+            print(json.dumps({"error": str(exc)}))
+        else:
+            print(f"agentic: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/agentic_cli/core.py

@@ -0,0 +1,381 @@
+"""Reconcile discovery paths with a shared home, one activation unit at a time."""
+import os
+import shlex
+from pathlib import Path
+import uuid
+
+from .merge import merge, has_markers
+from .storage import (Unsafe, Transaction, atomic_json, digest, exists, guarded_parent,
+                      load_json, materialize, same_content, snapshot)
+
+# Codex's documented global catalog is now ~/.agents/skills; import legacy too.
+AGENTS = {
+    "claude": (".claude", ".claude/skills", ".claude/CLAUDE.md"),
+    "codex": (".codex", ".agents/skills", ".codex/AGENTS.md"),
+    "cursor": (".cursor", ".cursor/skills", None),
+    "pi": (".pi/agent", ".pi/agent/skills", ".pi/agent/AGENTS.md"),
+}
+
+
+def fingerprint(path):
+    return digest({"raw": snapshot(path), "content": snapshot(path, True)})
+
+
+def link_node(target):
+    return {"kind": "link", "target": str(target)}
+
+
+class Home:
+    def __init__(self, home=None, root=None, config_dir=None):
+        self.home = Path(home or Path.home()).resolve()
+        self.config_dir = Path(config_dir or os.environ.get("XDG_CONFIG_HOME", self.home / ".config")).resolve() / "agentic"
+        self.config_path = self.config_dir / "config.json"
+        self.config = load_json(self.config_path, {})
+        saved = self.config.get("pending_root") or self.config.get("root")
+        selected = Path(root).expanduser().absolute() if root else Path(saved or self.home / ".agentic")
+        self.root = selected.resolve()
+        self.old_root = Path(self.config["root"]) if self.config.get("root") else None
+        if saved and root and self.root != Path(saved):
+            previous = load_json(Path(saved) / ".agentic" / "state.json", {})
+            if previous.get("conflicts") or previous.get("applying") or self.config.get("pending_root"):
+                raise Unsafe("Finish pending work before selecting another root")
+        for base, skills, instructions in AGENTS.values():
+            # Even an absent agent may be installed later; reserve its entire home.
+            location = self.home / base
+            if self.root == location or self.root.is_relative_to(location) or location.is_relative_to(self.root):
+                raise Unsafe(f"Managed root overlaps an agent directory: {location}")
+        for reserved in (self.home / ".agents", self.config_dir):
+            if self.root == reserved or self.root.is_relative_to(reserved) or reserved.is_relative_to(self.root):
+                raise Unsafe(f"Managed root overlaps reserved directory: {reserved}")
+        if self.old_root and self.old_root != self.root:
+            if self.root.is_relative_to(self.old_root) or self.old_root.is_relative_to(self.root):
+                raise Unsafe("Old and new managed roots must not contain one another")
+        self.meta = self.root / ".agentic"
+        for path in (self.meta, self.root / "skills"):
+            if path.is_symlink():
+                raise Unsafe(f"Managed directory must not be a symlink: {path}")
+        self.state_path = self.meta / "state.json"
+        self.state = load_json(self.state_path, {"version": 1, "baselines": {}, "conflicts": {}})
+        if self.state.get("version") != 1:
+            raise Unsafe("Unsupported managed-state version")
+        self.agents = {name: spec for name, spec in AGENTS.items() if (self.home / spec[0]).is_dir()}
+        catalogs = [self.home / spec[1] for spec in self.agents.values()]
+        if "codex" in self.agents:
+            catalogs.append(self.home / ".codex/skills")
+        if "pi" in self.agents:
+            catalogs.append(self.home / ".agents/skills")
+        for catalog in catalogs:
+            if not catalog.is_dir():
+                continue
+            candidates = [catalog, *(p for p in catalog.iterdir() if p.is_dir())]
+            for source in candidates:
+                if self.root == source.resolve() or self.root.is_relative_to(source.resolve()):
+                    raise Unsafe(f"Managed root overlaps a source catalog or skill: {source}")
+        self.tx = Transaction(self.meta)
+
+    def save(self):
+        atomic_json(self.state_path, self.state)
+
+    def route_pending(self):
+        if self.config == {"root": str(self.root)}:
+            return
+        config = {**self.config, "pending_root": str(self.root)}
+        if config != self.config:
+            atomic_json(self.config_path, config)
+            self.config = config
+
+    def finish_config(self):
+        config = {"root": str(self.root)}
+        if self.config != config:
+            atomic_json(self.config_path, config)
+            self.config = config
+
+    def inventories(self):
+        units = {}
+        warnings = []
+        issues = []
+        catalogs = [("managed", self.root / "skills")]
+        catalogs += [(name, self.home / spec[1]) for name, spec in self.agents.items()]
+        if "codex" in self.agents and exists(self.home / ".codex/skills"):
+            catalogs.append(("codex-legacy", self.home / ".codex/skills"))
+        if "pi" in self.agents and "codex" not in self.agents and exists(self.home / ".agents/skills"):
+            catalogs.append(("shared-agents", self.home / ".agents/skills"))
+        if self.old_root and self.old_root != self.root:
+            catalogs.append(("previous-root", self.old_root / "skills"))
+        for label, catalog in catalogs:
+            if not exists(catalog):
+                continue
+            if not catalog.is_dir():
+                issues.append({"path": str(catalog), "reason": "Skill catalog is not a directory"})
+                continue
+            for entry in sorted(catalog.iterdir()):
+                if entry.name.startswith("."):
+                    continue  # System/plugin-owned hidden catalogs are not adopted.
+                if entry.is_file() and entry.suffix == ".md":
+                    warnings.append(f"Standalone Markdown skill left untouched (not portable): {entry}")
+                    continue
+                key = "skills/" + entry.name
+                units.setdefault(key, []).append((label, entry))
+        instructions = [("managed", self.root / "AGENTS.md")]
+        instructions += [(name, self.home / spec[2]) for name, spec in self.agents.items() if spec[2]]
+        if self.old_root and self.old_root != self.root:
+            instructions.append(("previous-root", self.old_root / "AGENTS.md"))
+        overrides = [self.home / self.agents[name][0] / "AGENTS.override.md"
+                     for name in ("codex", "pi") if name in self.agents]
+        shadowed = [p for p in overrides if exists(p)]
+        if shadowed:
+            issues.extend({"path": str(p), "reason": "Instruction override shadows shared instructions; reconcile/remove explicitly"} for p in shadowed)
+        elif any(exists(p) for _, p in instructions):
+            units["AGENTS.md"] = instructions
+        if "cursor" in self.agents:
+            warnings.append("Cursor instructions unsupported: global User Rules have no documented file-based discovery hook; skills are supported.")
+        for key in self.state["baselines"]:
+            if key == "AGENTS.md" and shadowed:
+                continue
+            units.setdefault(key, [])
+        for record in self.state["conflicts"].values():
+            if record["unit"] == "AGENTS.md" and shadowed:
+                continue
+            units.setdefault(record["unit"], [(label, Path(source["path"]))
+                                             for label, source in record["sources"].items()])
+        return units, warnings, issues
+
+    def destinations(self, key, sources):
+        paths = []
+        if key == "AGENTS.md":
+            paths.extend(self.home / spec[2] for spec in self.agents.values() if spec[2])
+        else:
+            name = key.split("/", 1)[1]
+            paths.extend(self.home / spec[1] / name for spec in self.agents.values())
+            paths.extend(path for label, path in sources if label in ("codex-legacy", "shared-agents"))
+        return list(dict.fromkeys(paths))
+
+    def inspect_unit(self, key, sources):
+        target = self.root / key
+        sources = list(sources)
+        if not any(p == target for _, p in sources):
+            sources.insert(0, ("managed", target))
+        for path in self.destinations(key, sources):
+            if not any(p == path for _, p in sources):
+                sources.append(("destination-" + str(len(sources)), path))
+        variants, captured = [], {}
+        for label, path in sources:
+            captured[label] = {"path": str(path), "fingerprint": fingerprint(path)}
+            value = snapshot(path, True)
+            if value is not None:
+                variants.append((label, value))
+        if not variants:
+            raise Unsafe(f"Managed target is missing; no source to restore: {target}")
+        if key.startswith("skills/") and any(n["kind"] != "dir" for _, n in variants):
+            # Type collisions are resolvable; a lone invalid skill is not publishable.
+            if len(variants) == 1:
+                raise Unsafe(f"Skill must be a directory: {variants[0][0]}: {key}")
+        base = self.state["baselines"].get(key)
+        result, pending = merge(variants, base)
+        return sources, captured, variants, result, pending
+
+    def conflict(self, key, captured, variants, result, pending):
+        identifier = digest(key)[:12]
+        old = self.state["conflicts"].get(identifier)
+        if old and old["sources"] == captured:
+            return old
+        directory = self.meta / "conflicts" / identifier / uuid.uuid4().hex
+        guarded_parent(directory)
+        directory.mkdir(parents=True)
+        paths = {}
+        for label, node in variants:
+            path = directory / label
+            materialize(path, node)
+            paths[label] = str(path)
+        work = directory / "working"
+        materialize(work, result)
+        record = {"id": identifier, "unit": key, "sources": captured, "variants": paths,
+                  "working_copy": str(work), "conflicting_paths": pending,
+                  "resolution": None, "commands": [f"agentic resolve {identifier} --take SOURCE",
+                                                    f"agentic resolve {identifier} --file {shlex.quote(str(work))}", "agentic continue"]}
+        self.state["conflicts"][identifier] = record
+        self.save()
+        return record
+
+    def publish(self, key, sources, result, dry_run=False):
+        if key.startswith("skills/") and (result["kind"] != "dir" or
+                result["entries"].get("SKILL.md", {}).get("kind") != "file"):
+            raise Unsafe(f"Resolved skill must be a directory containing a regular SKILL.md file: {key}")
+        if key == "AGENTS.md":
+            if result["kind"] != "file":
+                raise Unsafe("Shared instructions must be a regular file")
+            for name in ("codex", "pi"):
+                if name in self.agents and exists(self.home / self.agents[name][0] / "AGENTS.override.md"):
+                    raise Unsafe("Instruction override appeared; reconcile/remove it before continuing")
+        target = self.root / key
+        current = snapshot(target, True)
+        canonical = result
+        if current is not None and same_content(current, result):
+            canonical = snapshot(target)
+        elif current is None:
+            # Preserve an external source link only when the complete selected tree matches.
+            discovery = [self.home / spec[0] for spec in AGENTS.values()]
+            for _, path in sources:
+                if path.is_symlink() and same_content(snapshot(path, True), result):
+                    external = path.resolve()
+                    excluded = [self.root, *(discovery), self.home / ".agents"]
+                    if self.old_root:
+                        excluded.append(self.old_root)
+                    if not any(external == p or external.is_relative_to(p) for p in excluded):
+                        canonical = link_node(external)
+                        break
+        operations = []
+        for path, node in [(target, canonical), *[(p, link_node(target)) for p in self.destinations(key, sources)]]:
+            # A whole-catalog link already pointing at this root needs no child writes.
+            if path != target and path.parent.is_symlink() and path.parent.resolve() == target.parent:
+                continue
+            # A dry run has planned, but not performed, catalog normalization.
+            guarded_parent(path.parent if dry_run and key.startswith("skills/") and path != target
+                           and path.parent.is_symlink() and path.parent.is_dir() else path)
+            before = snapshot(path)
+            if before != node:
+                operations.append({"path": str(path), "before": before, "after": node})
+        if not operations and self.state["baselines"].get(key) == result:
+            return False
+        if dry_run:
+            return True
+        self.state["applying"] = {"unit": key, "result": result, "operations": operations}
+        self.save()
+        self.resume_apply()
+        return True
+
+    def resume_apply(self):
+        self.tx.recover()
+        pending = self.state.get("applying")
+        if not pending:
+            return
+        for operation in pending["operations"]:
+            path = Path(operation["path"])
+            current = snapshot(path)
+            if current == operation["after"]:
+                continue
+            if current != operation["before"]:
+                raise Unsafe(f"Newer changes block recovery at {path}; backups retained")
+            self.tx.replace(path, operation["after"])
+        self.state["baselines"][pending["unit"]] = pending["result"]
+        self.state["conflicts"].pop(digest(pending["unit"])[:12], None)
+        del self.state["applying"]
+        self.save()
+
+    def sync(self, dry_run=False):
+        if not dry_run:
+            self.resume_apply()
+        units, warnings, issues = self.inventories()
+        report = {"root": str(self.root), "changed": [], "conflicts": [], "issues": issues, "warnings": warnings,
+                  "backups": str(self.meta / "backups"), "dry_run": dry_run}
+        inspected = []
+        # Inventory and read every unit before any user-file mutation.
+        for key, sources in sorted(units.items()):
+            try:
+                inspected.append((key, self.inspect_unit(key, sources)))
+            except (OSError, RuntimeError, ValueError) as exc:
+                issues.append({"path": key, "reason": str(exc)})
+        if not dry_run:
+            self.meta.mkdir(mode=0o700, parents=True, exist_ok=True)
+            self.route_pending()
+        normalized = self.normalize_catalogs(units, dry_run=dry_run)
+        if normalized:
+            if not dry_run:
+                # Only topology changed: all old targets remain active via child links.
+                inspected = [(key, self.inspect_unit(key, data[0])) for key, data in inspected]
+            report["changed"].extend(normalized)
+        for key, (sources, captured, variants, result, pending) in inspected:
+            try:
+                old = self.state["conflicts"].get(digest(key)[:12])
+                if pending or old:
+                    if dry_run:
+                        report["conflicts"].append({"id": digest(key)[:12], "unit": key,
+                                                    "sources": captured, "conflicting_paths": pending})
+                    else:
+                        report["conflicts"].append(self.conflict(key, captured, variants, result, pending))
+                    continue
+                if any(fingerprint(Path(s["path"])) != s["fingerprint"] for s in captured.values()):
+                    raise Unsafe(f"Source changed during inventory: {key}; rerun sync")
+                if self.publish(key, sources, result, dry_run=dry_run):
+                    report["changed"].append(key)
+            except (OSError, RuntimeError, ValueError) as exc:
+                if self.state.get("applying"):
+                    raise  # Do not overwrite an interrupted publication with another unit.
+                issues.append({"path": key, "reason": str(exc)})
+        reported = {c["id"] for c in report["conflicts"]}
+        report["conflicts"].extend(c for identifier, c in self.state["conflicts"].items() if identifier not in reported)
+        if not dry_run and not report["conflicts"] and not issues:
+            self.finish_config()
+        return report
+
+    def normalize_catalogs(self, units, dry_run=False):
+        """Replace whole-catalog links with per-entry links without touching targets."""
+        catalogs = set()
+        for key, sources in units.items():
+            if key.startswith("skills/"):
+                catalogs.update(p.parent for p in self.destinations(key, sources))
+        changed = []
+        for catalog in sorted(catalogs):
+            if not catalog.is_symlink() or not catalog.is_dir():
+                continue
+            if catalog.resolve() == self.root / "skills":
+                continue
+            node = {"kind": "dir", "mode": catalog.stat().st_mode & 0o777,
+                    "entries": {p.name: link_node(p.resolve()) for p in catalog.iterdir()}}
+            # Validate the old tree before converting its discovery entry.
+            snapshot(catalog, True)
+            guarded_parent(catalog)
+            if not dry_run:
+                self.tx.replace(catalog, node)
+            changed.append(str(catalog))
+        return changed
+
+    def resolve(self, identifier, source=None, file=None):
+        self.resume_apply()
+        record = self.state["conflicts"].get(identifier)
+        if not record:
+            raise Unsafe(f"Unknown conflict: {identifier}")
+        if source is not None:
+            if source not in record["variants"]:
+                raise Unsafe("Choose a source from: " + ", ".join(record["variants"]))
+            path = Path(record["variants"][source])
+        else:
+            path = Path(file).expanduser().absolute()
+        node = snapshot(path, True)
+        if node is None or has_markers(node):
+            raise Unsafe("Resolution missing or still contains conflict markers")
+        record["resolution"] = node
+        self.save()
+        return {"id": identifier, "staged": True, "next": "agentic continue"}
+
+    def continue_(self):
+        self.resume_apply()
+        for identifier, record in list(self.state["conflicts"].items()):
+            if record["resolution"] is None:
+                continue
+            units, _, _ = self.inventories()
+            sources = list(units.get(record["unit"], []))
+            sources.extend((label, Path(s["path"])) for label, s in record["sources"].items()
+                           if not any(str(p) == s["path"] for _, p in sources))
+            captured = self.inspect_unit(record["unit"], sources)[1]
+            # Compare paths, not labels: absent destinations acquire agent labels on discovery.
+            before = {s["path"]: s["fingerprint"] for s in record["sources"].values()}
+            now = {s["path"]: s["fingerprint"] for s in captured.values()}
+            if now != before:
+                record["resolution"] = None
+                self.save()
+                continue  # sync refreshes source snapshots and the working copy.
+            self.publish(record["unit"], sources, record["resolution"])
+        return self.sync()
+
+    def status(self):
+        units, warnings, issues = self.inventories()
+        links = []
+        for key, sources in sorted(units.items()):
+            for path in self.destinations(key, sources):
+                links.append({"path": str(path), "target": str(self.root / key),
+                              "linked": path.is_symlink() and path.exists() and path.resolve() == (self.root / key).resolve()})
+        return {"root": str(self.root), "conflicts": list(self.state["conflicts"].values()),
+                "links": links, "warnings": warnings, "issues": issues,
+                "interrupted": bool(self.state.get("applying") or self.tx.journal.exists()),
+                "backups": str(self.meta / "backups")}

package/agentic_cli/merge.py

@@ -0,0 +1,83 @@
+"""Conservative tree merging: no invented ancestors or source precedence."""
+import base64
+import copy
+import subprocess
+import tempfile
+from pathlib import Path
+
+from .storage import Unsafe, same_content
+
+
+def text(node):
+    if node is None or node["kind"] != "file":
+        return None
+    data = base64.b64decode(node["data"])
+    try:
+        result = data.decode("utf-8")
+    except UnicodeDecodeError:
+        return None
+    return None if "\0" in result else result
+
+
+def file_node(value, mode=0o644):
+    return {"kind": "file", "mode": mode,
+            "data": base64.b64encode(value.encode()).decode()}
+
+
+def merge(variants, base=None, relative=""):
+    """Return a complete working tree and unresolved relative paths."""
+    unique = []
+    for label, node in variants:
+        if node is not None and not any(same_content(node, old) for _, old in unique):
+            unique.append((label, node))
+    if not unique:
+        return copy.deepcopy(base), []
+    if all(node["kind"] == "dir" for _, node in unique):
+        entries = {}
+        conflicts = []
+        base_entries = base["entries"] if base and base["kind"] == "dir" else {}
+        names = set(base_entries)
+        for _, node in unique:
+            names.update(node["entries"])
+        for name in sorted(names):
+            entries[name], pending = merge(
+                [(label, node["entries"].get(name)) for label, node in unique],
+                base_entries.get(name), f"{relative}/{name}".lstrip("/"))
+            conflicts.extend(pending)
+        return {"kind": "dir", "mode": unique[0][1]["mode"], "entries": entries}, conflicts
+    if len(unique) == 1:
+        return copy.deepcopy(unique[0][1]), []
+    if base is not None:
+        changed = [(label, node) for label, node in unique if not same_content(node, base)]
+        if len(changed) == 1:
+            return copy.deepcopy(changed[0][1]), []
+        unique = changed
+    if len(unique) == 2 and base is not None and text(base) is not None and all(text(n) is not None for _, n in unique):
+        with tempfile.TemporaryDirectory(prefix="agentic-merge-") as directory:
+            paths = [Path(directory) / str(i) for i in range(3)]
+            for path, node in zip(paths, (unique[0][1], base, unique[1][1])):
+                path.write_bytes(base64.b64decode(node["data"]))
+            result = subprocess.run(
+                ["git", "merge-file", "-p", "-L", unique[0][0], "-L", "baseline", "-L", unique[1][0],
+                 *map(str, paths)], capture_output=True)
+            if result.returncode < 0 or result.returncode > 127:
+                raise Unsafe(result.stderr.decode(errors="replace") or "git merge-file failed")
+            node = {"kind": "file", "mode": unique[0][1]["mode"],
+                    "data": base64.b64encode(result.stdout).decode()}
+            return node, [relative or "."] if result.returncode else []
+    if all(text(n) is not None for _, n in unique):
+        parts = []
+        for i, (label, node) in enumerate(unique):
+            parts.append(("<<<<<<< " if i == 0 else "======= ") + label + "\n")
+            value = text(node)
+            parts.append(value + ("" if value.endswith("\n") else "\n"))
+        parts.append(">>>>>>> resolve all variants\n")
+        return file_node("".join(parts), unique[0][1]["mode"]), [relative or "."]
+    return copy.deepcopy(unique[0][1]), [relative or "."]
+
+
+def has_markers(node):
+    if node["kind"] == "dir":
+        return any(has_markers(child) for child in node["entries"].values())
+    value = text(node)
+    return value is not None and any(line.startswith(("<<<<<<<", "=======", ">>>>>>>")) for line in value.splitlines())

package/agentic_cli/storage.py

@@ -0,0 +1,176 @@
+"""Lossless snapshots and journaled, backed-up filesystem replacements."""
+import base64
+import contextlib
+import fcntl
+import hashlib
+import json
+import os
+from pathlib import Path
+import shutil
+import stat
+import tempfile
+import uuid
+
+
+class Unsafe(ValueError):
+    pass
+
+
+def exists(path):
+    return path.exists() or path.is_symlink()
+
+
+# ponytail: full snapshots suit small skill trees; use content-addressed blobs if storage becomes material.
+def snapshot(path, follow=False, ancestors=()):
+    path = Path(path)
+    if not exists(path):
+        return None
+    mode = path.lstat().st_mode
+    if stat.S_ISLNK(mode):
+        try:
+            target = path.resolve(strict=True)
+        except (OSError, RuntimeError) as exc:
+            raise Unsafe(f"Broken or cyclic link: {path}") from exc
+        if target in ancestors:
+            raise Unsafe(f"Cyclic link: {path}")
+        if follow:
+            return snapshot(target, True, ancestors)
+        return {"kind": "link", "target": os.readlink(path)}
+    if stat.S_ISREG(mode):
+        return {"kind": "file", "mode": stat.S_IMODE(mode),
+                "data": base64.b64encode(path.read_bytes()).decode()}
+    if stat.S_ISDIR(mode):
+        real = path.resolve()
+        if real in ancestors:
+            raise Unsafe(f"Cyclic directory: {path}")
+        return {"kind": "dir", "mode": stat.S_IMODE(mode), "entries": {
+            p.name: snapshot(p, follow, (*ancestors, real))
+            for p in sorted(path.iterdir())}}
+    raise Unsafe(f"Special file is not supported: {path}")
+
+
+def digest(node):
+    return hashlib.sha256(json.dumps(node, sort_keys=True).encode()).hexdigest()
+
+
+def same_content(a, b):
+    # Permissions are retained from the selected source; content decides conflicts.
+    def clean(n):
+        if n is None:
+            return None
+        result = {k: v for k, v in n.items() if k != "mode"}
+        if n["kind"] == "dir":
+            result["entries"] = {name: clean(child) for name, child in n["entries"].items()}
+        return result
+    return clean(a) == clean(b)
+
+
+def materialize(path, node):
+    if node["kind"] == "file":
+        path.write_bytes(base64.b64decode(node["data"]))
+        path.chmod(node["mode"])
+    elif node["kind"] == "link":
+        path.symlink_to(node["target"])
+    elif node["kind"] == "dir":
+        path.mkdir()
+        for name, child in node["entries"].items():
+            if name in (".", "..") or "/" in name or not name:
+                raise Unsafe(f"Unsafe snapshot entry: {name!r}")
+            materialize(path / name, child)
+        path.chmod(node["mode"])
+    else:
+        raise Unsafe("Invalid snapshot kind")
+
+
+def remove(path):
+    if path.is_dir() and not path.is_symlink():
+        shutil.rmtree(path)
+    elif exists(path):
+        path.unlink()
+
+
+def atomic_json(path, value):
+    guarded_parent(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, name = tempfile.mkstemp(prefix=".agentic-", dir=path.parent)
+    try:
+        with os.fdopen(fd, "w") as stream:
+            json.dump(value, stream, indent=2, sort_keys=True)
+            stream.write("\n")
+            stream.flush()
+            os.fsync(stream.fileno())
+        os.replace(name, path)
+    finally:
+        if os.path.lexists(name):
+            os.unlink(name)
+
+
+def load_json(path, default):
+    return json.loads(path.read_text()) if path.exists() else default
+
+
+@contextlib.contextmanager
+def lock(config_dir):
+    config_dir.mkdir(parents=True, exist_ok=True)
+    path = config_dir / "lock"
+    fd = os.open(path, os.O_CREAT | os.O_RDWR | os.O_NOFOLLOW, 0o600)
+    with os.fdopen(fd, "w") as stream:
+        try:
+            fcntl.flock(stream, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except BlockingIOError as exc:
+            raise Unsafe("Another agentic operation is running") from exc
+        yield
+
+
+def guarded_parent(path):
+    """Do not write through an external directory symlink."""
+    for parent in path.parents:
+        if parent.is_symlink():
+            raise Unsafe(f"Refusing to write through directory symlink: {parent}")
+
+
+class Transaction:
+    def __init__(self, metadata):
+        self.metadata = metadata
+        self.journal = metadata / "journal.json"
+
+    def recover(self):
+        op = load_json(self.journal, None)
+        if op is None:
+            return
+        path = Path(op["path"])
+        guarded_parent(path)
+        current = snapshot(path)
+        if current == op["after"]:
+            self.journal.unlink()
+            return
+        if current != op["before"] and not (current is None and op["phase"] == "install"):
+            raise Unsafe(f"Interrupted operation has newer changes at {path}; backup: {op['backup']}")
+        backup = Path(op["backup"])
+        if not backup.exists():
+            atomic_json(backup, {"path": str(path), "original": op["before"]})
+        temp = Path(op["temporary"])
+        remove(temp)
+        materialize(temp, op["after"])
+        op["phase"] = "install"
+        atomic_json(self.journal, op)
+        if (path.is_dir() and not path.is_symlink()) or (op["after"]["kind"] == "dir" and exists(path)):
+            # POSIX cannot atomically replace directories across node types.
+            # The journal + retained snapshot make this short gap recoverable.
+            remove(path)
+        os.replace(temp, path)
+        self.journal.unlink()
+
+    def replace(self, path, node):
+        self.recover()
+        guarded_parent(path)
+        before = snapshot(path)
+        if before == node:
+            return
+        path.parent.mkdir(parents=True, exist_ok=True)
+        token = uuid.uuid4().hex
+        op = {"path": str(path), "before": before, "after": node,
+              "phase": "prepare", "backup": str(self.metadata / "backups" / f"{token}.json"),
+              "temporary": str(path.parent / f".agentic-{token}")}
+        atomic_json(self.journal, op)
+        self.recover()

package/bin/agentic.cjs

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+'use strict';
+const { spawnSync } = require('node:child_process');
+const path = require('node:path');
+
+// Use an installed interpreter; never download runtimes or run pip during install.
+const candidates = process.env.AGENTIC_PYTHON
+  ? [process.env.AGENTIC_PYTHON]
+  : ['python3', 'python3.14', 'python3.13', 'python3.12', 'python3.11', 'python'];
+const python = candidates.find(command => spawnSync(command, [
+  '-I', '-c', 'import sys; sys.exit(0 if sys.version_info >= (3, 11) else 1)'
+], { stdio: 'ignore' }).status === 0);
+if (!python) {
+  console.error('agentic requires Python 3.11+. Install it or set AGENTIC_PYTHON to its executable path.');
+  process.exit(1);
+}
+const result = spawnSync(python, ['-I', '-c',
+  'import sys; sys.path.insert(0, sys.argv.pop(1)); from agentic_cli.cli import main; sys.exit(main())',
+  path.resolve(__dirname, '..'), ...process.argv.slice(2)
+], { stdio: 'inherit' });
+if (result.error) console.error(`agentic: ${result.error.message}`);
+if (result.signal) process.kill(process.pid, result.signal);
+else process.exit(result.status ?? 1);

package/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "agentic-home-cli",
+  "version": "0.1.0",
+  "description": "Consolidate global agent skills and instructions with safe, resumable conflicts",
+  "license": "UNLICENSED",
+  "bin": { "agentic": "bin/agentic.cjs" },
+  "files": ["bin/agentic.cjs", "agentic_cli/*.py", "README.md"],
+  "engines": { "node": ">=18" },
+  "os": ["darwin", "linux"],
+  "publishConfig": { "access": "public" },
+  "scripts": { "test": "node --test tests/npm-launcher.cjs" },
+  "keywords": ["ai", "agents", "skills", "claude", "codex", "cursor", "pi"]
+}