Function onHappySessionWebhook

cli/src/runner/run.ts:216–281

(sessionId: string, sessionMetadata: Metadata)

    // Handle webhook from HAPI session reporting itself
    const onHappySessionWebhook = (sessionId: string, sessionMetadata: Metadata) => {
      logger.debugLargeJson(`[RUNNER RUN] Session reported`, sessionMetadata);

      const pid = sessionMetadata.hostPid;
      if (!pid) {
        logger.debug(`[RUNNER RUN] Session webhook missing hostPid for sessionId: ${sessionId}`);
        return;
      }

      logger.debug(`[RUNNER RUN] Session webhook: ${sessionId}, PID: ${pid}, started by: ${sessionMetadata.startedBy || 'unknown'}`);
      logger.debug(`[RUNNER RUN] Current tracked sessions before webhook: ${Array.from(pidToTrackedSession.keys()).join(', ')}`);

      // Check if we already have this PID (runner-spawned)
      const existingSession = pidToTrackedSession.get(pid);

      if (existingSession && existingSession.startedBy === 'runner') {
        // Update runner-spawned session with reported data
        existingSession.happySessionId = sessionId;
        existingSession.happySessionMetadataFromLocalWebhook = sessionMetadata;
        logger.debug(`[RUNNER RUN] Updated runner-spawned session ${sessionId} with metadata`);

        // Resolve any awaiter for this PID
        const awaiter = pidToAwaiter.get(pid);
        if (awaiter) {
          pidToAwaiter.delete(pid);
          pidToErrorAwaiter.delete(pid);
          awaiter(existingSession);
          logger.debug(`[RUNNER RUN] Resolved session awaiter for PID ${pid}`);
        }
      } else if (!existingSession) {
        // No tracked session for this PID. Two possibilities:
        //  1. The child was spawned externally from a terminal (legitimate).
        //  2. The child was runner-spawned but already had its tracking
        //     entry removed because its webhook arrived after the timeout
        //     (orphaned / ghost-session case).
        //
        // Differentiate via the webhook's own `startedBy` field: genuine
        // terminal-launched children report `startedBy: 'terminal'`, so
        // anything claiming `'runner'` here must be the second case and
        // should be ignored + terminated instead of silently promoted.
        if (sessionMetadata.startedBy === 'runner') {
          logger.debug(
            `[RUNNER RUN] Ignoring late webhook from orphaned runner-spawned PID ${pid} (session ${sessionId}). Terminating child.`
          );
          // Use killProcess (SIGTERM → SIGKILL escalation) rather than a
          // bare process.kill() so the orphan is reliably reaped even if
          // it ignores SIGTERM.  We don't have a ChildProcess reference
          // here (tracking entry was already removed by the timeout
          // handler), so tree-kill via killProcessByChildProcess is not
          // available — but the timeout handler should have already
          // tree-killed the process group; this is defence-in-depth.
          void killProcess(pid);
          return;
        }

        // New session started externally (terminal)
        const trackedSession: TrackedSession = {
          startedBy: 'hapi directly - likely by user from terminal',