git-captains-log 0.7.2__tar.gz → 0.7.4__tar.gz

{git_captains_log-0.7.2 → git_captains_log-0.7.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: git-captains-log
-Version: 0.7.2
+Version: 0.7.4
 Summary: Automatically aggregate git commit messages daily into markdown logs
 Author: Captain's Log Team
 License-File: LICENSE
@@ -41,12 +41,17 @@ captains-log setup
 This will:
 - Create `~/.captains-log/` for configuration
 - Create `~/.git-hooks/` for global Git hooks
-- Install or update the `commit-msg` hook
+- Install or update the `commit-msg` validation dispatcher and `post-commit` logger
 - Configure `git config --global core.hooksPath ~/.git-hooks`
 - Create a default `~/.captains-log/config.yml` if it does not exist
 
 After that you can use `btw`, `wtf`, `wnext`, `stone`, and `captains-log` from anywhere in your shell.
 
+After upgrading an existing installation, run `captains-log setup` again to replace the
+old `commit-msg` logger and install `post-commit`. Logging runs in the background after
+the source commit exists, so each entry records that commit's SHA. Existing pre-commit
+validation wrappers are preserved.
+
 See [INSTALLATION.md](INSTALLATION.md) for more detailed installation and configuration examples.
 
 ### From Source (For Development)
@@ -102,7 +107,7 @@ projects:
 
 #### Private Repositories
 
-Set `private: true` on a project to prevent its commits from appearing in the daily log. The commit-msg hook still runs but silently skips the logging step, so other features (`btw`, `wtf`, `wnext`, `stone`) remain available.
+Set `private: true` on a project to prevent its commits from appearing in the daily log. The post-commit hook still runs but skips the logging step, so other features (`btw`, `wtf`, `wnext`, `stone`) remain available.
 
 You can also set the `CAPTAINS_LOG_PRIVATE` environment variable to override the config value for the current shell session (useful in CI or per-repo `.envrc` files):
 
@@ -206,7 +211,10 @@ stone "Completed migration to new infrastructure"
 #### How They Work:
 - **Smart Project Detection**: Uses the same project detection logic as git commits
   - If you're in a configured project directory → logs to that project
-  - If not configured → uses the current directory name as project
+  - Clones and worktrees outside configured roots can still join the same project; see
+    [project grouping rules](docs/adr/0004-project-grouping-tolerates-pooled-worktrees.md)
+    for directory-name matching and equivalent HTTPS/SSH origin URLs
+  - Otherwise → uses the repository directory name as project
 - **Different Sections**:
   - `btw` entries appear in the "What I did" section under "## other"
   - `wtf` entries appear in the "What Broke or Got Weird" section
@@ -276,7 +284,25 @@ uv run pytest tests/ -v
 ### Hook not running
 - Make sure you've run `captains-log setup` and it completed successfully
 - Check that `git config --global core.hooksPath` points to `~/.git-hooks`
-- Verify the `commit-msg` file exists in `~/.git-hooks/` and is executable
+- Verify `post-commit` exists in `~/.git-hooks/` and is executable
+
+### Entries saved locally but not published
+
+- Inspect `~/.captains-log/update-log.log`: each processing line includes timestamp, run ID,
+  source repo, SHA, stage, and exit status. `Saved locally; NOT published` means the remote
+  has not received the entry; only `Published` confirms publication.
+- Inspect `~/.captains-log/pending/*.json` for durable failure details. `btw`, `wtf`, `wnext`,
+  and `stone` warn when pending runs exist and exit 1 with `Saved locally; NOT published`
+  if publishing their own entry fails. A log directory that is not a Git repository is a
+  normal local save.
+- The next successful automatic run stages the pending local Markdown files together and
+  clears saved-run markers for that destination. It also retries previously committed
+  entries whose push failed.
+- Git locks are retried briefly. Only unchanged regular locks at least 24 hours old with
+  a successful no-holder ownership check are removed automatically. Live or uncertain
+  locks remain for manual inspection; missing `lsof` disables automatic recovery.
+
+See the [publication behavior and migration specification](docs/specs/20261020-publication-reliability.md).
 
 ### Pre-commit integration issues
 - Ensure you ran `captains-log setup` before `captains-log install-precommit-hooks`

{git_captains_log-0.7.2 → git_captains_log-0.7.4}/README.md

@@ -30,12 +30,17 @@ captains-log setup
 This will:
 - Create `~/.captains-log/` for configuration
 - Create `~/.git-hooks/` for global Git hooks
-- Install or update the `commit-msg` hook
+- Install or update the `commit-msg` validation dispatcher and `post-commit` logger
 - Configure `git config --global core.hooksPath ~/.git-hooks`
 - Create a default `~/.captains-log/config.yml` if it does not exist
 
 After that you can use `btw`, `wtf`, `wnext`, `stone`, and `captains-log` from anywhere in your shell.
 
+After upgrading an existing installation, run `captains-log setup` again to replace the
+old `commit-msg` logger and install `post-commit`. Logging runs in the background after
+the source commit exists, so each entry records that commit's SHA. Existing pre-commit
+validation wrappers are preserved.
+
 See [INSTALLATION.md](INSTALLATION.md) for more detailed installation and configuration examples.
 
 ### From Source (For Development)
@@ -91,7 +96,7 @@ projects:
 
 #### Private Repositories
 
-Set `private: true` on a project to prevent its commits from appearing in the daily log. The commit-msg hook still runs but silently skips the logging step, so other features (`btw`, `wtf`, `wnext`, `stone`) remain available.
+Set `private: true` on a project to prevent its commits from appearing in the daily log. The post-commit hook still runs but skips the logging step, so other features (`btw`, `wtf`, `wnext`, `stone`) remain available.
 
 You can also set the `CAPTAINS_LOG_PRIVATE` environment variable to override the config value for the current shell session (useful in CI or per-repo `.envrc` files):
 
@@ -195,7 +200,10 @@ stone "Completed migration to new infrastructure"
 #### How They Work:
 - **Smart Project Detection**: Uses the same project detection logic as git commits
   - If you're in a configured project directory → logs to that project
-  - If not configured → uses the current directory name as project
+  - Clones and worktrees outside configured roots can still join the same project; see
+    [project grouping rules](docs/adr/0004-project-grouping-tolerates-pooled-worktrees.md)
+    for directory-name matching and equivalent HTTPS/SSH origin URLs
+  - Otherwise → uses the repository directory name as project
 - **Different Sections**:
   - `btw` entries appear in the "What I did" section under "## other"
   - `wtf` entries appear in the "What Broke or Got Weird" section
@@ -265,7 +273,25 @@ uv run pytest tests/ -v
 ### Hook not running
 - Make sure you've run `captains-log setup` and it completed successfully
 - Check that `git config --global core.hooksPath` points to `~/.git-hooks`
-- Verify the `commit-msg` file exists in `~/.git-hooks/` and is executable
+- Verify `post-commit` exists in `~/.git-hooks/` and is executable
+
+### Entries saved locally but not published
+
+- Inspect `~/.captains-log/update-log.log`: each processing line includes timestamp, run ID,
+  source repo, SHA, stage, and exit status. `Saved locally; NOT published` means the remote
+  has not received the entry; only `Published` confirms publication.
+- Inspect `~/.captains-log/pending/*.json` for durable failure details. `btw`, `wtf`, `wnext`,
+  and `stone` warn when pending runs exist and exit 1 with `Saved locally; NOT published`
+  if publishing their own entry fails. A log directory that is not a Git repository is a
+  normal local save.
+- The next successful automatic run stages the pending local Markdown files together and
+  clears saved-run markers for that destination. It also retries previously committed
+  entries whose push failed.
+- Git locks are retried briefly. Only unchanged regular locks at least 24 hours old with
+  a successful no-holder ownership check are removed automatically. Live or uncertain
+  locks remain for manual inspection; missing `lsof` disables automatic recovery.
+
+See the [publication behavior and migration specification](docs/specs/20261020-publication-reliability.md).
 
 ### Pre-commit integration issues
 - Ensure you ran `captains-log setup` before `captains-log install-precommit-hooks`

{git_captains_log-0.7.2 → git_captains_log-0.7.4}/docs/README.md

@@ -6,6 +6,7 @@ This repository uses a docs-as-code layout bootstrapped by [adrlane](https://git
 
 | Path | Purpose |
 | --- | --- |
+| `docs/architecture.md` | Current modules, entry points, and publication flow |
 | `docs/specs/` | Feature specifications, behavior, and contracts |
 | `docs/plans/` | Implementation plans derived from specs |
 | `docs/adr/` | Architecture and design decision records |

{git_captains_log-0.7.2 → git_captains_log-0.7.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "git-captains-log"
-version = "0.7.2"
+version = "0.7.4"
 # dynamic = ["version"]  # Temporarily disabled for release
 description = "Automatically aggregate git commit messages daily into markdown logs"
 authors = [

{git_captains_log-0.7.2 → git_captains_log-0.7.4}/src/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.7.2'
-__version_tuple__ = version_tuple = (0, 7, 2)
+__version__ = version = '0.7.4'
+__version_tuple__ = version_tuple = (0, 7, 4)
 
 __commit_id__ = commit_id = None

{git_captains_log-0.7.2 → git_captains_log-0.7.4}/src/btw.py

@@ -17,6 +17,7 @@ from src.entries import EntryProcessor
 from src.git import GitOperations
 from src.logs import LogManager
 from src.projects import ProjectFinder
+from src.publication import publish_manual_entry, warn_unpublished
 
 
 def add_manual_entry(entry_text: str):
@@ -26,6 +27,7 @@ def add_manual_entry(entry_text: str):
         entry_text: Text for the manual entry
     """
     # Load configuration
+    warn_unpublished()
     config = load_config()
 
     # Find project from current working directory
@@ -61,7 +63,10 @@ def add_manual_entry(entry_text: str):
         if log_info.has_git_repo:
             git_ops = GitOperations(log_info.log_repo_path)
             commit_message = f"Add manual entry to {project.name} logs for {date.today().isoformat()}"
-            git_ops.commit_and_push(commit_message)
+            if not publish_manual_entry(
+                git_ops, log_info.log_repo_path, commit_message
+            ):
+                sys.exit(1)
 
         cli_logging.success(f"Added entry to {project.name} log: {entry_text}")
     else:

{git_captains_log-0.7.2 → git_captains_log-0.7.4}/src/cli.py

@@ -5,6 +5,7 @@ Captain's Log CLI - Main command-line interface
 Provides setup and configuration commands for Captain's Log.
 """
 
+import shlex
 import subprocess
 import sys
 from pathlib import Path
@@ -13,33 +14,31 @@ from . import __version__, cli_logging
 
 
 def _render_commit_msg_hook(python_executable: str) -> str:
-    """Render commit-msg hook content using a specific Python interpreter.
+    """Keep commit-message validation separate from post-commit logging.
 
-    This avoids relying on `python3` from PATH (which may not have the
-    package installed, e.g. when `git-captains-log` is installed via pipx).
+    Re-running setup replaces the legacy logger while preserving installed
+    pre-commit validation wrappers. Captain's Log itself never vetoes a commit.
     """
-    # Use bash for compatibility with existing hook and common shells.
-    py = python_executable.replace('"', '\\"')
-    return f"""#!/bin/bash
-
-# Exit on any error
-set -e
-
-# Get repository information
-REPO_NAME=$(basename "$(git rev-parse --show-toplevel)")
-REPO_PATH=$(git rev-parse --show-toplevel)
-COMMIT_MSG=$(head -n1 "$1")
-
-# Get commit SHA (handle both pre-commit and post-commit scenarios)
-COMMIT_SHA=$(git rev-parse --verify HEAD 2>/dev/null || echo "no-sha")
-
-# Run the update script using the installed package
-export GIT_HOOK=1
-if ! "{py}" -m src.update_log "$REPO_NAME" "$REPO_PATH" "$COMMIT_SHA" "$COMMIT_MSG"; then
-    echo "Warning: Captain's Log update failed, but commit will continue"
-    echo "Check the script output above for errors"
-    exit 0  # Don't fail the commit
+    return """#!/bin/sh
+HOOKS_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+if [ -x "$HOOKS_DIR/commit-msg-precommit" ]; then
+    exec "$HOOKS_DIR/commit-msg-precommit" "$@"
 fi
+exit 0
+"""
+
+
+def _render_post_commit_hook(python_executable: str) -> str:
+    """Capture immutable commit details before starting the background publisher."""
+    return f"""#!/bin/sh
+REPO_PATH=$(git rev-parse --show-toplevel) || exit 0
+REPO_NAME=$(basename "$REPO_PATH")
+COMMIT_SHA=$(git rev-parse --verify HEAD) || exit 0
+COMMIT_MSG=$(git log -1 --format=%s "$COMMIT_SHA") || exit 0
+mkdir -p "$HOME/.captains-log" || exit 0
+# Diagnostics include the updater's exit status; publication never blocks Git.
+GIT_HOOK=1 {shlex.quote(python_executable)} -m src.update_log "$REPO_NAME" "$REPO_PATH" "$COMMIT_SHA" "$COMMIT_MSG" >> "$HOME/.captains-log/update-log.log" 2>&1 < /dev/null &
+exit 0
 """
 
 
@@ -72,8 +71,8 @@ def setup():
         print("  pip install git-captains-log")
         sys.exit(1)
 
-    # Install commit-msg hook
-    print("Installing Git commit-msg hook...")
+    # Migrate the legacy logger and install its post-commit replacement together.
+    print("Installing Git commit-msg dispatcher and post-commit logger...")
 
     # Hook templates ship inside the package (src/hooks/), so this works the
     # same way for an editable/source install and a real wheel install.
@@ -90,7 +89,13 @@ def setup():
         hook_content = _render_commit_msg_hook(sys.executable)
         commit_msg_dest.write_text(hook_content, encoding="utf-8")
         commit_msg_dest.chmod(0o755)
-        print(f"  ✓ Installed commit-msg hook to {commit_msg_dest}")
+        post_commit_dest = git_hooks_dir / "post-commit"
+        post_commit_dest.write_text(
+            _render_post_commit_hook(sys.executable), encoding="utf-8"
+        )
+        post_commit_dest.chmod(0o755)
+        print(f"  ✓ Updated commit-msg dispatcher at {commit_msg_dest}")
+        print(f"  ✓ Installed post-commit logger to {post_commit_dest}")
     else:
         print("  ⚠ Warning: commit-msg hook not found in package")
         print("    You may need to copy it manually from the repository")
@@ -195,36 +200,7 @@ fi
 exit 0
 """
 
-    python_executable = sys.executable.replace('"', '\\"')
-
-    captains_log = f"""#!/usr/bin/env sh
-
-# Captain's Log commit-msg dispatcher
-# Behavior:
-# - If commit-msg-precommit exists: run pre-commit first
-# - Always run Captain's Log hook afterwards using the current interpreter
-
-set -eu
-
-HOOKS_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
-PRECOMMIT_WRAPPER="$HOOKS_DIR/commit-msg-precommit"
-
-# 1) Run pre-commit wrapper if present
-if [ -x "$PRECOMMIT_WRAPPER" ]; then
-  "$PRECOMMIT_WRAPPER" "$@"
-fi
-
-# 2) Run Captain's Log update via installed package
-REPO_NAME=$(basename "$(git rev-parse --show-toplevel)")
-REPO_PATH=$(git rev-parse --show-toplevel)
-COMMIT_MSG=$(head -n1 "$1")
-COMMIT_SHA=$(git rev-parse --verify HEAD 2>/dev/null || echo "no-sha")
-
-export GIT_HOOK=1
-exec "{python_executable}" -m src.update_log "$REPO_NAME" "$REPO_PATH" "$COMMIT_SHA" "$COMMIT_MSG"
-
-exit 0
-"""
+    captains_log = _render_commit_msg_hook(sys.executable)
 
     pre_push = """#!/usr/bin/env sh
 
@@ -239,6 +215,7 @@ exit 0
     write_hook("pre-commit", pre_commit)
     write_hook("commit-msg-precommit", commit_msg_precommit)
     write_hook("commit-msg", captains_log)
+    write_hook("post-commit", _render_post_commit_hook(sys.executable))
     write_hook("pre-push", pre_push)
 
     # Set global git hooks path
@@ -268,9 +245,7 @@ exit 0
 
     print("\nDone. pre-commit wrappers are installed globally.")
     print("- They run pre-commit in repos with .pre-commit-config.yaml")
-    print(
-        "- The commit-msg wrapper will also run Captain's Log if installed at ~/.captains-log"
-    )
+    print("- Captain's Log publishes asynchronously from post-commit")
 
 
 def main():

{git_captains_log-0.7.2 → git_captains_log-0.7.4}/src/git/git_operations.py

@@ -1,7 +1,10 @@
 """Git operations for Captain's Log."""
 
 import os
+import shutil
+import stat
 import subprocess
+import time
 from pathlib import Path
 
 # Git points these at the invoking repository (and, from a worktree, at its
@@ -23,6 +26,9 @@ class GitOperations:
 
     # How many times to pull-and-retry a rejected push before giving up.
     MAX_PUSH_RETRIES = 3
+    LOCK_RETRIES = 5
+    LOCK_RETRY_DELAY = 0.2
+    STALE_LOCK_SECONDS = 24 * 60 * 60
 
     # Git attribute that makes concurrent same-section appends to the log's
     # markdown files merge cleanly (keep every unique line from both sides)
@@ -37,6 +43,84 @@ class GitOperations:
             repo_path: Path to the git repository
         """
         self.repo_path = repo_path
+        self.stage = "lock"
+        self.status_failed = False
+
+    def _git_directories(self):
+        """Resolve ordinary and linked-worktree metadata without inherited env."""
+        git_dir = self.repo_path / ".git"
+        if git_dir.is_file():
+            value = git_dir.read_text(encoding="utf-8").strip()
+            if not value.startswith("gitdir: "):
+                raise ValueError(f"Unrecognized Git directory: {git_dir}")
+            git_dir = (self.repo_path / value[8:]).resolve()
+        directories = [git_dir]
+        common = git_dir / "commondir"
+        if common.is_file():
+            directories.append((git_dir / common.read_text().strip()).resolve())
+        return directories
+
+    def _lock_files(self):
+        return [
+            path
+            for directory in self._git_directories()
+            for path in directory.glob("*.lock")
+        ]
+
+    def _recover_abandoned_lock(self, path):
+        """Fail closed unless an old, unchanged regular lock has no open owner.
+
+        lsof works on macOS and Linux. Missing tools, unsupported platforms,
+        inspection errors, symlinks, and changing files all require manual action.
+        """
+        try:
+            before = path.lstat()
+            if (
+                not stat.S_ISREG(before.st_mode)
+                or time.time() - max(before.st_mtime, before.st_ctime)
+                < self.STALE_LOCK_SECONDS
+            ):
+                return False
+            lsof = shutil.which("lsof") if os.name == "posix" else None
+            if lsof is None:
+                return False
+            result = subprocess.run(
+                [lsof, "-t", str(path.resolve())],
+                capture_output=True,
+                text=True,
+                timeout=2,
+            )
+            # lsof's documented no-match result: status 1, no output or errors.
+            if result.returncode != 1 or result.stdout.strip() or result.stderr.strip():
+                return False
+            if path.lstat() != before:
+                return False
+            path.unlink()
+            print(
+                f"Recovered abandoned Git lock: {path}; publishing pending local entries"
+            )
+            return True
+        except FileNotFoundError:
+            return True  # The owning Git process removed it while we waited.
+        except (OSError, subprocess.TimeoutExpired):
+            return False
+
+    def wait_for_locks(self):
+        """Briefly wait for active Git operations, then recover only proven stale locks."""
+        self.stage = "lock"
+        for attempt in range(self.LOCK_RETRIES + 1):
+            locks = self._lock_files()
+            if not locks:
+                return True
+            if attempt < self.LOCK_RETRIES:
+                time.sleep(self.LOCK_RETRY_DELAY)
+        for path in locks:
+            self._recover_abandoned_lock(path)
+        remaining = self._lock_files()
+        if remaining:
+            print(f"Warning: Git locks remain; publication blocked: {remaining}")
+            return False
+        return True
 
     def _run_git(self, args: list, **kwargs) -> subprocess.CompletedProcess:
         """Run a git command scoped to repo_path, immune to inherited repo env vars.
@@ -57,6 +141,7 @@ class GitOperations:
         Returns:
             True if there are changes, False otherwise
         """
+        self.status_failed = False
         try:
             result = self._run_git(
                 ["-C", str(self.repo_path), "status", "--porcelain"],
@@ -66,6 +151,7 @@ class GitOperations:
             )
             return bool(result.stdout.strip())
         except subprocess.CalledProcessError:
+            self.status_failed = True
             return False
 
     def has_lock_files(self) -> bool:
@@ -74,12 +160,7 @@ class GitOperations:
         Returns:
             True if lock files exist, False otherwise
         """
-        git_dir = self.repo_path / ".git"
-        if not git_dir.exists():
-            return False
-
-        lock_files = list(git_dir.glob("*.lock"))
-        return len(lock_files) > 0
+        return bool(self._lock_files())
 
     def add_file(self, file_path: Path) -> bool:
         """Add a file to the git staging area.
@@ -369,30 +450,34 @@ class GitOperations:
         """
         try:
             # Check for lock files
-            if self.has_lock_files():
-                print("Warning: Git lock files found, skipping operations")
+            if not self.wait_for_locks():
                 return False
 
+            self.stage = "add"
             self.ensure_merge_driver()
 
             # Check if there are any changes to commit
-            if not self.has_changes():
-                print("No changes to commit, skipping git operations")
-                return True
-
-            # Add all changes
-            if not self.add_all():
-                print("Warning: Failed to add files to git")
-                return False
-
-            # Commit
-            if not self.commit(commit_message):
-                print("Warning: Failed to commit changes")
+            self.stage = "status"
+            has_changes = self.has_changes()
+            if self.status_failed:
+                print("Warning: Failed to inspect Git status")
                 return False
+            if has_changes:
+                # Include entries left by earlier failed runs in the same commit.
+                self.stage = "add"
+                if not self.add_all():
+                    print("Warning: Failed to add files to git")
+                    return False
+                self.stage = "commit"
+                if not self.commit(commit_message):
+                    print("Warning: Failed to commit changes")
+                    return False
 
             # Push, retrying with a pull in between if the remote moved on
+            # A clean worktree can still have commits from an earlier failed push.
+            self.stage = "push"
             if self.push():
-                print("Successfully committed and pushed log updates")
+                print("Successfully published log updates")
                 return True
 
             for attempt in range(1, self.MAX_PUSH_RETRIES + 1):
@@ -400,9 +485,12 @@ class GitOperations:
                     f"Warning: Push rejected, pulling and retrying "
                     f"({attempt}/{self.MAX_PUSH_RETRIES})..."
                 )
-                self.pull()
+                self.stage = "pull"
+                if self.pull() is False:
+                    return False
+                self.stage = "push"
                 if self.push():
-                    print("Successfully committed and pushed log updates")
+                    print("Successfully published log updates")
                     return True
 
             print("Warning: Failed to push changes")

git_captains_log-0.7.4/src/hooks/commit-msg

@@ -0,0 +1,8 @@
+#!/bin/sh
+# Compatibility dispatcher. Install post-commit alongside this hook for logging.
+# Run captains-log setup after upgrading to replace the legacy commit-msg logger.
+HOOKS_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+if [ -x "$HOOKS_DIR/commit-msg-precommit" ]; then
+    exec "$HOOKS_DIR/commit-msg-precommit" "$@"
+fi
+exit 0

git_captains_log-0.7.4/src/hooks/commit-msg-package

@@ -0,0 +1,8 @@
+#!/bin/sh
+# Compatibility dispatcher. Install post-commit alongside this hook for logging.
+# Run captains-log setup after upgrading to replace the legacy commit-msg logger.
+HOOKS_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+if [ -x "$HOOKS_DIR/commit-msg-precommit" ]; then
+    exec "$HOOKS_DIR/commit-msg-precommit" "$@"
+fi
+exit 0

git_captains_log-0.7.4/src/hooks/post-commit

@@ -0,0 +1,10 @@
+#!/bin/sh
+REPO_PATH=$(git rev-parse --show-toplevel) || exit 0
+REPO_NAME=$(basename "$REPO_PATH")
+COMMIT_SHA=$(git rev-parse --verify HEAD) || exit 0
+COMMIT_MSG=$(git log -1 --format=%s "$COMMIT_SHA") || exit 0
+mkdir -p "$HOME/.captains-log" || exit 0
+export PYTHONPATH="$HOME/.captains-log:$PYTHONPATH"
+# Diagnostics include the updater's exit status; publication never blocks Git.
+GIT_HOOK=1 python3 -m src.update_log "$REPO_NAME" "$REPO_PATH" "$COMMIT_SHA" "$COMMIT_MSG" >> "$HOME/.captains-log/update-log.log" 2>&1 < /dev/null &
+exit 0

git_captains_log-0.7.4/src/hooks/post-commit-package

@@ -0,0 +1,9 @@
+#!/bin/sh
+REPO_PATH=$(git rev-parse --show-toplevel) || exit 0
+REPO_NAME=$(basename "$REPO_PATH")
+COMMIT_SHA=$(git rev-parse --verify HEAD) || exit 0
+COMMIT_MSG=$(git log -1 --format=%s "$COMMIT_SHA") || exit 0
+mkdir -p "$HOME/.captains-log" || exit 0
+# Diagnostics include the updater's exit status; publication never blocks Git.
+GIT_HOOK=1 python3 -m src.update_log "$REPO_NAME" "$REPO_PATH" "$COMMIT_SHA" "$COMMIT_MSG" >> "$HOME/.captains-log/update-log.log" 2>&1 < /dev/null &
+exit 0

{git_captains_log-0.7.2 → git_captains_log-0.7.4}/src/projects/project_finder.py

@@ -1,12 +1,35 @@
 """Project discovery functionality for Captain's Log."""
 
 import configparser
+import re
 from pathlib import Path
 from typing import Optional
 
 from src.config.config_models import Config, ProjectConfig
 from src.projects.project_models import ProjectInfo
 
+_REMOTE_URL = re.compile(
+    r"(?:https?://|ssh://git@)(?P<host>[A-Za-z0-9.-]+)/"
+    r"(?P<path>[^/\s:?#@]+/[^/\s:?#@]+?)(?:\.git)?(?P<slash>/?)"
+)
+_SCP_LIKE_REMOTE = re.compile(
+    r"git@(?P<host>[A-Za-z0-9.-]+):"
+    r"(?P<path>[^/\s:?#@]+/[^/\s:?#@]+?)(?:\.git)?"
+)
+
+
+def normalize_remote_url(url: str) -> tuple[str, str]:
+    """Canonicalize approved remote forms, retaining raw text for all others.
+
+    Only credential-free HTTP(S), git-user SSH without ports, and git-user
+    SCP forms are canonicalized. Host case is ignored; path case is preserved.
+    Only HTTP(S) forms accept a trailing slash.
+    """
+    match = _REMOTE_URL.fullmatch(url) or _SCP_LIKE_REMOTE.fullmatch(url)
+    if match is None or (url.startswith("ssh://") and match.group("slash")):
+        return "raw", url
+    return "canonical", f"{match.group('host').lower()}/{match.group('path')}"
+
 
 class ProjectFinder:
     """Handles finding and identifying projects from repository paths."""
@@ -87,7 +110,7 @@ class ProjectFinder:
         if remote_a is None or remote_b is None:
             return True
 
-        return remote_a == remote_b
+        return normalize_remote_url(remote_a) == normalize_remote_url(remote_b)
 
     def _git_remote_url(self, repo: Path) -> Optional[str]:
         """Read the "origin" remote URL from a repo's git config, if any.

git_captains_log-0.7.4/src/publication.py

@@ -0,0 +1,132 @@
+"""Correlated run diagnostics and durable records of unpublished local logs."""
+
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from uuid import uuid4
+
+from src import cli_logging
+
+
+def timestamp():
+    return datetime.now(timezone.utc).isoformat()
+
+
+def pending_directory():
+    return Path.home() / ".captains-log" / "pending"
+
+
+def warn_unpublished():
+    """Surface background failures even when this command uses another log repo."""
+    records = list(pending_directory().glob("*.json"))
+    if records:
+        cli_logging.warning(
+            f"Warning: {len(records)} unpublished Captain's Log run(s). "
+            f"Inspect {pending_directory()} and ~/.captains-log/update-log.log"
+        )
+
+
+class PublicationRun:
+    """One run's diagnostic context and pending-state lifecycle.
+
+    Each run has its own marker. Successful publication clears only the snapshot
+    of older saved runs for this destination; a concurrent new run stays pending.
+    """
+
+    def __init__(self, repo, sha):
+        self.run_id = uuid4().hex
+        self.repo = repo
+        self.sha = sha
+        self.stage = "config"
+        self.git_ops = None
+        self.exit_status = "running"
+        self.stream = sys.stdout
+        self.buffer = ""
+        self.marker = pending_directory() / f"{self.run_id}.json"
+        self.record = {}
+        self.older = []
+
+    @property
+    def current_stage(self):
+        return self.git_ops.stage if self.git_ops is not None else self.stage
+
+    def write(self, value):
+        """Prefix every diagnostic line, including multiline Git errors."""
+        self.buffer += value
+        while "\n" in self.buffer:
+            line, self.buffer = self.buffer.split("\n", 1)
+            if line:
+                self.stream.write(
+                    f"timestamp={timestamp()} run={self.run_id} "
+                    f"repo={json.dumps(self.repo)} sha={json.dumps(self.sha)} "
+                    f"stage={self.current_stage} exit_status={self.exit_status} {line}\n"
+                )
+        self.stream.flush()
+        return len(value)
+
+    def flush(self):
+        if self.buffer:
+            self.write("\n")
+        self.stream.flush()
+
+    def isatty(self):
+        return False
+
+    def start_pending(self, log_repo, log_file):
+        destination = str(log_repo.resolve()) if log_repo else None
+        for path in pending_directory().glob("*.json"):
+            try:
+                data = json.loads(path.read_text(encoding="utf-8"))
+                if (
+                    isinstance(data, dict)
+                    and data.get("log_repo") == destination
+                    and data.get("saved_locally")
+                ):
+                    self.older.append(path)
+            except (OSError, ValueError):
+                continue  # Keep malformed records for inspection.
+        self.record = {
+            "run": self.run_id,
+            "repo": self.repo,
+            "sha": self.sha,
+            "log_repo": destination,
+            "log_file": str(log_file) if log_file else None,
+            "saved_locally": False,
+        }
+        self.update_pending()
+
+    def update_pending(self, **values):
+        self.record.update(
+            values,
+            timestamp=timestamp(),
+            stage=self.current_stage,
+            exit_status=self.exit_status,
+        )
+        self.marker.parent.mkdir(parents=True, exist_ok=True)
+        temporary = self.marker.with_suffix(".tmp")
+        temporary.write_text(json.dumps(self.record, indent=2) + "\n", encoding="utf-8")
+        temporary.replace(self.marker)
+
+    def published(self):
+        for path in [*self.older, self.marker]:
+            try:
+                path.unlink()
+            except FileNotFoundError:
+                pass
+            except OSError as exc:
+                print(f"Published, but could not clear pending record {path}: {exc}")
+
+
+def publish_manual_entry(git_ops, log_repo, commit_message):
+    """Publish a manual entry; on failure keep a pending marker and return False."""
+    run = PublicationRun("manual", "manual")
+    run.start_pending(log_repo, None)
+    if git_ops.commit_and_push(commit_message):
+        run.published()
+        return True
+    run.stage = git_ops.stage
+    run.exit_status = 1
+    run.update_pending(saved_locally=True)
+    cli_logging.error(f"Saved locally; NOT published; pending={run.marker}")
+    return False

{git_captains_log-0.7.2 → git_captains_log-0.7.4}/src/stone.py

@@ -21,6 +21,7 @@ from src.config import Config, load_config
 from src.git import GitOperations
 from src.logs.log_manager import LogManager
 from src.projects import ProjectFinder, ProjectInfo
+from src.publication import publish_manual_entry, warn_unpublished
 
 EMOJIS: list[str] = ["🎯", "🏆", "🚀", "⭐️", "🎉", "📌"]
 
@@ -115,6 +116,7 @@ def build_milestone_context(config: Config, project: ProjectInfo) -> MilestoneCo
 
 def add_milestone_entry(entry_text: str) -> None:
     """High-level API to add a milestone entry for the current project."""
+    warn_unpublished()
     config, project = resolve_project()
 
     # Pull remote changes before deciding where the entry goes, since the
@@ -137,7 +139,8 @@ def add_milestone_entry(entry_text: str) -> None:
         commit_message = (
             f"Add milestone entry to {ctx.project.name} for {ctx.log_date.year}"
         )
-        git_ops.commit_and_push(commit_message)
+        if not publish_manual_entry(git_ops, log_repo_path, commit_message):
+            raise SystemExit(1)
 
 
 def main() -> None:

{git_captains_log-0.7.2 → git_captains_log-0.7.4}/src/update_log.py

@@ -6,6 +6,7 @@ This script processes git commit information and updates daily log files.
 """
 
 import sys
+from contextlib import redirect_stderr, redirect_stdout
 from datetime import date
 from pathlib import Path
 
@@ -16,6 +17,7 @@ from src.entries import EntryProcessor
 from src.git import CommitParser, GitOperations
 from src.logs import LogManager
 from src.projects import ProjectFinder
+from src.publication import PublicationRun
 
 
 # Backward compatibility exports for existing tests
@@ -68,7 +70,7 @@ def save_log(file_path, repos):
 def commit_and_push(log_repo_path, commit_msg):
     """Legacy function for backward compatibility."""
     git_ops = GitOperations(log_repo_path)
-    git_ops.commit_and_push(commit_msg)
+    return git_ops.commit_and_push(commit_msg)
 
 
 def get_log_repo_and_path(project, config):
@@ -101,8 +103,7 @@ def main():
     try:
         args, log_level = cli_logging.split_log_level_args(sys.argv[1:])
     except ValueError as exc:
-        cli_logging.error(str(exc))
-        sys.exit(0)
+        _argument_error(str(exc))
     cli_logging.configure_log_level(log_level)
 
     # Check for version flag
@@ -113,22 +114,39 @@ def main():
         sys.exit(0)
 
     if len(args) < 4:
-        print(
+        _argument_error(
             "Usage: update_log.py [--log-level compact|verbose|debug] "
             "<repo_name> <repo_path> <commit_sha> <commit_message>"
         )
-        return
 
     repo_name = args[0]
     repo_path = args[1]
     commit_sha = args[2]
     commit_msg = args[3]
 
+    run = PublicationRun(repo_name, commit_sha)
+    with redirect_stdout(run), redirect_stderr(run):
+        status = _update(repo_name, repo_path, commit_sha, commit_msg, run)
+        run.exit_status = status
+        print(f"Run finished with exit_status={status}")
+        run.flush()
+    if status:
+        raise SystemExit(status)
+
+
+def _argument_error(message):
+    run = PublicationRun("unknown", "unknown")
+    run.stage = "arguments"
+    run.exit_status = 2
+    with redirect_stdout(run):
+        print(message)
+    raise SystemExit(2)
+
+
+def _update(repo_name, repo_path, commit_sha, commit_msg, run):
+    saved = False
     try:
-        # Load configuration
         config = load_config()
-
-        # Check if we should skip this commit
         if CommitParser.should_skip_commit(
             commit_sha,
             repo_path,
@@ -138,66 +156,81 @@ def main():
                 print("Skipping log update: No valid commit SHA")
             else:
                 print("Skipping log update: Running from within log repository")
-            return
-
-        # Find project information
-        project_finder = ProjectFinder(config)
-        project = project_finder.find_project(repo_path)
+            return 0
 
+        run.stage = "project"
+        project = ProjectFinder(config).find_project(repo_path)
         if project.is_private:
             print("Skipping log update: repository is private")
-            return
+            return 0
 
-        # Get log file information
         log_manager = LogManager(config)
         log_info = log_manager.get_log_file_info(project)
-
-        # Pull remote changes before reading the log, so a push made from
-        # another machine (or directly on GitHub) is already reflected in
-        # what we load and merge into below.
+        # A project-specific log repo also needs the recursion guard.
+        if (
+            log_info.log_repo_path
+            and Path(repo_path).resolve() == log_info.log_repo_path.resolve()
+        ):
+            print("Skipping log update: Running from within log repository")
+            return 0
+        git_ops = None
         if log_info.has_git_repo and log_info.log_repo_path:
-            GitOperations(log_info.log_repo_path).pull()
-
-        # Load existing log data
+            run.start_pending(log_info.log_repo_path, log_info.file_path)
+            git_ops = GitOperations(log_info.log_repo_path)
+            run.git_ops = git_ops
+            if git_ops.wait_for_locks():
+                git_ops.stage = "pull"
+                git_ops.pull()
+            # A failed pull must not prevent saving the source entry locally.
+            # commit_and_push will expose a failed publication (or recover later).
+            run.git_ops = None
+
+        run.stage = "read"
         log_data = log_manager.load_log(log_info)
-
-        # Process the new commit entry
-        entry_processor = EntryProcessor()
-
-        # Get or create repository entries
-        repo_entries = log_data.get_repo_entries(repo_name)
-
-        # Update with new commit
-        updated_entries = entry_processor.update_commit_entries(
-            repo_entries, commit_sha, commit_msg
+        processor = EntryProcessor()
+        updated = processor.update_commit_entries(
+            log_data.get_repo_entries(repo_name),
+            commit_sha,
+            commit_msg,
         )
-
-        # Update log data
-        log_data.set_repo_entries(repo_name, updated_entries)
-
-        # Save the updated log
+        log_data.set_repo_entries(repo_name, updated)
+        run.stage = "save"
         log_manager.save_log(log_info, log_data)
-
-        # Commit and push all changes if we have a git repository
-        if log_info.has_git_repo and log_info.log_repo_path:
-            git_ops = GitOperations(log_info.log_repo_path)
-            commit_message = (
-                f"Update {project.name} logs for {date.today().isoformat()}"
-            )
-            git_ops.commit_and_push(commit_message)
-
-        print(f"Updated log for {repo_name} in project {project.name}")
-        cli_logging.debug(
-            f"Debug details: repo={repo_name}, repo_path={repo_path}, sha={commit_sha}"
-        )
-
-    except Exception as e:
-        print(f"Error updating log: {e}")
-        cli_logging.debug(
-            f"Debug context: repo={repo_name}, path={repo_path}, sha={commit_sha}"
+        saved = True
+        print(f"Saved locally for {repo_name} in project {project.name}")
+
+        if git_ops is None:
+            return 0
+
+        run.update_pending(saved_locally=True)
+        run.git_ops = git_ops
+        commit_message = f"Update {project.name} logs for {date.today().isoformat()}"
+        if not git_ops.commit_and_push(commit_message):
+            run.exit_status = 1
+            run.update_pending()
+            print(f"Saved locally; NOT published; pending={run.marker}")
+            return 1
+
+        run.exit_status = 0
+        run.published()
+        print(f"Published log for {repo_name} in project {project.name}")
+        return 0
+    except Exception as exc:
+        run.exit_status = 1
+        print(f"Error updating log: {exc}")
+        if not run.record:
+            run.record = {"run": run.run_id, "repo": repo_name, "sha": commit_sha}
+        if run.record:
+            try:
+                run.update_pending(saved_locally=saved, error=str(exc))
+            except OSError as marker_error:
+                print(f"Error recording pending publication: {marker_error}")
+        print(
+            "Saved locally; NOT published"
+            if saved
+            else "Log update failed before local save"
         )
-        # Don't exit with error code to avoid breaking git operations
-        sys.exit(0)
+        return 1
 
 
 if __name__ == "__main__":

{git_captains_log-0.7.2 → git_captains_log-0.7.4}/src/wnext.py

@@ -19,10 +19,12 @@ from src.entries import EntryProcessor
 from src.git import GitOperations
 from src.logs import LogManager
 from src.projects import ProjectFinder
+from src.publication import publish_manual_entry, warn_unpublished
 
 
 def add_what_next_entry(entry_text: str, project_name: Optional[str], use_other: bool):
     """Add an entry to the 'Whats next' section."""
+    warn_unpublished()
     config = load_config()
 
     project_finder = ProjectFinder(config)
@@ -104,7 +106,10 @@ def add_what_next_entry(entry_text: str, project_name: Optional[str], use_other:
         if log_info.has_git_repo and log_info.log_repo_path:
             git_ops = GitOperations(log_info.log_repo_path)
             commit_message = f"Add What Next entry to {project.name} logs for {date.today().isoformat()}"
-            git_ops.commit_and_push(commit_message)
+            if not publish_manual_entry(
+                git_ops, log_info.log_repo_path, commit_message
+            ):
+                sys.exit(1)
 
         cli_logging.success(
             f"Added 'Whats next' entry to {project.name} "

{git_captains_log-0.7.2 → git_captains_log-0.7.4}/src/wtf.py

@@ -17,6 +17,7 @@ from src.entries import EntryProcessor
 from src.git import GitOperations
 from src.logs import LogManager
 from src.projects import ProjectFinder
+from src.publication import publish_manual_entry, warn_unpublished
 
 
 def add_wtf_entry(entry_text: str):
@@ -26,6 +27,7 @@ def add_wtf_entry(entry_text: str):
         entry_text: Text for the wtf entry
     """
     # Load configuration
+    warn_unpublished()
     config = load_config()
 
     # Find project from current working directory
@@ -67,7 +69,10 @@ def add_wtf_entry(entry_text: str):
             commit_message = (
                 f"Add WTF entry to {project.name} logs for {date.today().isoformat()}"
             )
-            git_ops.commit_and_push(commit_message)
+            if not publish_manual_entry(
+                git_ops, log_info.log_repo_path, commit_message
+            ):
+                sys.exit(1)
 
         cli_logging.success(f"Added WTF entry to {project.name} log: {entry_text}")
     else:

git_captains_log-0.7.2/src/hooks/commit-msg

@@ -1,31 +0,0 @@
-#!/bin/bash
-
-# Exit on any error
-set -e
-
-# Get repository information
-REPO_NAME=$(basename "$(git rev-parse --show-toplevel)")
-REPO_PATH=$(git rev-parse --show-toplevel)
-COMMIT_MSG=$(head -n1 "$1")
-
-# Get commit SHA (handle both pre-commit and post-commit scenarios)
-COMMIT_SHA=$(git rev-parse --verify HEAD 2>/dev/null || echo "no-sha")
-
-# Path to the update script
-SCRIPT_PATH="$HOME/.captains-log/src/update_log.py"
-
-# Check if script exists
-if [ ! -f "$SCRIPT_PATH" ]; then
-    echo "Warning: Captain's Log script not found at $SCRIPT_PATH"
-    echo "Please run the install script or check your installation."
-    exit 0  # Don't fail the commit
-fi
-
-# Run the update script
-export GIT_HOOK=1
-export PYTHONPATH="$HOME/.captains-log:$PYTHONPATH"
-if ! python3 "$SCRIPT_PATH" "$REPO_NAME" "$REPO_PATH" "$COMMIT_SHA" "$COMMIT_MSG"; then
-    echo "Warning: Captain's Log update failed, but commit will continue"
-    echo "Check the script output above for errors"
-    exit 0  # Don't fail the commit
-fi

git_captains_log-0.7.2/src/hooks/commit-msg-package

@@ -1,21 +0,0 @@
-#!/bin/bash
-
-# Exit on any error
-set -e
-
-# Get repository information
-REPO_NAME=$(basename "$(git rev-parse --show-toplevel)")
-REPO_PATH=$(git rev-parse --show-toplevel)
-COMMIT_MSG=$(head -n1 "$1")
-
-# Get commit SHA (handle both pre-commit and post-commit scenarios)
-COMMIT_SHA=$(git rev-parse --verify HEAD 2>/dev/null || echo "no-sha")
-
-# Run the update script using the installed package
-export GIT_HOOK=1
-if ! python3 -m src.update_log "$REPO_NAME" "$REPO_PATH" "$COMMIT_SHA" "$COMMIT_MSG"; then
-    echo "Warning: Captain's Log update failed, but commit will continue"
-    echo "Check the script output above for errors"
-    exit 0  # Don't fail the commit
-fi
-