git-stint 0.2.4 → 0.3.1

package/README.md

@@ -96,7 +96,7 @@ git stint end
 | `git stint squash -m "msg"` | Collapse all commits into one |
 | `git stint merge` | Merge session into current branch (no PR) |
 | `git stint pr [--title "..."]` | Push branch and create GitHub PR |
-| `git stint end` | Finalize session, clean up everything |
+| `git stint end` | Finalize session, clean up everything (deletes remote branch if merged) |
 | `git stint abort` | Discard session — delete all changes |
 | `git stint undo` | Revert last commit, changes become pending |
 | `git stint conflicts` | Check file overlap with other sessions |
@@ -346,6 +346,7 @@ Combined testing creates a temporary octopus merge of the specified sessions, ru
 - **`execFileSync` everywhere** — array arguments prevent shell injection. No `execSync` with string interpolation.
 - **Atomic manifest writes** — write to `.tmp`, then `rename()`. Crash-safe.
 - **Symlinks for shared data** — gitignored dirs (caches, data) symlink into worktrees instead of being copied or lost.
+- **Safe remote branch cleanup** — on `end`/`merge`, deletes the remote branch only when all changes are verified merged **on the remote**. Checks against remote tracking refs (`origin/main`), not local branches — so a local-only merge won't delete the remote branch until you push. Uses a two-tier check (commit ancestry + content diff) that handles regular merges, squash merges, and rebase merges. Unmerged branches are always preserved with a warning.
 - **Zero runtime dependencies** — only Node.js built-ins. Dev deps are TypeScript and @types/node.
 
 ## git-stint vs GitButler

package/adapters/claude-code/hooks/git-stint-hook-pre-tool

@@ -152,7 +152,8 @@ if [ "$MAIN_BRANCH_POLICY" = "prompt" ]; then
   fi
   echo "BLOCKED: Writing to main branch." >&2
   echo "To allow, run: git stint allow-main --client-id $CLIENT_ID" >&2
-  echo "To create a session instead, run: git stint start <name>" >&2
+  echo "To create a session instead, run: git stint start <descriptive-name>" >&2
+  echo "  (pick a short name that describes your task, e.g. fix-auth-refresh, add-user-search)" >&2
   exit 2
 fi
 

package/dist/git.d.ts

@@ -20,6 +20,16 @@ export declare function deleteBranch(name: string): void;
  */
 export declare function remoteBranchExists(name: string): boolean;
 export declare function deleteRemoteBranch(name: string): void;
+/**
+ * Check if all changes from `branch` are present in `into`.
+ * Handles regular merges, squash merges, and rebase merges.
+ *
+ * 1. Fast path: branch tip is an ancestor of `into` (regular merge / ff).
+ * 2. Content check: every file the branch changed has identical content in
+ *    `into`. This catches squash and rebase merges where SHAs differ but
+ *    the content is the same.
+ */
+export declare function isBranchMergedInto(branch: string, into: string): boolean;
 export declare function addWorktree(path: string, branch: string): void;
 /** Create a worktree in detached HEAD mode at a given ref. */
 export declare function addWorktreeDetached(path: string, ref: string): void;

package/dist/git.js

@@ -78,6 +78,39 @@ export function remoteBranchExists(name) {
 export function deleteRemoteBranch(name) {
     git("push", "origin", "--delete", name);
 }
+/**
+ * Check if all changes from `branch` are present in `into`.
+ * Handles regular merges, squash merges, and rebase merges.
+ *
+ * 1. Fast path: branch tip is an ancestor of `into` (regular merge / ff).
+ * 2. Content check: every file the branch changed has identical content in
+ *    `into`. This catches squash and rebase merges where SHAs differ but
+ *    the content is the same.
+ */
+export function isBranchMergedInto(branch, into) {
+    // Fast path — works for regular merges and fast-forwards
+    try {
+        git("merge-base", "--is-ancestor", branch, into);
+        return true;
+    }
+    catch {
+        // Not an ancestor — may still be squash/rebase merged
+    }
+    // Content check — compare files the branch changed against `into`
+    try {
+        const mergeBase = git("merge-base", into, branch);
+        const changedOutput = git("diff", "--name-only", mergeBase, branch);
+        if (!changedOutput)
+            return true; // branch has no file changes
+        const files = changedOutput.split("\n");
+        const contentDiff = git("diff", into, branch, "--", ...files);
+        return contentDiff.length === 0;
+    }
+    catch {
+        // If anything fails (e.g. branch already deleted), assume not merged
+        return false;
+    }
+}
 export function addWorktree(path, branch) {
     git("worktree", "add", path, branch);
 }

package/dist/install-hooks.js

@@ -93,9 +93,17 @@ const RULES_CONTENT = `# Git Stint Workflow
 All file edits are intercepted by git-stint hooks and redirected to isolated
 worktrees. One stint session = one branch = one PR.
 
+## Session Naming
+
+When creating a session, pick a short descriptive name that captures the task:
+- Good: \`fix-auth-refresh\`, \`add-user-search\`, \`refactor-db-queries\`
+- Bad: \`session-1\`, \`changes\`, \`test\`, \`update\`
+
+The name becomes the branch (\`stint/<name>\`) and the PR title context.
+
 ## Session Lifecycle
 
-- Session auto-creates on first Write/Edit (via PreToolUse hook).
+- If the hook blocks a write, create a session: \`git stint start <descriptive-name>\`
 - All edits redirect to \`.stint/<session>/\` worktree.
 - \`git stint commit -m "msg"\` to commit logical units of work.
 - \`git stint pr\` to push and create PR.
@@ -103,6 +111,10 @@ worktrees. One stint session = one branch = one PR.
 
 ## Rules
 
+- **NEVER end or delete a stint session you didn't create.** Other sessions
+  belong to other conversations or agents. Only operate on your own session
+  (the one auto-created by the hook for your edits). Use \`git stint list\` to
+  see all sessions — leave others alone.
 - Do NOT call \`git stint end\` until all changes are committed (code, tests,
   config updates, follow-up tasks). Premature \`end\` kills the session; the
   next edit auto-creates a NEW session, fragmenting work across multiple PRs.

package/dist/session.js

@@ -696,15 +696,58 @@ function cleanup(manifest, force = false) {
             }
         }
     }
+    // Check if remote branch should be cleaned up (before deleting local branch,
+    // since we need it for the merge check).
+    //
+    // IMPORTANT: We check against REMOTE tracking refs (origin/main), not local
+    // branches. A local `git stint merge` merges into local main, but the user
+    // may not have pushed yet. Deleting the remote session branch before the
+    // remote main has the changes would destroy the only remote copy of the work.
+    // By checking origin/main, we only delete when the remote already has the
+    // changes — matching how GitHub/GitLab auto-delete works.
+    let shouldDeleteRemote = false;
+    if (git.remoteBranchExists(manifest.branch)) {
+        // Build list of remote tracking refs to check against.
+        const targets = new Set();
+        const defaultBranch = git.getDefaultBranch();
+        targets.add(`origin/${defaultBranch}`);
+        try {
+            const current = git.currentBranch(topLevel);
+            if (current !== manifest.branch && git.remoteBranchExists(current)) {
+                targets.add(`origin/${current}`);
+            }
+        }
+        catch { /* detached HEAD — skip */ }
+        for (const target of targets) {
+            if (git.isBranchMergedInto(manifest.branch, target)) {
+                shouldDeleteRemote = true;
+                break;
+            }
+        }
+        if (!shouldDeleteRemote) {
+            console.log(`Remote branch 'origin/${manifest.branch}' was NOT deleted (has unmerged changes).\n` +
+                `  To delete manually: git push origin --delete ${manifest.branch}`);
+        }
+    }
     // Delete local branch
     try {
         git.deleteBranch(manifest.branch);
     }
     catch { /* branch may already be deleted */ }
-    // Delete remote tracking ref if it exists (no network call — just local ref).
-    // We intentionally do NOT delete the remote branch itself:
-    // the user may have an open PR. They can clean up with `git push origin --delete`.
-    // The local tracking ref is cleaned up by `git branch -D` above.
+    // Delete remote branch if all changes are merged
+    if (shouldDeleteRemote) {
+        try {
+            git.deleteRemoteBranch(manifest.branch);
+            console.log(`Deleted remote branch 'origin/${manifest.branch}'.`);
+        }
+        catch {
+            // Branch may already be deleted on the remote (e.g., GitHub auto-delete
+            // after PR merge) or the network may be down. Either way, not critical.
+            console.log(`Could not delete remote branch 'origin/${manifest.branch}'.\n` +
+                `  It may have already been deleted (e.g., by GitHub after PR merge).\n` +
+                `  To delete manually: git push origin --delete ${manifest.branch}`);
+        }
+    }
     // Delete manifest last — if anything above fails, manifest persists for prune
     deleteManifest(manifest.name);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "git-stint",
-  "version": "0.2.4",
+  "version": "0.3.1",
   "description": "Session-scoped change tracking for AI coding agents",
   "type": "module",
   "bin": {