git-stint 0.5.0 → 0.6.1

package/README.md

@@ -152,6 +152,8 @@ Create a `.stint.json` in your repo root:
 ```json
 {
   "shared_dirs": ["node_modules", ".venv", "dist"],
+  "shared_files": [".env", ".python-version"],
+  "post_create": ["uv sync"],
   "main_branch_policy": "block",
   "force_cleanup": "prompt",
   "adopt_changes": "always"
@@ -161,6 +163,8 @@ Create a `.stint.json` in your repo root:
 | Field | Values | Default | Description |
 |-------|--------|---------|-------------|
 | `shared_dirs` | `string[]` | `[]` | Directories to symlink from worktree to main repo. Use for gitignored dirs (caches, build outputs) that shouldn't be duplicated per session. |
+| `shared_files` | `string[]` | `[]` | Files to symlink from main repo into each new worktree. Like `shared_dirs` but for individual files — use for untracked config files (`.env.keys`, `service-account.json`) that should stay in sync with main. |
+| `post_create` | `string[]` or `string` | `[]` | Shell command(s) to run in the new worktree after creation. Use for project setup (e.g., `uv sync`, `pip install -r requirements.txt`). Commands run sequentially; failures warn but don't abort session creation. |
 | `main_branch_policy` | `"block"` / `"prompt"` / `"allow"` | `"prompt"` | What happens when an agent writes to main. `"block"` auto-creates a session. `"prompt"` blocks with instructions. `"allow"` passes through. |
 | `force_cleanup` | `"force"` / `"prompt"` / `"fail"` | `"prompt"` | Behavior when worktree removal fails. |
 | `adopt_changes` | `"always"` / `"never"` / `"prompt"` | `"always"` | Whether uncommitted changes on main carry into new sessions. |
@@ -188,6 +192,30 @@ git stint start my-feature --adopt       # Force adopt regardless of config
 git stint start my-feature --no-adopt    # Skip regardless of config
 ```
 
+### Shared Files
+
+Like `shared_dirs` but for individual files. Symlinks each file from main into the worktree so changes stay in sync:
+
+```json
+{
+  "shared_files": [".env.keys", "service-account.json", "config/local.yaml"]
+}
+```
+
+Files that don't exist are skipped with a warning. Files already present in the worktree (e.g., tracked by git) are not overwritten. Symlinked files are automatically added to the worktree's `.gitignore`.
+
+### Post-Create Hooks
+
+Run setup commands automatically after worktree creation. Commands execute in the new worktree directory:
+
+```json
+{
+  "post_create": ["uv sync", "cp .env.example .env"]
+}
+```
+
+A single string is also accepted: `"post_create": "npm install"`. Commands run sequentially. A failing command prints a warning but does not prevent session creation — subsequent commands still run.
+
 ## How It Works
 
 ### Session Model

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

@@ -94,6 +94,8 @@ if [ -f "$STINT_CONFIG" ]; then
 fi
 
 # The file is NOT in a stint worktree. Check if any stint session exists.
+SOLE_SESSION=""
+SESSION_COUNT=0
 SESSIONS_DIR="$(git rev-parse --git-common-dir 2>/dev/null)/sessions"
 if [ -d "$SESSIONS_DIR" ]; then
   MY_WORKTREE=""
@@ -134,7 +136,22 @@ if [ -d "$SESSIONS_DIR" ]; then
   fi
 
   # No session matches our clientId, but other sessions exist.
-  # Don't hijack them — fall through to create our own session.
+  # With "block" policy: auto-resume the sole session (common case: Claude Code
+  # restarted with a new PID). With multiple sessions, still auto-create.
+  if [ -n "$OTHER_SESSIONS" ]; then
+    SOLE_SESSION=""
+    SESSION_COUNT=0
+    for manifest in "$SESSIONS_DIR"/*.json; do
+      [ -f "$manifest" ] || continue
+      case "$manifest" in *.tmp) continue ;; esac
+      SESSION_COUNT=$((SESSION_COUNT + 1))
+      if command -v jq &>/dev/null; then
+        SOLE_SESSION=$(jq -r '.name // empty' "$manifest" 2>/dev/null || true)
+      else
+        SOLE_SESSION=$(grep -o '"name"[[:space:]]*:[[:space:]]*"[^"]*"' "$manifest" | head -1 | sed 's/.*"name"[[:space:]]*:[[:space:]]*"//;s/"$//')
+      fi
+    done
+  fi
 fi
 
 # No session for this client — check main_branch_policy before auto-creating.
@@ -151,13 +168,39 @@ if [ "$MAIN_BRANCH_POLICY" = "prompt" ]; then
     exit 0
   fi
   echo "BLOCKED: Writing to main branch." >&2
+  if [ -n "$SOLE_SESSION" ] && [ "$SESSION_COUNT" -eq 1 ] 2>/dev/null; then
+    echo "Active session found: $SOLE_SESSION" >&2
+    echo "To resume: git stint resume $SOLE_SESSION" >&2
+  fi
   echo "To allow, run: git stint allow-main --client-id $CLIENT_ID" >&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
 
-# Policy is "block" (or default) — auto-start a session, then block so agent retries in worktree.
+# Policy is "block" — auto-resume if exactly one session exists, otherwise auto-create.
+if [ -n "$SOLE_SESSION" ] && [ "$SESSION_COUNT" -eq 1 ] 2>/dev/null; then
+  # One session exists from a previous client — auto-resume it
+  RESUME_OUTPUT=$(git-stint resume "$SOLE_SESSION" --client-id "$CLIENT_ID" 2>&1) || {
+    # Resume failed — fall through to auto-create
+    SOLE_SESSION=""
+  }
+fi
+
+if [ -n "$SOLE_SESSION" ] && [ "$SESSION_COUNT" -eq 1 ] 2>/dev/null; then
+  # Resume succeeded — extract worktree and redirect
+  WORKTREE_PATH=$(echo "$RESUME_OUTPUT" | grep -o 'Worktree:.*' | sed 's/Worktree:[[:space:]]*//')
+  if [ -z "$WORKTREE_PATH" ]; then
+    WORKTREE_PATH="$REPO_ROOT/.stint/$SOLE_SESSION"
+  fi
+  echo "git-stint: Resumed session '${SOLE_SESSION}' (new client: ${CLIENT_ID})." >&2
+  echo "All edits must target the worktree: $WORKTREE_PATH" >&2
+  echo "Rewrite your file path from: $FILE_PATH" >&2
+  echo "To: ${WORKTREE_PATH}/${FILE_PATH#$REPO_ROOT/}" >&2
+  exit 2
+fi
+
+# No session to resume (0 or 2+ sessions) — auto-create a new one.
 SESSION_NAME="session-$(date +%Y%m%d-%H%M%S)"
 CLIENT_FLAG=""
 if [ -n "$CLIENT_ID" ]; then

package/dist/cli.js

@@ -132,6 +132,16 @@ try {
             session.abort(getFlag("--session"));
             break;
         }
+        case "resume": {
+            const name = getPositional(0);
+            if (!name) {
+                console.error("Usage: git stint resume <session-name>");
+                process.exit(1);
+            }
+            const clientId = getFlag("--client-id");
+            session.resume(name, clientId);
+            break;
+        }
         case "undo": {
             session.undo(getFlag("--session"));
             break;
@@ -254,6 +264,7 @@ Commands:
   squash -m "msg"           Collapse all commits into one
   merge                     Merge session into main (no PR)
   pr [--title "..."]        Push branch and create GitHub PR
+  resume <name>             Rebind session to current client (after restart)
   end                       Finalize session, clean up everything
   abort                     Discard session — delete all changes
   undo                      Revert last commit, changes become pending

package/dist/config.d.ts

@@ -1,5 +1,7 @@
 export interface StintConfig {
     shared_dirs: string[];
+    shared_files: string[];
+    post_create: string[];
     main_branch_policy: "prompt" | "allow" | "block";
     force_cleanup: "prompt" | "force" | "fail";
     adopt_changes: "always" | "never" | "prompt";

package/dist/config.js

@@ -2,6 +2,8 @@ import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 const DEFAULTS = {
     shared_dirs: [],
+    shared_files: [],
+    post_create: [],
     main_branch_policy: "block",
     force_cleanup: "prompt",
     adopt_changes: "always",
@@ -30,6 +32,15 @@ export function loadConfig(repoRoot) {
     if (Array.isArray(obj.shared_dirs)) {
         config.shared_dirs = obj.shared_dirs.filter((d) => typeof d === "string" && d.length > 0);
     }
+    if (Array.isArray(obj.shared_files)) {
+        config.shared_files = obj.shared_files.filter((f) => typeof f === "string" && f.length > 0);
+    }
+    if (Array.isArray(obj.post_create)) {
+        config.post_create = obj.post_create.filter((c) => typeof c === "string" && c.length > 0);
+    }
+    else if (typeof obj.post_create === "string" && obj.post_create.length > 0) {
+        config.post_create = [obj.post_create];
+    }
     if (typeof obj.main_branch_policy === "string" && VALID_POLICIES.has(obj.main_branch_policy)) {
         config.main_branch_policy = obj.main_branch_policy;
     }

package/dist/install-hooks.js

@@ -83,6 +83,8 @@ export function install(scope) {
 }
 const DEFAULT_CONFIG = {
     shared_dirs: [],
+    shared_files: [],
+    post_create: [],
     main_branch_policy: "block",
     force_cleanup: "prompt",
     adopt_changes: "always",
@@ -104,6 +106,10 @@ The name becomes the branch (\`stint/<name>\`) and the PR title context.
 ## Session Lifecycle
 
 - If the hook blocks a write, create a session: \`git stint start <descriptive-name>\`
+- **Resuming**: If a session already exists from a previous conversation, resume it
+  instead of creating a new one: \`git stint resume <session-name>\`
+  Use \`git stint list\` to see active sessions. With \`block\` policy, the hook
+  auto-resumes when exactly one session exists.
 - Any uncommitted files on main are automatically carried into the new session.
   Do NOT redo work that was already written — it is adopted into the worktree.
 - All edits redirect to \`.stint/<session>/\` worktree.
@@ -126,6 +132,12 @@ The name becomes the branch (\`stint/<name>\`) and the PR title context.
 - Directories listed under \`shared_dirs\` in \`.stint.json\` are symlinked into
   worktrees pointing to the main repo's real directories. They must never be
   staged or committed. The hooks auto-add them to the worktree's \`.gitignore\`.
+
+## Runtime
+
+- Run tests and services from the worktree (your CWD), not the main repo. If
+  you spot paths or dependencies resolving back to main, warn the user.
+- Use a non-default port to avoid collisions with other sessions.
 `;
 function scaffoldConfig(repoRoot) {
     const configPath = join(repoRoot, ".stint.json");

package/dist/session.d.ts

@@ -20,6 +20,14 @@ export declare function listJson(): void;
 export declare function prune(): void;
 /** Clean up allow-main flags for PIDs that are no longer running. */
 export declare function pruneAllowMainFlags(): void;
+/**
+ * Resume an existing session by rebinding it to the current client.
+ * Updates the clientId so hooks route writes to this session's worktree.
+ *
+ * @param name - Session name to resume
+ * @param clientId - Explicit client ID. If not provided, falls back to process.ppid.
+ */
+export declare function resume(name: string, clientId?: string): void;
 /**
  * Create per-process flag file allowing writes to main branch.
  * Scoped to a client ID (typically Claude Code's PID), so other

package/dist/session.js

@@ -3,7 +3,7 @@ import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, statSync,
 import { dirname, join, resolve } from "node:path";
 import * as git from "./git.js";
 import { loadConfig } from "./config.js";
-import { BRANCH_PREFIX, WORKTREE_DIR, MANIFEST_VERSION, saveManifest, deleteManifest, listManifests, resolveSession, getWorktreePath, getRepoRoot, } from "./manifest.js";
+import { BRANCH_PREFIX, WORKTREE_DIR, MANIFEST_VERSION, loadManifest, saveManifest, deleteManifest, listManifests, resolveSession, getWorktreePath, getRepoRoot, } from "./manifest.js";
 // --- Constants ---
 const WIP_MESSAGE = "WIP: session checkpoint";
 // --- Name generation ---
@@ -123,6 +123,19 @@ export function start(name, clientId, adoptOverride) {
     }
     // Adopt uncommitted changes from main repo (before symlinking, to avoid conflicts)
     const config = loadConfig(topLevel);
+    // Snapshot shared_files and .stint.json BEFORE adopt stash (which moves
+    // untracked files out of main). Without this, session 2 would find .env
+    // missing because session 1's adopt already moved it.
+    const configPath = join(topLevel, ".stint.json");
+    const configSnapshot = existsSync(configPath) ? readFileSync(configPath) : null;
+    const sharedFileSnapshots = new Map();
+    for (const file of config.shared_files) {
+        const source = resolve(topLevel, file);
+        if (!source.startsWith(topLevel + "/"))
+            continue;
+        if (existsSync(source))
+            sharedFileSnapshots.set(file, readFileSync(source));
+    }
     const shouldAdopt = adoptOverride !== undefined
         ? adoptOverride
         : config.adopt_changes === "always";
@@ -155,6 +168,17 @@ export function start(name, clientId, adoptOverride) {
             }
         }
     }
+    // Restore .stint.json and shared_files to main after adopt stash moved them
+    if (configSnapshot && !existsSync(configPath)) {
+        writeFileSync(configPath, configSnapshot);
+    }
+    for (const [file, content] of sharedFileSnapshots) {
+        const source = resolve(topLevel, file);
+        if (!existsSync(source)) {
+            mkdirSync(dirname(source), { recursive: true });
+            writeFileSync(source, content);
+        }
+    }
     // Symlink shared directories from config (after adopt, so stash pop doesn't conflict with symlinks)
     const linkedDirs = [];
     for (const dir of config.shared_dirs) {
@@ -201,6 +225,71 @@ export function start(name, clientId, adoptOverride) {
             }
         }
     }
+    // Symlink shared files from main repo into worktree.
+    const linkedFiles = [];
+    for (const file of config.shared_files) {
+        const source = resolve(topLevel, file);
+        if (!source.startsWith(topLevel + "/")) {
+            console.warn(`Warning: shared_files entry '${file}' escapes repo root, skipping.`);
+            continue;
+        }
+        const target = resolve(worktreeAbs, file);
+        if (!existsSync(source)) {
+            console.warn(`Warning: shared_files entry '${file}' not found in repo, skipping.`);
+            continue;
+        }
+        if (existsSync(target)) {
+            if (lstatSync(target).isSymbolicLink())
+                continue; // already symlinked
+            // Only replace untracked files (e.g., from adopt stash-pop).
+            // Git-tracked files keep their worktree version.
+            try {
+                git.gitInDir(worktreeAbs, "ls-files", "--error-unmatch", file);
+                continue; // tracked by git — don't replace
+            }
+            catch { /* untracked — safe to replace */ }
+            unlinkSync(target);
+        }
+        mkdirSync(dirname(target), { recursive: true });
+        symlinkSync(source, target);
+        linkedFiles.push(file);
+    }
+    // Prevent shared_files symlinks from being staged
+    if (linkedFiles.length > 0) {
+        const gitignorePath = join(worktreeAbs, ".gitignore");
+        const markerStart = "# git-stint shared_files (auto-generated, do not commit)";
+        const markerEnd = "# end git-stint shared_files";
+        let giContent = existsSync(gitignorePath) ? readFileSync(gitignorePath, "utf-8") : "";
+        const entries = linkedFiles.join("\n");
+        const block = `${markerStart}\n${entries}\n${markerEnd}`;
+        if (giContent.includes(markerStart)) {
+            const regex = new RegExp(`${markerStart.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}[\\s\\S]*?` +
+                `(?:${markerEnd.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}|$)`);
+            giContent = giContent.replace(regex, block);
+        }
+        else {
+            giContent = giContent.endsWith("\n") ? giContent + "\n" + block + "\n" : giContent + "\n\n" + block + "\n";
+        }
+        writeFileSync(gitignorePath, giContent);
+        for (const f of linkedFiles) {
+            try {
+                git.gitInDir(worktreeAbs, "rm", "--cached", "--ignore-unmatch", f);
+            }
+            catch { /* best effort */ }
+        }
+    }
+    // Run post_create hooks in the new worktree
+    for (const cmd of config.post_create) {
+        try {
+            execFileSync("sh", ["-c", cmd], { cwd: worktreeAbs, stdio: ["pipe", "pipe", "pipe"], timeout: 300_000 });
+        }
+        catch (err) {
+            const e = err;
+            const stderr = e.stderr ? e.stderr.toString().trim() : (e.message || "unknown error");
+            console.warn(`Warning: post_create command failed: ${cmd}`);
+            console.warn(`  ${stderr}`);
+        }
+    }
     // Revoke main-branch write pass when entering session mode
     removeAllowMainFlag();
     // Create manifest
@@ -225,6 +314,12 @@ export function start(name, clientId, adoptOverride) {
             console.log(`  ${dir} → ${resolve(topLevel, dir)}`);
         }
     }
+    if (linkedFiles.length > 0) {
+        console.log(`\nShared files (symlinked from main repo):`);
+        for (const f of linkedFiles) {
+            console.log(`  ${f} \u2192 ${resolve(topLevel, f)}`);
+        }
+    }
     if (adoptedFiles > 0) {
         console.log(`\nCarried over ${adoptedFiles} uncommitted file(s) into session.`);
     }
@@ -680,6 +775,17 @@ function cleanup(manifest, force = false) {
             }
             catch { /* best effort */ }
         }
+        for (const file of config.shared_files) {
+            const target = resolve(worktree, file);
+            if (!existsSync(target))
+                continue;
+            try {
+                if (lstatSync(target).isSymbolicLink()) {
+                    unlinkSync(target);
+                }
+            }
+            catch { /* best effort */ }
+        }
     }
     // Remove worktree
     if (existsSync(worktree)) {
@@ -796,6 +902,53 @@ export function pruneAllowMainFlags() {
     if (cleaned > 0)
         console.log(`Cleaned ${cleaned} stale allow-main flag(s).`);
 }
+/**
+ * Resume an existing session by rebinding it to the current client.
+ * Updates the clientId so hooks route writes to this session's worktree.
+ *
+ * @param name - Session name to resume
+ * @param clientId - Explicit client ID. If not provided, falls back to process.ppid.
+ */
+export function resume(name, clientId) {
+    if (!git.isInsideGitRepo()) {
+        throw new Error("Not inside a git repository.");
+    }
+    if (!name || name.trim().length === 0) {
+        throw new Error("Session name is required. Usage: git stint resume <name>");
+    }
+    const manifest = loadManifest(name);
+    if (!manifest) {
+        throw new Error(`Session '${name}' not found.\n` +
+            `Run 'git stint list' to see active sessions.`);
+    }
+    // Verify the worktree still exists
+    const worktree = getWorktreePath(manifest);
+    if (!existsSync(worktree)) {
+        throw new Error(`Worktree missing for session '${name}' at ${worktree}.\n` +
+            `Run 'git stint prune' to clean up, then start a new session.`);
+    }
+    const newClientId = clientId || String(process.ppid);
+    // Check if already bound to this client
+    if (manifest.clientId === newClientId) {
+        console.log(`Session '${name}' is already bound to client ${newClientId}.`);
+        console.log(`\ncd "${worktree}"`);
+        return;
+    }
+    const oldClientId = manifest.clientId;
+    manifest.clientId = newClientId;
+    saveManifest(manifest);
+    console.log(`Session '${name}' resumed.`);
+    if (oldClientId) {
+        console.log(`  Client: ${oldClientId} \u2192 ${newClientId}`);
+    }
+    else {
+        console.log(`  Client: ${newClientId}`);
+    }
+    console.log(`  Branch:   ${manifest.branch}`);
+    console.log(`  Worktree: ${worktree}`);
+    console.log(`  Commits:  ${manifest.changesets.length}`);
+    console.log(`\ncd "${worktree}"`);
+}
 /**
  * Create per-process flag file allowing writes to main branch.
  * Scoped to a client ID (typically Claude Code's PID), so other

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "git-stint",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "Session-scoped change tracking for AI coding agents",
   "type": "module",
   "bin": {
@@ -51,6 +51,6 @@
   "license": "MIT",
   "devDependencies": {
     "typescript": "^5.7.0",
-    "@types/node": "^22.0.0"
+    "@types/node": "^25.3.5"
   }
 }