예외의 길

# backend/services/turn_clock.py:125-156 (cwkPippa)
def failure_reason(exc: BaseException) -> str:
    """What ``failed:<reason>`` names: an HTTP refusal by its status, a
    request that went away, or any other error."""
    status = getattr(exc, "status_code", None)
    if isinstance(status, int):
        return f"http_{status}"
    if isinstance(exc, asyncio.CancelledError):
        return "cancelled"
    return "error"


def marks_failure(endpoint: Callable[..., Awaitable[T]]) -> Callable[..., Awaitable[T]]:
    """Wrap a chat route so a turn that fails before its stream starts leaves
    the board as ``done`` / ``failed:<reason>`` (todo #598): a 404 for a
    conversation the viewer may not write, a 500 for a row that would not
    save, or any error in the preparation. ``functools.wraps`` keeps the
    route's signature visible to FastAPI. The stream reports its own end."""

    @functools.wraps(endpoint)
    async def wrapper(*args: Any, **kwargs: Any) -> T:
        token = _route_turn.set(None)
        try:
            return await endpoint(*args, **kwargs)
        except BaseException as exc:
            clock = _route_turn.get()
            if clock is not None:
                clock.failed(failure_reason(exc))
            raise
        finally:
            _route_turn.reset(token)

    return wrapper

// clients/apple/PippaMobile/Sources/AppModel.swift:4966-4979 (cwkPippa)
    /// A spoken turn failed (todo #598): after a provider error mid-reply the
    /// turn stayed awaited, the lines it had streamed kept a `spokenUnits`
    /// entry, the mic never opened again and the last stage line stood frozen
    /// until Dad tapped twice. It leaves the gate and the line now, and the
    /// talk listens again once nothing of hers is sounding. Only the first time
    /// the failure is seen: a failed record stays in the outbox, and every
    /// later drain must not reopen the mic under a newer turn.
    private func spokenTurnFailed(_ turnId: String) {
        let awaited = spokenReplies.forget(turnId)
        spokenUnits[turnId] = nil
        guard awaited else { return }
        if voiceStageTurnId == turnId || voiceStage?.turnId == turnId { clearVoiceStage() }
        if !voice.isReading { resumeHandsFree() }
    }

// A sketch, not cwkPippa's code: the ways a spoken turn can fail, and the named
// state each one must end in. The rule it checks: a real failure is never
// silent, and "nothing to speak" is not a failure at all.

type Failure =
  | { kind: 'turnFailed'; reason: string; firstSeen: boolean }   // provider error mid-reply
  | { kind: 'sendDropped'; attempt: number }                     // a transient link drop
  | { kind: 'streamLost'; cursor: number }                       // web: the stream died mid-answer
  | { kind: 'routeChanged'; heardSeconds: number }               // AirPods moved, a call came
  | { kind: 'takeFailed'; how: 'neverSounded' | 'stalled' | 'brokeOff'; restarted: boolean;
      detail: string; privately: boolean }                      // a take in a hands-free talk
  | { kind: 'nothingToSpeak' };                                  // a lone ```spark block

interface Outcome {
  record: string | null;   // what the engine or the talk's record keeps
  screen: string | null;   // the one line Dad sees
  next: string;            // the state the turn moves on to
}

const RETRY_SECONDS = [5, 15, 45, 60];   // the last delay repeats

function retryAfter(attempt: number): number {
  return RETRY_SECONDS[Math.min(attempt, RETRY_SECONDS.length - 1)];
}

/** Words Dad can act on, from the error's own text; never the HTTP chain. */
function plainCause(detail: string): string {
  const text = detail.toLowerCase();
  if (/timed out|stalled|no audio in time/.test(text)) return 'her voice took too long to arrive';
  if (/offline|connection was lost|network/.test(text)) return 'the link to Pippa dropped';
  if (/\b5\d\d\b/.test(text)) return 'the voice service failed';
  if (/\b4\d\d\b/.test(text)) return 'the voice service refused it';
  return 'her voice did not come through';
}

export function settle(f: Failure): Outcome {
  switch (f.kind) {
    case 'turnFailed':
      // Only the first sighting frees the talk; a later drain must not reopen
      // the mic under a newer turn.
      return f.firstSeen
        ? { record: `stage board: done / failed:${f.reason}`, screen: null, next: 'gate forgets the turn; listening again' }
        : { record: null, screen: null, next: 'unchanged (already settled)' };
    case 'sendDropped':
      return { record: null, screen: `Link dropped, sending again in ${retryAfter(f.attempt)} s`, next: 'queued' };
    case 'streamLost':
      return { record: null, screen: 'Connection lost — following her answer',
               next: `read the stored reply from character ${f.cursor}` };
    case 'routeChanged':
      return { record: null, screen: null,
               next: `same take from ${Math.max(0, f.heardSeconds - 0.5).toFixed(1)} s` };
    case 'takeFailed': {
      // A stream that never sounded falls back to the finished take, except in a
      // private talk, which keeps no finished take: there the first failure is said.
      if (f.how === 'neverSounded' && !f.privately)
        return { record: null, screen: 'Her voice came from the finished take: the live stream did not open.',
                 next: 'play the finished take (take_failed if it fails too)' };
      // A stall (no audio for 20 s) is asked for again once, from where she was heard.
      if (f.how === 'stalled' && !f.restarted)
        return { record: null, screen: null, next: 'reopen the take at the heard position' };
      // A second stall, or any other break, is said at once.
      const voiced = f.how !== 'neverSounded';
      const cause = voiced ? 'audio_error' : 'take_failed';
      const line = voiced
        ? `Her voice stopped early: ${plainCause(f.detail)}.`
        : `Part of her answer was not read aloud: ${plainCause(f.detail)}.`;
      return { record: f.privately ? null : `voice_reading_stopped cause=${cause}`, screen: line, next: 'the next unit' };
    }
    case 'nothingToSpeak':
      return { record: null, screen: null, next: 'the next unit, silently' };
  }
}

const cases: Failure[] = [
  { kind: 'turnFailed', reason: 'http_500', firstSeen: true },
  { kind: 'turnFailed', reason: 'http_500', firstSeen: false },
  { kind: 'sendDropped', attempt: 0 },
  { kind: 'sendDropped', attempt: 7 },
  { kind: 'streamLost', cursor: 412 },
  { kind: 'routeChanged', heardSeconds: 37.2 },
  { kind: 'takeFailed', how: 'neverSounded', restarted: false, detail: 'HTTP 504', privately: false },
  { kind: 'takeFailed', how: 'neverSounded', restarted: false, detail: 'HTTP 504', privately: true },
  { kind: 'takeFailed', how: 'stalled', restarted: false, detail: 'stalled 20 s', privately: false },
  { kind: 'takeFailed', how: 'stalled', restarted: true, detail: 'stalled 20 s', privately: true },
  { kind: 'takeFailed', how: 'brokeOff', restarted: false, detail: 'the network connection was lost', privately: false },
  { kind: 'nothingToSpeak' },
];

for (const f of cases) {
  const o = settle(f);
  console.log(f.kind.padEnd(15), '| record:', o.record ?? '-', '| screen:', o.screen ?? '-', '| next:', o.next);
  // Only a first stall is asked for again in silence; every other failed take says so on screen.
  const retrying = f.kind === 'takeFailed' && f.how === 'stalled' && !f.restarted;
  if (f.kind === 'takeFailed' && !retrying && !o.screen) throw new Error('a failed take went silent');
}