Add strict current-tab session lookup for PTK_AGENT workflow methods

[k4sperski]

Issues

Related to discussion in #85
Phase 3a of the PTK Agent integration.
Builds on the workflow wrapper from #90 and the DAST stop/stale-session fixes from #91

Description

PTK_AGENT workflow methods now only see the session that belongs to the current tab. PTK_AUTOMATION behaviour is unchanged by default.

What changed:

• startScan(), scanStatus(), stopScan(), getFindings(), and exportFullReport() pass sessionScope: "current-tab" to the background automatically
• background handlers that the workflow layer depends on now resolve sessions through a shared _resolveSessionForRequest() instead of each doing their own tab/global lookup
• a tab with a starting, running, or stopping session is treated as busy — startScan() will reject until that session finishes
• startScan() now verifies the new session is reachable before returning success, so startup failures surface immediately instead of on the next status poll
• scanStatus() with an explicit sessionId that is not found now returns a failure instead of silently mapping it to { status: "none" }
• PTK_AUTOMATION can use the same strict lookup by passing sessionScope: "current-tab", but does not do so by default

Design choices:

1. PTK_AGENT and PTK_AUTOMATION have different defaults on purpose — agent callers get current-tab only, low-level callers keep the existing fallback chain so nothing breaks
2. Strict lookup lives on the existing methods (sessionScope option) rather than adding separate strict APIs — fewer methods, same backward compatibility
3. A tab in stopping state blocks new starts. The tradeoff is you cannot restart immediately while a stop is in progress, but it prevents two sessions running in the same tab
4. Phase 3a only covers which tab a session belongs to. Status normalisation, human-readable error messages, and canonical status enums stay in phase 3b so each piece can be reviewed on its own
5. Tests are split across two files: automationBridge.test.js covers what the page-facing bridge sends and normalises, automation.test.js covers how the background resolves sessions and applies lookup rules. Failures point straight to which layer broke

Known limitations:

• New background handlers need to call _resolveSessionForRequest() explicitly. A follow-up can tighten this so it is harder to skip.

Demo

// PTK_AGENT stays on the current tab by default
await window.PTK_AGENT.startScan({ project: "demo", engines: ["DAST"] })
await window.PTK_AGENT.scanStatus()
await window.PTK_AGENT.stopScan()
await window.PTK_AGENT.getFindings({ limit: 25 })
await window.PTK_AGENT.exportFullReport({ engine: "DAST" })

// PTK_AUTOMATION keeps existing behaviour
await window.PTK_AUTOMATION.getFindings(25)

// strict lookup is available on the low-level API, but opt-in
await window.PTK_AUTOMATION.getFindings({
  limit: 25,
  sessionScope: "current-tab"
})

// PTK_AGENT rejects sessions that don't belong to this tab
await window.PTK_AGENT.scanStatus({ sessionId: "other-tab-session" })
// → { ok: false, code: "session_not_found", message: "No PTK session is available for this tab" }

How Has This Been Tested?

node --test test/automationBridge.test.js test/automation.test.js test/dastSessionCoordinator.test.js

29 new tests covering:

• current-tab scope injection for all PTK_AGENT workflow methods
• startScan() verification round-trip and early failure on startup errors
• scanStatus() explicit sessionId lookup kept as failure when not found
• blocking session end flows through to stopAutomationSession()
• foreign-session rejection in the background
• unchanged PTK_AUTOMATION compatibility behaviour
• busy detection for starting, running, and stopping
• strict and compatibility paths for progress, findings, and export resolution
• stale pointer cleanup when active, completed-tab, or completed-global entries go missing

Checklist

• I have performed a self-review of my own code
• I have added tests to cover my changes