foregroundSleepDenial function

String? foregroundSleepDenial(String command, { required bool canJob, })

The instructive validation denial for a bare long foreground sleep, or null when the command may run in the foreground. The caller gates on timeout == null (an explicit timeout is a deliberate bail cap — the call unwinds there, steering and cancel included) and passes canJob so the escape advice matches what the environment actually offers — background advice would dead-end in a no-jobs host.

Implementation

String? foregroundSleepDenial(String command, {required bool canJob}) {
  final seconds = bareForegroundSleepSeconds(command);
  if (seconds == null || seconds <= maxForegroundSleepSeconds) return null;
  final label = seconds == seconds.truncateToDouble()
      ? '${seconds.truncate()}'
      : '$seconds';
  final escape = canJob
      ? 'Re-run it with background: true: the command keeps running as a '
            'job, the job id returns immediately, and a settle notification '
            'wakes you when it finishes; collect progress with bash_job '
            '(action: output).'
      : 'Background jobs are not supported in this environment; bound the '
            'wait with an explicit timeout (seconds) instead — the call '
            'unwinds at the cap, so steering and cancel can reach you.';
  return 'Denied: a bare foreground sleep of ${label}s parks the whole '
      'turn — owner steering and cancel cannot reach the agent while the '
      'call stays open. $escape Never poll in the foreground.';
}