@delorenj/pjangler 1.3.7 → 1.4.2

package/.mise/scripts/link-agentfiles.sh

@@ -1,9 +1,42 @@
 #!/bin/bash
+set -eu
 
-if [ -f AGENTS.md ]; then
-  ln -sf AGENTS.md CLAUDE.md
-  ln -sf AGENTS.md GEMINI.md
-  echo "✅ AI agent symlinks verified"
+# Symlink the per-CLI agent instruction files at AGENTS.md.
+#
+# A mise ENTER hook runs with cwd set to the directory the user cd'd into, NOT
+# to config_root — measured on mise 2026.8.10, and true even for a parent config
+# when the entered directory is a nested child. `mise run <task>` does run at
+# config_root, which is why the old cwd-relative version looked correct for
+# years: only the enter-hook path was wrong. So take the root explicitly, and
+# fall back to this script's own location — never to cwd.
+root="${1:-${MISE_CONFIG_ROOT:-}}"
+own_root=$(CDPATH= cd "$(dirname "$0")/../.." && pwd -P)
+if [ -z "$root" ]; then
+  root="$own_root"
 else
-  echo "No AGENTS.md file found. Can't symlink."
+  root=$(CDPATH= cd "$root" && pwd -P)
 fi
+if [ "$root" != "$own_root" ]; then
+  echo "link-agentfiles: refusing to act on $root; this script belongs to $own_root" >&2
+  echo "link-agentfiles: a nested repo must ship its own .mise/scripts copy" >&2
+  exit 1
+fi
+
+CDPATH= cd "$root"
+if [ ! -f AGENTS.md ]; then
+  echo "No AGENTS.md in $root. Nothing to symlink."
+  exit 0
+fi
+
+# `ln -sf` cannot tell a stale link it owns from a real file it must not touch:
+# -f means "unlink whatever is there". A hand-written CLAUDE.md was silently
+# replaced by a symlink, and the script printed a green checkmark while doing it.
+for name in CLAUDE.md GEMINI.md; do
+  if [ -e "$name" ] && [ ! -L "$name" ]; then
+    echo "link-agentfiles: refusing to replace the real file $root/$name with a symlink" >&2
+    echo "link-agentfiles: move its content into AGENTS.md, then delete $name" >&2
+    exit 1
+  fi
+  ln -sfn AGENTS.md "$name"
+done
+echo "✅ AGENTS.md links verified in $root"

package/README.md

@@ -18,6 +18,26 @@ node dist/index.js --help
 pjangler --help
 ```
 
+## Project notebook
+
+`pjangler notebook` manages one companion Open Notebook for a registered
+repository. The binding and stable Overview note IDs live in `.project.json`
+and the project registry; endpoint, authentication mode, defaults, and finite
+capture limits live in the registry's global `notebook` configuration.
+
+```bash
+pjangler notebook status . --json
+pjangler notebook create . --live --json
+pjangler notebook list notes . --json
+pjangler notebook search notes "release evidence" . --json
+pjangler notebook audit . --json
+pjangler notebook migrate . --live --apply --json
+```
+
+True `SessionStart` and `SessionEnd` hooks are projected separately from the
+project-scoped hook masters. Their per-repository policy stays fail-open and
+disabled until explicitly enabled in `.project.json`.
+
 ## Orienting in a repo
 
 `describe` reads a repo and reports what it actually is — detected type,

package/dist/assets/project-notebook-skill/SHA256SUMS

@@ -0,0 +1,10 @@
+dba418f3b40d2e1362e615bdfda6cb1616ec5e49e2e8bd81ca48144ef219b29f  agents/openai.yaml
+8a469caf88ed05dc466ffaad611cb45dd0c26046595d9538415d7c89287c8800  hooks/claude.settings.json
+8a469caf88ed05dc466ffaad611cb45dd0c26046595d9538415d7c89287c8800  hooks/hooks.master.json
+848d2f5ba9000c2538e21d5a21257c72a5e4799ee3a9145a4eb9d7b00179e52b  hooks/session-end.sh
+f146a81c3e6cfbbce28c85c3c2163255974abef61339638c2a0ac9902346905e  hooks/session-start.sh
+a25d1d34f9960b2b3bf17a00191d5477b81a05bffe5d4e183c2954cc3975b535  references/configuration.md
+6a61d9dd0d5dd32f8a7fefcb82001bbad90523704fa1500b7e0becc3a848545c  references/recovery.md
+95d1b6199b0416f7fdf3306215bc10a9a647f64654ccbb26786cc228fc35ac37  scripts/project-hooks.py
+8567ab2567ec412eb8d673dd713340b81a45e69374d9baee3cb7e827999be437  SKILL.md
+7e16380d079277ee08b8ea64767b1596dc4e8f7ce1bd89c45d9d4821f6d493d3  tests/test_project_hooks.py

package/dist/assets/project-notebook-skill/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: project-notebook
+description: Operate PJangler Project Notebook as bounded, Git-grounded project memory. Use when an agent needs to inspect notebook status, read or update the stable Overview, manage scoped notes, search project knowledge, audit or migrate a binding, recover capture receipts, or install/check the canonical global Project Notebook hooks without changing foreign hooks.
+---
+
+# Project Notebook
+
+Treat Git and the repository's Project Manifest as authoritative. Treat the
+remote notebook as scoped, derivative context that PJangler owns and can audit.
+
+## Work through PJangler
+
+1. Resolve the repository explicitly when the current directory is ambiguous.
+2. Inspect `pj notebook status [repo]` before assuming a healthy binding.
+3. Use `--json` when another tool will consume the result. Check `ok`, symbolic
+   error code, and `next_actions`; do not infer success from prose.
+4. Keep reads and mutations project-scoped. Never call the notebook service
+   directly or accept a result whose membership in the resolved binding is not
+   proven.
+5. Use `pj notebook audit [repo]` to diagnose Drift. Use
+   `pj notebook migrate [repo]` for an owned repair plan, adding `--apply` for
+   local changes and `--live` only when remote repair is intended.
+6. Preserve repository files as the source of truth. Never overwrite Git
+   content from notebook content.
+
+## Use the public command surface
+
+Use these command families rather than internal hook or worker entrypoints:
+
+- `pj notebook status|create|overview|audit|migrate`
+- `pj notebook list notes`, `get note`, `add note`, `update note`, `delete note`
+- `pj notebook search notes`
+- `pj notebook capture list|retry`
+
+Direct note mutation authorizes only that selected operation. `create` and live
+migration require `--live`; note deletion requires confirmation or `--yes`.
+Never delete the stable Overview note.
+
+For complete command forms, policy precedence, hook projection, and safe
+configuration, read [configuration.md](references/configuration.md). For
+capture pressure, Drift, snapshots, uninstall, and failure recovery, read
+[recovery.md](references/recovery.md).
+
+## Handle session context safely
+
+- Let the global wrappers scope themselves at runtime. Global installation does
+  not enable a repository.
+- Use true `SessionStart` and `SessionEnd` only. Never substitute `Stop` for a
+  session boundary.
+- Keep hook payloads and user content out of argv and logs.
+- Treat hook failures as bounded, actionable, fail-open diagnostics.
+- Treat `PROJECT NOTEBOOK OVERVIEW DRIFT` as stale context. Run the exact audit
+  or migration action reported before relying on the stored Overview.
+- Treat retention pressure as an admission diagnostic, not a receipt state.
+  Never delete or compact an unresolved receipt to make room.
+
+## Protect credentials and foreign configuration
+
+Resolve endpoint and authentication through PJangler runtime configuration;
+never store them in a repository Manifest, note, hook command, or skill file.
+Use `scripts/project-hooks.py` for global Claude projection. Its owner marker is
+exactly `project-notebook.v1`; do not hand-edit live settings or remove
+Bloodbank, Hindsight, Git checkpoint, notification, CommonProject, or other
+foreign hooks.

package/dist/assets/project-notebook-skill/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Project Notebook"
+  short_description: "Operate Git-grounded project memory safely"
+  default_prompt: "Use $project-notebook to inspect this repository's notebook status and take the safest scoped next action."
+policy:
+  allow_implicit_invocation: true

package/dist/assets/project-notebook-skill/export-manifest.json

@@ -0,0 +1,56 @@
+{
+  "schema_version": 1,
+  "skill": "project-notebook",
+  "files": [
+    {
+      "path": "agents/openai.yaml",
+      "sha256": "dba418f3b40d2e1362e615bdfda6cb1616ec5e49e2e8bd81ca48144ef219b29f",
+      "mode": "0644"
+    },
+    {
+      "path": "hooks/claude.settings.json",
+      "sha256": "8a469caf88ed05dc466ffaad611cb45dd0c26046595d9538415d7c89287c8800",
+      "mode": "0644"
+    },
+    {
+      "path": "hooks/hooks.master.json",
+      "sha256": "8a469caf88ed05dc466ffaad611cb45dd0c26046595d9538415d7c89287c8800",
+      "mode": "0644"
+    },
+    {
+      "path": "hooks/session-end.sh",
+      "sha256": "848d2f5ba9000c2538e21d5a21257c72a5e4799ee3a9145a4eb9d7b00179e52b",
+      "mode": "0755"
+    },
+    {
+      "path": "hooks/session-start.sh",
+      "sha256": "f146a81c3e6cfbbce28c85c3c2163255974abef61339638c2a0ac9902346905e",
+      "mode": "0755"
+    },
+    {
+      "path": "references/configuration.md",
+      "sha256": "a25d1d34f9960b2b3bf17a00191d5477b81a05bffe5d4e183c2954cc3975b535",
+      "mode": "0644"
+    },
+    {
+      "path": "references/recovery.md",
+      "sha256": "6a61d9dd0d5dd32f8a7fefcb82001bbad90523704fa1500b7e0becc3a848545c",
+      "mode": "0644"
+    },
+    {
+      "path": "scripts/project-hooks.py",
+      "sha256": "95d1b6199b0416f7fdf3306215bc10a9a647f64654ccbb26786cc228fc35ac37",
+      "mode": "0755"
+    },
+    {
+      "path": "SKILL.md",
+      "sha256": "8567ab2567ec412eb8d673dd713340b81a45e69374d9baee3cb7e827999be437",
+      "mode": "0644"
+    },
+    {
+      "path": "tests/test_project_hooks.py",
+      "sha256": "7e16380d079277ee08b8ea64767b1596dc4e8f7ce1bd89c45d9d4821f6d493d3",
+      "mode": "0644"
+    }
+  ]
+}

package/dist/assets/project-notebook-skill/hooks/claude.settings.json

@@ -0,0 +1,26 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "PJ_HOOK_OWNER=project-notebook.v1 \"$HOME/.agents/skills/project-notebook/hooks/session-start.sh\"",
+            "timeout": 3
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "PJ_HOOK_OWNER=project-notebook.v1 \"$HOME/.agents/skills/project-notebook/hooks/session-end.sh\"",
+            "timeout": 1
+          }
+        ]
+      }
+    ]
+  }
+}

package/dist/assets/project-notebook-skill/hooks/hooks.master.json

@@ -0,0 +1,26 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "PJ_HOOK_OWNER=project-notebook.v1 \"$HOME/.agents/skills/project-notebook/hooks/session-start.sh\"",
+            "timeout": 3
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "PJ_HOOK_OWNER=project-notebook.v1 \"$HOME/.agents/skills/project-notebook/hooks/session-end.sh\"",
+            "timeout": 1
+          }
+        ]
+      }
+    ]
+  }
+}

package/dist/assets/project-notebook-skill/hooks/session-end.sh

@@ -0,0 +1,228 @@
+#!/usr/bin/python3 -I
+"""Fail-open SessionEnd bridge to the fixed PJangler user installation."""
+
+from __future__ import annotations
+
+import grp
+import os
+import pwd
+import signal
+import stat
+import subprocess
+import sys
+from pathlib import Path
+
+DISPLAY_EVENT = "SessionEnd"
+HOOK_EVENT = "session-close"
+REQUEST_LIMIT_BYTES = 1_048_576
+STREAM_LIMIT_BYTES = REQUEST_LIMIT_BYTES + 1
+CHILD_TIMEOUT_SECONDS = 0.75
+NODE_BINARY = Path("/usr/bin/node")
+AUTH_VARIABLE = "OPEN_NOTEBOOK_PASSWORD"
+
+
+class LauncherError(RuntimeError):
+    """A bounded launcher-validation failure."""
+
+
+def fail_open(reason: str) -> int:
+    print(f"project-notebook: {DISPLAY_EVENT} {reason}", file=sys.stderr)
+    return 0
+
+
+def canonical_identity() -> pwd.struct_passwd:
+    entry = pwd.getpwuid(os.geteuid())
+    if entry.pw_uid != os.geteuid():
+        raise LauncherError("skipped; canonical user identity is invalid")
+    home = Path(entry.pw_dir)
+    if not home.is_absolute() or home == Path("/") or ".." in home.parts:
+        raise LauncherError("skipped; canonical user home is invalid")
+    return entry
+
+
+def private_primary_group(entry: pwd.struct_passwd) -> bool:
+    try:
+        group = grp.getgrgid(entry.pw_gid)
+        primary_users = {
+            candidate.pw_name for candidate in pwd.getpwall() if candidate.pw_gid == entry.pw_gid
+        }
+    except (KeyError, OSError):
+        return False
+    if entry.pw_name not in primary_users:
+        return False
+    writers = primary_users | set(group.gr_mem)
+    return writers <= {entry.pw_name}
+
+
+def path_components(path: Path) -> list[Path]:
+    if not path.is_absolute() or path == Path("/"):
+        raise LauncherError("skipped; trusted path is invalid")
+    components: list[Path] = []
+    current = Path("/")
+    for component in path.parts[1:]:
+        if component in ("", ".", ".."):
+            raise LauncherError("skipped; trusted path is invalid")
+        current /= component
+        components.append(current)
+    return components
+
+
+def reject_symlink_components(path: Path) -> None:
+    for component in path_components(path):
+        try:
+            information = component.lstat()
+        except OSError as exc:
+            raise LauncherError("skipped; trusted path is unavailable") from exc
+        if stat.S_ISLNK(information.st_mode):
+            raise LauncherError("skipped; trusted path contains a symlink")
+
+
+def validate_owned_component(
+    path: Path,
+    entry: pwd.struct_passwd,
+    *,
+    directory: bool,
+    private_group: bool,
+) -> None:
+    try:
+        information = path.lstat()
+    except OSError as exc:
+        raise LauncherError("skipped; trusted path is unavailable") from exc
+    expected_type = stat.S_ISDIR if directory else stat.S_ISREG
+    if stat.S_ISLNK(information.st_mode) or not expected_type(information.st_mode):
+        raise LauncherError("skipped; trusted path has an unsafe type")
+    if information.st_uid != entry.pw_uid or information.st_gid != entry.pw_gid:
+        raise LauncherError("skipped; trusted path ownership is unsafe")
+    mode = stat.S_IMODE(information.st_mode)
+    special = stat.S_ISUID | stat.S_ISGID | stat.S_ISVTX
+    if mode & (special | stat.S_IWOTH):
+        raise LauncherError("skipped; trusted path permissions are unsafe")
+    if mode & stat.S_IWGRP and not private_group:
+        raise LauncherError("skipped; trusted path group is not private")
+    if not directory and not mode & (stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH):
+        raise LauncherError("skipped; trusted pj is not executable")
+
+
+def validate_owned_tree(
+    home: Path,
+    target: Path,
+    entry: pwd.struct_passwd,
+    *,
+    final_directory: bool,
+    private_group: bool,
+) -> None:
+    try:
+        relative = target.relative_to(home)
+    except ValueError as exc:
+        raise LauncherError("skipped; resolved pj is outside canonical home") from exc
+    reject_symlink_components(target)
+    validate_owned_component(home, entry, directory=True, private_group=private_group)
+    current = home
+    for index, component in enumerate(relative.parts):
+        current /= component
+        validate_owned_component(
+            current,
+            entry,
+            directory=final_directory or index < len(relative.parts) - 1,
+            private_group=private_group,
+        )
+
+
+def validate_node_binary() -> None:
+    try:
+        information = NODE_BINARY.lstat()
+    except OSError as exc:
+        raise LauncherError("skipped; fixed node runtime is unavailable") from exc
+    mode = stat.S_IMODE(information.st_mode)
+    special = stat.S_ISUID | stat.S_ISGID | stat.S_ISVTX
+    if (
+        stat.S_ISLNK(information.st_mode)
+        or not stat.S_ISREG(information.st_mode)
+        or information.st_uid != 0
+        or mode & (special | stat.S_IWGRP | stat.S_IWOTH)
+        or not mode & (stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+    ):
+        raise LauncherError("skipped; fixed node runtime is unsafe")
+
+
+def resolve_launcher(entry: pwd.struct_passwd) -> Path:
+    home = Path(entry.pw_dir)
+    launcher = home / ".local" / "bin" / "pj"
+    private_group = private_primary_group(entry)
+    reject_symlink_components(launcher.parent)
+    validate_owned_tree(
+        home,
+        launcher.parent,
+        entry,
+        final_directory=True,
+        private_group=private_group,
+    )
+    try:
+        resolved = launcher.resolve(strict=True)
+    except OSError as exc:
+        raise LauncherError("skipped; trusted pj launcher cannot be resolved") from exc
+    validate_owned_tree(
+        home,
+        resolved,
+        entry,
+        final_directory=False,
+        private_group=private_group,
+    )
+    return resolved
+
+
+def sanitized_environment(entry: pwd.struct_passwd) -> dict[str, str]:
+    environment = {
+        "HOME": entry.pw_dir,
+        "USER": entry.pw_name,
+        "LOGNAME": entry.pw_name,
+        "PATH": "/usr/bin:/bin",
+        "LANG": "C.UTF-8",
+        "LC_ALL": "C.UTF-8",
+    }
+    authentication = os.environ.get(AUTH_VARIABLE)
+    if authentication is not None:
+        environment[AUTH_VARIABLE] = authentication
+    return environment
+
+
+def invoke(entry: pwd.struct_passwd, launcher: Path, payload: bytes) -> int:
+    process = subprocess.Popen(
+        [str(NODE_BINARY), str(launcher), "notebook", "hook", HOOK_EVENT],
+        stdin=subprocess.PIPE,
+        env=sanitized_environment(entry),
+        close_fds=True,
+        start_new_session=True,
+    )
+    try:
+        process.communicate(payload, timeout=CHILD_TIMEOUT_SECONDS)
+    except subprocess.TimeoutExpired:
+        try:
+            os.killpg(process.pid, signal.SIGKILL)
+        except ProcessLookupError:
+            pass
+        process.wait()
+        return fail_open("timed out; run pj notebook capture list")
+    if process.returncode != 0:
+        return fail_open("failed open; run pj notebook capture list")
+    return 0
+
+
+def main() -> int:
+    entry = canonical_identity()
+    validate_node_binary()
+    launcher = resolve_launcher(entry)
+    payload = sys.stdin.buffer.read(STREAM_LIMIT_BYTES)
+    if len(payload) > REQUEST_LIMIT_BYTES:
+        return fail_open("skipped; hook payload exceeds 1048576 bytes")
+    return invoke(entry, launcher, payload)
+
+
+if __name__ == "__main__":
+    try:
+        result = main()
+    except LauncherError as exc:
+        result = fail_open(str(exc))
+    except Exception:
+        result = fail_open("failed open; run pj notebook capture list")
+    raise SystemExit(result)