bug(agents): unguarded sessionManager read makes launches crash without a session manager

[danielgap]

Before submitting

• I searched open and closed issues and did not find a report of this problem.
• I reviewed this report and removed credentials, tokens, private paths, hostnames, and other sensitive data.

Problem

The #1064 launch seam reads the parent session id with ctx.sessionManager.getSessionId() in extensions/gentle-agents.ts, while every other binding reader guards the access (ctx.sessionManager?.getSessionId?.() in extensions/gentle-ai.ts). The optional-chaining pattern elsewhere treats sessionManager as possibly absent, but the launch path makes it load-bearing: a host context that provides no sessionManager throws on the unguarded dereference before the launch queues.

Raised as advisory R3-unguarded-session-id-read (suggestion) by the review-reliability lens during the native review of PR #1558.

Steps to reproduce

1. Construct the writer launch path (task-request creation) with an extension context that omits sessionManager, as test harnesses do.
2. Queue a subagent launch.
3. The unguarded ctx.sessionManager.getSessionId() read fails instead of treating the session as unbound.

Expected and actual behavior

Expected: the launch seam guards the read like the panel, status, and usage seams, and a missing sessionManager resolves to an unbound session.
Actual: the direct call makes sessionManager a hard requirement for every launch.

gentle-pi version

Unreleased: feat/1064-session-effective-routing at 4ffe4f9 (PR #1558).

Pi version

1.0.0

Operating system

Linux

Relevant logs or error output (optional)

No response

[carlosmoradev]

Good catch from the review lens, @danielgap.

Since readSessionProfileBinding in lib/session-profile-binding.ts is already typed to accept string | undefined and returns undefined when sessionId === undefined, the fix in PR #1558 is a clean one-liner:

const sessionBinding = readSessionProfileBinding(ctx.sessionManager?.getSessionId?.());

When sessionManager is omitted (such as in headless test harnesses or synthetic contexts), it safely yields undefined and falls through to the profile pin / global routing layers instead of throwing a TypeError.

[danielgap]

Update from turning the proposed one-liner into a RED test: the unguarded surface is wider than this report claimed, and the launch path assumes a parent session structurally, so the scope here is full sessionless-launch tolerance, not the guard swap.

What the RED test showed: with sessionManager absent from the extension context, subagent_run never reaches the getSessionId() read this issue pointed at. It crashes earlier in roots() at extensions/gentle-agents.ts:1187 (ctx.sessionManager.getCwd()), and behind that sit parentCwd (line 1215), parentWorktreeRoot (1286), and the mid-launch identity guards (1303) that compare ctx.sessionManager by design. A one-line ?. on getSessionId leaves the same TypeError one call earlier.

So the real contract question for this issue: what should a launch from a sessionless host mean? Options as I see them:

• Full sessionless tolerance: roots() falls back to ctx.cwd, the session binding read stays optional (this is where the original one-liner lands), the worktree registry and task attribution get a sessionless mode, and the 1303 identity guards degrade to their non-session invariants. This is a real refactor of the launch seam's session model.
• Explicit contract: launches require a parent session, and the seam fails fast at entry with a clear error instead of a deep TypeError. Small, but it forecloses headless/synthetic hosts that carlosmoradev's comment describes.

@carlosmoradev your one-liner is exactly right for the getSessionId read and it is where this started, but it cannot land alone, and it does not belong in #1558 (that PR is scoped to session-binding resolution and is holding for merge). I am scoping the full-tolerance version here as its own slice; maintainer call needed on which contract is wanted before implementation lands in a PR.