fix: warn when an agent commit lands with no Entire session recorded

PrepareCommitMsg only logged a debug line when it found no session to
attach a commit to, so the failure (agent session started outside the
worktree, drifted hook config, an incompatible entire on PATH, etc.)
was invisible until a user later noticed nothing had been recorded.

Print a visible, rate-limited stderr warning instead, but only when a
known coding-agent env marker is present (CLAUDECODE, GEMINI_CLI,
COPILOT_CLI, PI_CODING_AGENT) and no session anywhere in the repo has
recorded recent activity, so a plain human commit or a healthy
multi-worktree agent workflow never triggers it.

Fixes #1965

Author: suhaanthayyil

cmd/entire/cli/interactive/interactive.go

@@ -85,6 +85,30 @@ func isAgentSubprocessEnv() bool {
 		os.Getenv("GIT_TERMINAL_PROMPT") == "0"
 }
 
+// HasAgentEnvMarker reports whether the environment carries a marker set by a
+// known coding agent's own process. This answers a different question from
+// isAgentSubprocessEnv above: that one decides "can this process prompt on
+// its inherited TTY" (and so also honors GIT_TERMINAL_PROMPT=0, a caller
+// preference rather than an agent identity); this one decides "is a coding
+// agent actually driving this process", used where misidentifying a human's
+// own commit as agent-driven would be the worse mistake (issue #1965: warning
+// when a commit lands with no Entire session recording it).
+//
+//   - CLAUDECODE=1: Claude Code sets this in the environment of every command
+//     it runs.
+//   - GEMINI_CLI=1, COPILOT_CLI=1, PI_CODING_AGENT=true: see
+//     isAgentSubprocessEnv.
+//
+// Markers for other integrations (Cursor, Factory AI Droid, OpenCode, Codex)
+// are not yet verified here and are deliberately omitted rather than guessed:
+// omission means "not detected", not "definitely not an agent".
+func HasAgentEnvMarker() bool {
+	return os.Getenv("CLAUDECODE") != "" ||
+		os.Getenv("GEMINI_CLI") != "" ||
+		os.Getenv("COPILOT_CLI") != "" ||
+		os.Getenv("PI_CODING_AGENT") != ""
+}
+
 // IsTerminalReader reports whether r is an *os.File backed by a terminal.
 // It is useful when an explicitly interactive command needs to distinguish a
 // human at stdin from an agent process that merely inherited a controlling TTY.

cmd/entire/cli/strategy/agent_no_session_warn_test.go

@@ -0,0 +1,174 @@
+package strategy
+
+import (
+	"bytes"
+	"context"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/entireio/cli/cmd/entire/cli/agent"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// Issue #1965: when a coding agent commits in an Entire-enabled repo but no
+// session anywhere in the repository has recorded recent activity (e.g. the
+// agent was launched from a bare-clone layout's shared root, outside any
+// worktree, so its hooks never fired), PrepareCommitMsg used to only log a
+// debug line invisible to a normal user before silently skipping the commit.
+// These tests exercise the real hook handler (not a hand-mocked call) end to
+// end and assert a visible stderr warning now appears.
+
+// writeEnabledSettings writes a minimal .entire/settings.json with
+// "enabled": true, matching what `entire enable` produces and what the
+// PersistentPreRun gate in hooks_git_cmd.go requires before any git-hook
+// command reaches the strategy layer in a real invocation.
+func writeEnabledSettings(t *testing.T, dir string) {
+	t.Helper()
+	entireDir := filepath.Join(dir, ".entire")
+	require.NoError(t, os.MkdirAll(entireDir, 0o755))
+	require.NoError(t, os.WriteFile(
+		filepath.Join(entireDir, "settings.json"),
+		[]byte(`{"enabled":true}`),
+		0o644,
+	))
+}
+
+// TestPrepareCommitMsg_AgentCommitNoSession_WarnsVisibly is the core
+// regression test for #1965. Setup: a real temp repo (testutil.InitRepo via
+// setupGitRepo), Entire enabled, CLAUDECODE=1 (the real env marker Claude
+// Code sets on every command it runs), and deliberately NO session state
+// anywhere (.git/entire-sessions/ is never populated - no InitializeSession
+// call). PrepareCommitMsg is invoked directly - the actual function a real
+// prepare-commit-msg git hook invocation reaches - with a real commit message
+// file, and stderr is captured through the package's real injectable
+// stderrWriter (the same seam warnStaleEndedSessions already uses).
+//
+// On the fixed code this must produce a visible warning. Run against the
+// pre-fix code (git stash the strategy fix), the captured buffer is empty:
+// the only trace was the debug-level "prepare-commit-msg: no active
+// sessions" log line, invisible to a user reading their terminal.
+func TestPrepareCommitMsg_AgentCommitNoSession_WarnsVisibly(t *testing.T) {
+	dir := setupGitRepo(t)
+	t.Chdir(dir)
+	writeEnabledSettings(t, dir)
+	t.Setenv("CLAUDECODE", "1")
+
+	s := &ManualCommitStrategy{}
+
+	commitMsgFile := filepath.Join(t.TempDir(), "COMMIT_EDITMSG")
+	require.NoError(t, os.WriteFile(commitMsgFile, []byte("fix: something\n"), 0o644))
+
+	var buf bytes.Buffer
+	oldWriter := stderrWriter
+	stderrWriter = &buf
+	defer func() { stderrWriter = oldWriter }()
+
+	err := s.PrepareCommitMsg(context.Background(), commitMsgFile, "")
+	require.NoError(t, err)
+
+	t.Logf("captured stderr: %q", buf.String())
+
+	assert.Contains(t, buf.String(), "no active Entire session",
+		"a coding-agent commit with no session recorded anywhere in the repo must print a visible stderr warning (issue #1965)")
+	assert.Contains(t, buf.String(), "entire doctor",
+		"the warning should point the user at `entire doctor`")
+}
+
+// TestPrepareCommitMsg_HumanCommitNoSession_NoWarn pins the other half of the
+// enabled-but-no-session vs no-agent-at-all distinction: with Entire enabled,
+// no session anywhere, but NO agent env marker set (an ordinary human running
+// `git commit` by hand), the warning must stay silent. This is
+// indistinguishable from "no agent running at all" and must never nag a
+// human's own commit.
+func TestPrepareCommitMsg_HumanCommitNoSession_NoWarn(t *testing.T) {
+	dir := setupGitRepo(t)
+	t.Chdir(dir)
+	writeEnabledSettings(t, dir)
+	// Force-clear every known agent env marker: this test asserts the
+	// no-agent-at-all case, and the test process itself may be running
+	// inside an actual agent session (e.g. this very fix was developed under
+	// Claude Code, which sets CLAUDECODE=1 in its own subprocess env) - that
+	// ambient marker must not leak into "no agent" test coverage.
+	t.Setenv("CLAUDECODE", "")
+	t.Setenv("GEMINI_CLI", "")
+	t.Setenv("COPILOT_CLI", "")
+	t.Setenv("PI_CODING_AGENT", "")
+
+	s := &ManualCommitStrategy{}
+
+	commitMsgFile := filepath.Join(t.TempDir(), "COMMIT_EDITMSG")
+	require.NoError(t, os.WriteFile(commitMsgFile, []byte("fix: something\n"), 0o644))
+
+	var buf bytes.Buffer
+	oldWriter := stderrWriter
+	stderrWriter = &buf
+	defer func() { stderrWriter = oldWriter }()
+
+	err := s.PrepareCommitMsg(context.Background(), commitMsgFile, "")
+	require.NoError(t, err)
+
+	t.Logf("captured stderr: %q", buf.String())
+
+	assert.Empty(t, buf.String(),
+		"a human commit with no agent env marker must never warn, even with no session recorded")
+}
+
+// TestPrepareCommitMsg_AgentCommitWithSession_NoWarn is the mandatory
+// regression guard: a real session with recent activity in THIS worktree
+// (initialized via the real InitializeSession turn-start path, not a
+// hand-built state) must suppress the warning entirely - PrepareCommitMsg
+// takes the "sessions found" branch and never reaches the no-session warning
+// at all.
+func TestPrepareCommitMsg_AgentCommitWithSession_NoWarn(t *testing.T) {
+	dir := setupGitRepo(t)
+	t.Chdir(dir)
+	writeEnabledSettings(t, dir)
+	t.Setenv("CLAUDECODE", "1")
+
+	s := &ManualCommitStrategy{}
+
+	sessionID := "test-session-1965-present"
+	require.NoError(t, s.InitializeSession(context.Background(), sessionID, agent.AgentTypeClaudeCode, "", "working on a fix", ""))
+
+	state, err := s.loadSessionState(context.Background(), sessionID)
+	require.NoError(t, err)
+	require.NotNil(t, state.LastInteractionTime, "InitializeSession's turn-start transition should stamp LastInteractionTime")
+
+	commitMsgFile := filepath.Join(t.TempDir(), "COMMIT_EDITMSG")
+	require.NoError(t, os.WriteFile(commitMsgFile, []byte("fix: something\n"), 0o644))
+
+	var buf bytes.Buffer
+	oldWriter := stderrWriter
+	stderrWriter = &buf
+	defer func() { stderrWriter = oldWriter }()
+
+	err = s.PrepareCommitMsg(context.Background(), commitMsgFile, "")
+	require.NoError(t, err)
+
+	t.Logf("captured stderr: %q", buf.String())
+
+	assert.Empty(t, buf.String(),
+		"an agent commit with a recently-active session present must not warn")
+}
+
+// TestWarnIfAgentCommitHasNoSession_RateLimit pins the sentinel-file rate
+// limit, mirroring TestWarnStaleEndedSessions_RateLimit's pattern.
+func TestWarnIfAgentCommitHasNoSession_RateLimit(t *testing.T) {
+	dir := setupGitRepo(t)
+	t.Chdir(dir)
+	t.Setenv("CLAUDECODE", "1")
+	ctx := context.Background()
+
+	s := &ManualCommitStrategy{}
+
+	var buf bytes.Buffer
+	s.warnIfAgentCommitHasNoSessionTo(ctx, &buf)
+	assert.Contains(t, buf.String(), "no active Entire session")
+
+	buf.Reset()
+	s.warnIfAgentCommitHasNoSessionTo(ctx, &buf)
+	assert.Empty(t, buf.String(), "second call within window must be suppressed")
+}

cmd/entire/cli/strategy/manual_commit_hooks.go

@@ -395,6 +395,11 @@ func (s *ManualCommitStrategy) PrepareCommitMsg(ctx context.Context, commitMsgFi
 			slog.String("strategy", "manual-commit"),
 			slog.String("source", source),
 		)
+		if err == nil {
+			// Only warn on a proven-empty listing, not on a listing error —
+			// we can't claim "no session" when we don't actually know.
+			s.warnIfAgentCommitHasNoSession(ctx)
+		}
 		return nil
 	}
 	findSessionsSpan.End()
@@ -848,6 +853,98 @@ func warnStaleEndedSessionsTo(ctx context.Context, count int, w io.Writer) {
 	)
 }
 
+// agentCommitNoSessionWarnInterval/File rate-limit the warning below the same
+// way staleEndedSessionWarnInterval/File do: a sentinel file's mtime under
+// entire-sessions/, shared across worktrees (session state already is), so
+// the warning re-appears at most once per window rather than on every commit
+// while the underlying cause (e.g. an agent session started outside any
+// worktree) persists.
+const (
+	agentCommitNoSessionWarnInterval = 24 * time.Hour
+	agentCommitNoSessionWarnFile     = ".warn-agent-no-session"
+)
+
+// warnIfAgentCommitHasNoSession prints a rate-limited, visible warning when a
+// coding agent appears to be driving this commit but no session anywhere in
+// the repository (any worktree) has recorded recent activity — the "this
+// commit will not be linked to any session" case from issue #1965. It is
+// called from PrepareCommitMsg's "no active sessions" branch, which is the
+// exact point where the only trace of the condition used to be a debug-only
+// log line no normal user would ever see.
+//
+// The condition is deliberately cause-agnostic. "Agent committing, nothing
+// recorded" is reachable many ways — the agent session started outside this
+// worktree (e.g. a bare-clone layout's shared root), the git hooks are
+// registered but the entire binary they invoke fails to parse this repo's
+// settings, hook config drifted out of the agent's own settings file, or
+// session state was wiped mid-conversation by `entire clean` — and at the
+// moment of the commit this hook already has everything needed to notice the
+// shared symptom without having to diagnose which cause produced it.
+//
+// Firing requires all three, each independently necessary:
+//
+//  1. An agent env marker is present (interactive.HasAgentEnvMarker). A human
+//     typing `git commit` with no agent involved never warns — this is the
+//     line between "Entire enabled but no session recording" (worth a
+//     warning) and "no agent running at all" (indistinguishable from an
+//     ordinary human commit, and must stay silent).
+//  2. No session anywhere in the repository shows recent activity
+//     (isRecentInteraction against LastInteractionTime). The caller already
+//     knows sessions matched to *this* worktree/identity came up empty; this
+//     re-checks the full listing because a live session in a sibling
+//     worktree (task fan-out, an isolated review checkout, an agent cd-ing
+//     between worktrees) is a deliberate, healthy shape — `entire session
+//     adopt` already covers moving it — and warning there would mostly nag
+//     power users rather than catch a real miss.
+//  3. Not rate-limited (see the sentinel-file constants above), fail-open on
+//     any file error exactly like warnStaleEndedSessions.
+//
+// settings.IsSetUpAndEnabled is intentionally NOT re-checked here: the sole
+// caller reaches this strategy method through the `entire hooks git` command
+// tree, which already refuses to invoke any hook handler at all when Entire
+// is not set up and enabled for the repo (hooks_git_cmd.go's
+// PersistentPreRun sets gitHooksDisabled and returns before RunE). A
+// disabled or never-configured repo therefore never reaches this function.
+func (s *ManualCommitStrategy) warnIfAgentCommitHasNoSession(ctx context.Context) {
+	s.warnIfAgentCommitHasNoSessionTo(ctx, stderrWriter)
+}
+
+func (s *ManualCommitStrategy) warnIfAgentCommitHasNoSessionTo(ctx context.Context, w io.Writer) {
+	if !interactive.HasAgentEnvMarker() {
+		return
+	}
+
+	states, err := s.listAllSessionStates(ctx)
+	if err != nil {
+		return // fail-open: couldn't prove "no session", so don't claim it
+	}
+	for _, state := range states {
+		if isRecentInteraction(state.LastInteractionTime) {
+			return // a session is live somewhere in the repo — stay quiet
+		}
+	}
+
+	root, err := gitdir.Open(ctx)
+	if err != nil {
+		return // fail-open
+	}
+	warnFile := session.SessionStateDirName + "/" + agentCommitNoSessionWarnFile
+	if info, statErr := root.Lstat(warnFile); statErr == nil {
+		if time.Since(info.ModTime()) < agentCommitNoSessionWarnInterval {
+			return // rate-limited
+		}
+	}
+	//nolint:errcheck // Best-effort warning — fail-open if file ops fail
+	_ = osroot.MkdirAllNoSymlink(root, session.SessionStateDirName, 0o750)
+	//nolint:errcheck // Best-effort sentinel file write
+	_ = jsonutil.WriteFileAtomicIn(root, warnFile, []byte{}, 0o644)
+	fmt.Fprint(w,
+		"\nentire: warning: a commit was made but no active Entire session was found — "+
+			"this commit will not be linked to any session.\n"+
+			"Run 'entire doctor' if this is unexpected.\n\n",
+	)
+}
+
 // activeSessionInteractionThreshold is the maximum age of LastInteractionTime
 // for an ACTIVE session to be considered genuinely active. 24h is generous
 // because LastInteractionTime only updates at TurnStart, not per-tool-call.