my-pi/pi-permission-system/docs/plans/archive/0013-consolidate-session-start-handlers.md

issue, issue_title

issue	issue_title
13	Consolidate duplicate session_start handlers in index.ts

Consolidate duplicate session_start handlers

Problem Statement

src/index.ts registers two session_start event handlers (lines ~1566 and ~1584) that perform identical setup work. The only difference is that the first handler also logs a lifecycle.reload debug entry when event.reason === "reload". Every startup side effect therefore runs twice per session start, and contributors must remember to update both handlers or behaviour silently diverges. This is documented as a known caveat in AGENTS.md under "Runtime Caveats".

Goals

• Merge the two session_start handlers into a single handler that preserves the lifecycle.reload debug log branch.
• Ensure startup side effects execute exactly once per session start.
• Remove the "Runtime Caveats" note from AGENTS.md since the workaround is no longer needed.

Non-Goals

• Refactoring other event handlers (resources_discover, agent_start, etc.) — out of scope.
• Extracting the shared setup into a named helper function — nice-to-have but not required by the issue; defer unless the single handler is unwieldy.

Background

• Origin: discovered during the #6 retro (docs/retro/0006-log-resolved-config-paths.md), where logResolvedConfigPaths() had to be added to both handlers.
• Permission surface: none — this is a pure lifecycle/startup concern with no policy semantics.
• Affected file: src/index.ts only (plus AGENTS.md docs).

The two handlers currently share these calls:

runtimeContext = ctx;
refreshExtensionConfig(ctx);
permissionManager = createPermissionManagerForCwd(ctx.cwd);
invalidateAgentStartCache();
lastKnownActiveAgentName = getActiveAgentName(ctx);
startForwardedPermissionPolling(ctx);
logResolvedConfigPaths();

Handler 1 additionally includes:

if (event.reason === "reload") {
  writeDebugLog("lifecycle.reload", {
    triggeredBy: "session_start",
    reason: event.reason,
    cwd: ctx.cwd,
  });
}

Handler 2 has no unique logic.

Design Overview

Delete the second pi.on("session_start", ...) block entirely. The first handler already contains every statement from the second plus the reload branch — no merging of logic is needed, only deletion of the duplicate.

No types, schemas, or config surfaces change.

Module-Level Changes

File	Change
src/index.ts	Remove the second session_start handler (currently lines ~1584–1592).
AGENTS.md	Remove the "Runtime Caveats" section that documents the dual-handler workaround.

TDD Order

1. Red → Green: add a test (or manual verification script) that asserts session_start side effects run exactly once per event. Surface: integration/event lifecycle. Commit: test: verify session_start side effects run once

2. Green → Refactor: delete the duplicate handler in src/index.ts. Commit: fix: consolidate duplicate session_start handlers (#13)

3. Docs: remove the "Runtime Caveats" section from AGENTS.md. Commit: docs: remove dual-handler caveat from AGENTS.md (#13)

Risks and Mitigations

Risk	Mitigation
Could this silently weaken a permission?	No — no permission decisions are made in the session_start handler; it only initialises the PermissionManager and caches. Running setup once is strictly more correct than running it twice.
Removing the wrong handler loses the reload log	The plan explicitly keeps handler 1 (which contains the reload branch) and deletes handler 2 (which is a strict subset). Review the diff to confirm.
Future contributors re-introduce a second handler	The AGENTS.md caveat removal eliminates the "keep both in sync" instruction, so there is no longer guidance that implies two handlers are expected.

Open Questions

• Extract a named helper? If future issues add more session_start work, extracting initializeSession(event, ctx) would improve readability. Defer unless the single handler grows beyond ~15 lines.